Create a custom API action for a conversation

Use a custom API action when the agent needs information or an external operation during the conversation. The destination must expose an API you are authorised to use. A custom action supplies a specific request; it does not add the full behaviour of a native connector.

You need the endpoint's method, URL, authentication requirements, input schema, response format, and a test record. Arrange these with the API owner before configuration. Use a test endpoint for writes.

For a simpler API connection, open Add next to Functions and choose Custom tool under Build your own in Add to your agent. It can call your API without the full in-call API setup.

Configure the request

1. In the call agent editor, choose Functions > Add > API call, then Add API in In-call APIs.
2. Give the action a clear, unique name, such as lookup_demo_order. Describe when the agent should use it.
3. Select the HTTP Method and enter the URL. Choose the method required by the destination; the editor supports GET, POST, PUT, PATCH, and DELETE.
4. Configure Authentication and any required headers. The authentication selector offers no authentication or basic authentication; a provider requiring a bearer token or API key may require a specific header. Use configured workspace-secret references where offered instead of putting credentials in conversation instructions.
5. Define Conversation Variables with clear descriptions of what the caller must supply. Insert the matching variable tokens into the URL, headers, or body where needed.
6. For a request body, use valid JSON matching the destination schema. Preserve the required data types: a number, boolean, object, and text value are not interchangeable.
7. Set Timeout (seconds) if required. This field uses seconds, unlike the MCP timeout field. Review Limit Successful API Calls if the operation should have a per-call success limit.
8. Use Test API with synthetic input. This editor test does not collect values from a conversation or prompt you to fill conversation variables. Supply a literal test value as described below, inspect the status and body, then capture the response fields the agent needs.
9. Save the action. Use the copy icon with the Copy prompt reference tooltip to insert the generated reference into the agent instructions where appropriate; do not invent an action reference from its display name.

Map inputs and results

Response fields can refer to nested JSON paths. Click a returned value to capture it, then check its Path and captured key. The editor uses the response field's key; it does not offer a separate rename field. A response variable is only available after its producing API has run successfully.

Try a complete read-only echo example

This example sends a fictional reference to httpbin and reads the same reference back. It demonstrates request and response mapping; it does not look up an order or change a record. httpbin's GET endpoint is documented in its API specification. Use only synthetic data and no authentication headers for this public echo service.

1. On a test agent, open Advanced Settings > Webhooks and enable Strip metadata from payloads before testing. This removes automatically added call metadata from API payloads; the echo service can still return ordinary HTTP headers and the requesting server's address.

2. Add an API named echo_demo_reference. Describe it as “Echo the caller's synthetic demo reference and return the echoed value.” Keep Run Prior to Agent Starting off, because this action needs input from the conversation.

3. Choose GET, use No Authentication, and leave custom headers empty. Enter this complete API Endpoint:

   https://httpbin.org/get?reference={{_variable.demo_reference}}
   

4. Under Conversation Variables, add demo_reference with the description “The synthetic demo reference supplied by the caller, copied exactly.”

Click to enlarge

5. For the editor test, put this literal JSON in Request Body, then choose Test API. For this GET test, these values become query parameters. Do not assume the editor test substitutes conversation tokens in the URL.

   {"reference": "DEMO-001"}
   

6. Confirm 200 OK and args.reference equal to DEMO-001. Under Response Data, click that value. Confirm Captured Variables shows key reference and path args.reference.

Click to enlarge

7. Restore Request Body to {} before saving, so the runtime example takes its reference from the URL's conversation token. Choose Save API, wait for the change to save, then reopen it to check the endpoint, conversation variable and captured path.
8. Instruct the agent: “Ask for a demo reference, run echo_demo_reference with that value, and report the echoed reference. Use the returned value {{_response.reference}}. If input is missing, ask for it. If the request fails, say you could not confirm the reference.”
9. Choose Test by text instead and send “Please echo the synthetic demo reference DEMO-002.” Expand the function's Response. Confirm HTTP 200 and args.reference equal to DEMO-002, and check that the agent reports this new value rather than the earlier test sample.

Click to enlarge

After checking the saved configuration and test result, publish the flow to make the action available on real calls.

The expected result is the same reference returned by the service and used by the agent. The screenshot is a response excerpt; the service returns additional request information. End the test when finished. Remove the test action or test agent when you no longer need it.

Complete an order-lookup example

For a test API that accepts an order reference and returns an order status:

Agree this synthetic contract with the API owner: a GET request takes a query parameter named reference, and the matching record returns the following JSON. This is an example contract for your test endpoint, not a built-in order service:

{
  "order": {
    "reference": "DEMO-ORDER-001",
    "status": "ready for collection"
  }
}

1. Define order_reference as “The order reference given by the caller.”
2. Use the owner-provided endpoint and set its reference query value to {{_variable.order_reference}}. If the endpoint already has query parameters, preserve them when adding this one.
3. Test with DEMO-ORDER-001 and confirm the response contains the expected synthetic status.
4. In the response mapping, click the nested order.status value. Confirm path order.status and captured key status. A later action can refer to {{_response.status}} after this lookup succeeds. If multiple responses use the same field name, review the keys and action order to avoid confusing their values.
5. Instruct the agent: “Ask for the order reference, run the order lookup, and explain the returned status. If no order is found or the action fails, say that you could not confirm the status.”
6. Test the conversation with both the known reference and a nonexistent one. Verify the request received by the API and the answer the agent gives.

For writes, also inspect the created or updated external record. A successful HTTP status without the intended provider result is insufficient.

For the nonexistent reference, have the API owner define the expected outcome, such as a 404 response or an explicit empty result. Ensure the agent does not reuse the earlier order's status. If the provider instead requires a POST JSON body, use its agreed schema and put the input token in the required field; changing only the method is insufficient.

Troubleshooting and maintenance

• Variable appears literally or empty: check its exact name and context, and whether it exists before the action runs. A post-call extraction result cannot supply an earlier in-call request.
• Invalid JSON or rejected field: compare the request with the endpoint schema, including nesting and required types.
• 401/403: check the authentication scheme and account permissions with the API owner.
• Timeout: inspect the API's logs and destination record before retrying a write. A timeout does not establish that nothing happened.
• API result is not used: check response mapping and the instructions that tell the agent when to use that result.
• GET editor test differs from the conversation: inspect the resolved request. Literal test-body values and automatically added metadata can replace the editor test's query string; this is separate from runtime conversation-token substitution. Restore the intended runtime configuration and test a new reference interactively.

The list supports editing, duplicating, copying a reference, and deleting an action. After a rename or deletion, update instructions and dependent response mappings. Repeat the provider test after an endpoint, credential, or response-schema change.