Skip to main content
An API request tool calls one endpoint of your system during a call, with values the agent collected from the caller. Use it to look up an order, check availability, create a ticket or anything else your API can do. This page covers every setting, how to test the tool, and the differences between single prompt and flow agents when they send the request.

Before you start

  • You need permission to create tools. See APIs & MCPs.
  • Your endpoint must be reachable from the internet over HTTPS.
  • If the API needs a key or password, store it first as a secret.

Create an API request

1

Start a new tool

Open APIs & MCPs, click Add new tool and choose API request. The form Add new API request opens.
2

Name and describe it

Enter a Tool name and a Description. Write the description for the agent: what the tool does and when to use it, for example “Looks up the status of an order. Use it when the caller asks where their order is.”
3

Set the request

Under Tool settings, enter the URL, pick the Method, and set Authentication and Headers if your API needs them.
4

Define the parameters

Under Function configuration, add the Parameters the agent should send, with a clear description for each.
5

Save and test

Click Create, then open the tool and click Test to send a sample request.
Then attach the tool to an agent: in a single prompt agent under Tools, in a flow with a Tool step. See Attach a tool to an agent.
The Add new API request form with Tool name get_order_status, a description, the URL and Method GETThe Add new API request form with Tool name get_order_status, a description, the URL and Method GET

Settings

Header names can contain letters, numbers, hyphens and underscores, and must be unique. Headers that browsers forbid (such as Cookie, Host, User-Agent or Content-Length) are refused.

Authentication

The API request form with Authentication set to Bearer token holding a secret, and an X-Store-Id headerThe API request form with Authentication set to Bearer token holding a secret, and an X-Store-Id header
To use a secret, click the key icon next to the token field and pick the secret. The field then holds {{secrets.NAME}}, and the value is filled in when the request is sent. Basic authentication can’t use a secret: the username and password are stored with the tool. Use either Authentication or your own Authorization header, not both.

Parameters

Parameters are the values the agent sends in the request. For each one, set:
  • Name: the key your API expects, for example order_id.
  • Type: string, number, boolean, array or object.
  • Description: what the value is and how to get it, for example “The 8-digit order number the caller reads from their receipt.” The agent reads it to know what to ask for.
  • Required: whether the request needs it.
  • Enum values (strings only): a fixed list of allowed values, one per line.
The Request body parameters dialog with an order_id parameter of type String, Required, and its descriptionThe Request body parameters dialog with an order_id parameter of type String, Required, and its description
The agent collects the values from the conversation. To send a value the caller never says, such as a customer ID passed when the call starts, set the parameter in the agent’s Tool configuration to a variable instead. See Change a tool for one agent.

Single prompt and flow agents

Both types of agent fill in {{variables}} and {{secrets.NAME}} in the URL, header values, token and parameter values when the request is sent. A few other things differ depending on the type of agent that calls the tool. You can build the URL from a variable, for example https://api.example.com/orders/{{order_id}}, where order_id is a variable the agent already has.

Timeouts

A request that takes longer than the tool’s Timeout fails. A single prompt agent is told the action couldn’t be completed; a flow’s Tool step takes On failure. The default of 5 seconds suits fast lookups; raise it for slower APIs, up to 60. An agent can set its own Timeout for the tool in Tool configuration.

Test the tool

Open the tool and click Test (in a flow, the Test tool button on a Tool step does the same). Enter sample values for the parameters and run it. The test shows the response, which you can use to set up the values a flow step extracts. Under Advanced configuration you can change the URL, method, authentication, headers and Request timeout (seconds) for this test only.
The test sends the request from Hamsa’s servers and fills in secrets, as calls do. If the tool uses variables that have no value yet, for example when you test it from APIs & MCPs before attaching it to an agent, Test first asks you for a value for each one, then sends the request with them filled in. The test may retry a failed request up to three times; calls don’t retry.

Change a tool for one agent

Each agent can change a tool’s settings without changing the tool for other agents. In a single prompt agent, open Tool configuration under Tools. In a flow, open the Tool step and its Tool configuration. You can change the Tool name, Tool description, URL, HTTP method, Auth type and Token, Timeout (seconds), HTTP headers, Async execution and On hold music. For each parameter, choose AI extraction (the agent collects it) or a fixed value or variable, or Disable it to leave it out of the call: the agent isn’t asked for it and it isn’t sent. You can disable a header the same way. You can also add Custom parameters and Custom headers that the tool doesn’t define. Basic authentication can’t be changed here: “Basic Authentication must be configured in the tool definition.”

Async execution

With Async execution on, the agent starts the request and carries on without waiting.
  • Single prompt agents are told the task started in the background. They never get the result, so use async only for requests whose answer the caller doesn’t need, such as logging a lead.
  • Flow agents: switching a step to async replaces On success and On failure with a single Move to transition, and the app asks you to confirm because existing connections are removed. The flow moves on at once. When the response arrives, the step’s extracted variables are still set from it, but no transition follows from the result.

How it works on a call

Single prompt agents pass the result to the model, which uses it to answer the caller: Flow agents don’t show the response to the model. A 2xx answer takes On success; anything else, including a timeout, takes On failure. To use data from the response in later steps, extract it into variables on the step. See API request step.

Good to know

  • Name tools in lowercase words joined by underscores, such as get_order_status. Single prompt agents show the name to the model in lowercase, with spaces and symbols turned into _.
  • Each save creates a new version. Agents keep their version until you click Sync to latest on the agent’s tool.
  • You can’t delete a tool while an agent uses it.

API request step

Call an API from a flow, with processing messages and extracted variables.

Secrets

Store API keys and reference them in tools.

Variables

Values you can send in a request.

APIs & MCPs

How agents use tools on a call.