> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/guides-and-quickstarts/using-tools-and-actions/configure-and-test-an-action.md).

# Configure and test an action

An action performs a specific operation in an external service. Its inputs tell the service what to do. Its outputs make the returned information available to later workflow steps.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FO7eoNfUV8Ieck2IKfhf0%2FG049.mp4?alt=media&token=408644c6-4251-4e82-ad33-ae736b8b6be3>" %}

## Before you start

Have a workflow with an **Input** and **Output**, plus an [authorized provider connection](https://docs.stackai.com/guides-and-quickstarts/using-tools-and-actions/create-and-manage-connections.md). If you have not built that path yet, follow [First input to output workflow](https://docs.stackai.com/guides-and-quickstarts/workflow-builder/first-input-to-output-workflow.md). Read [Map variables and expressions](https://docs.stackai.com/guides-and-quickstarts/workflow-builder/map-variables-and-expressions.md) for the reference picker.

Choose one operation from the [Provider Catalog](https://docs.stackai.com/integrations/catalog.md) and check its supported connection type, required fields, and expected return fields. For a first test, prefer a read/search operation on information you can verify in the provider. The following steps apply to that selected action; field names vary by provider.

## Select a connection

In the workflow, add the selected provider action and choose the connection for the intended account. Keep the same action while testing its inputs and mapping its output.

![Action provider connection selection](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/74QblcsaZIv04aQPVT5P/assets/g049-g049-01-baseline.png)

The connection determines which account the action uses.

Optional connection check: open **Test Action**, enter every required value directly, and run a small read request whose result you can verify. If you use a separate read action for this check, return to the action you intend to configure afterward. Otherwise, continue to **Configure the action and inputs** below before running it.

![Action provider connection selection](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/jFCLKEBCfNSFqZtCzJHC/assets/g049-g049-02-labels.png)

Resolve connection problems before adding more input mapping or downstream formatting.

## Configure the action and inputs

Connect **Input → the selected action → Output**. Open the action and fill the required fields shown in its form. For a search operation, use its documented query format; a provider search query may differ from an ordinary question.

![Action input mapping controls](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/e3GD7AMNyhacW1TfBr5N/assets/g049-g049-03-search.png)

Check that the chosen operation matches the information you need to retrieve.

For a field that should change with each request, open its reference picker and select the relevant value from **Input**. For a search action, this is usually the query or search-text field; use the field name and accepted format shown for your selected action.

![Action input mapping controls](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/yoIivgUvS772AEl0jSG2/assets/g049-g049-04-reference.png)

A live reference supplies the current request on each execution.

Use this mapping pattern to distinguish values you type once from values supplied on each run:

| Value                                                      | How to supply it                                                  | How to check it                                                                         |
| ---------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| A fixed account resource or option                         | Enter/select it directly in the action field.                     | It identifies the resource or behavior intended for every run.                          |
| A question, search term, or record identifier that changes | Select the corresponding **Input** value in the reference picker. | Two different workflow inputs produce requests with the corresponding different values. |
| Information returned by the action                         | Select the actual action result field in **Output**.              | The displayed output matches that field in the current run's result.                    |

Do not type a guessed expression or copy identifiers from a screenshot. Select fields exposed by your own workflow and use values from your own authorized account.

## Run the action directly

Use Test Action to supply the required input directly.

![Direct action test inputs](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/U4dJoLIF3Z1oSedeo2Up/assets/g049-g049-05-test-input.png)

This helps you inspect the action's behavior separately from the surrounding workflow.

## Map the output

After the direct test returns data, expand the result and identify the field needed by the user: for example, the returned record list or a specific text value. In **Output**, open the reference picker and select that field from the selected action. Use the actual field exposed by your action, not a universal field name.

![Action result output mapping](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/tJbdYyggpglc3pPtzGR6/assets/g049-g049-06-output.png)

Select the live result rather than copying a response from an earlier run.

Run the complete workflow with a query in its input.

![Action result output mapping](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/cjpMe5uYwVdgX5HhYPYN/assets/g049-g049-07-run.png)

Inspect the resulting records to confirm that the input mapping and output mapping work together.

## Resolve action errors

If the request fails, expand the error and inspect the input fields.

![Action error and retry results](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/LMvCLXTPZ2w1ZhJvfoUA/assets/g049-g049-08-error.png)

For an authorization error, [check or reconnect the account](https://docs.stackai.com/guides-and-quickstarts/using-tools-and-actions/create-and-manage-connections.md). For a missing field or invalid value, correct the named input using the action's field help and provider reference. If a full workflow fails but **Test Action** succeeds, compare the mapped input with the successful direct-test value. Before retrying an action that changes data, inspect the provider to see whether the first attempt already took effect.

Rerun the corrected request and inspect the new response.

![Action error and retry results](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/ZZA9Tk2S9gZzl0QoTZE6/assets/g049-g049-09-correct.png)

Confirm success from the actual result rather than an earlier status badge.

## Important behavior

A live reference uses values from the current run. Pasting a previous response into Output creates fixed content.

## Continue

* [Give an agent tools](https://docs.stackai.com/guides-and-quickstarts/agent-builder-and-skills/give-an-agent-tools.md)
* [Workflow debugging and node results](https://docs.stackai.com/guides-and-quickstarts/workflow-builder/workflow-debugging-and-node-results.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/guides-and-quickstarts/using-tools-and-actions/configure-and-test-an-action.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
