HTTP tools

HTTP tools connect agents to external APIs and services to fetch data, submit forms, or trigger external services. The agent invokes the tool based on its reasoning, passing the required parameters — the platform handles authentication, request construction, and response mapping.

Configuring an HTTP tool

Navigate to Tools > + New Tool > HTTP.

Step 1: Provide basic information about the tool

Tool Name: A unique name for the tool.

Description: Brief description of the tool. This description is used by the agent to identify when to invoke the tool.

Step 2: Configure your API endpoint, authentication, and request settings

The Configuration step defines the API endpoint, authentication, and request structure. You can populate these fields manually or click Import from cURL to automatically parse a cURL command into the configuration fields.

Protocol: Select REST for standard HTTP APIs or SOAP for XML-based web services.

Endpoint: Enter the full URL of the API endpoint.

Method: Select the HTTP method for the request.

Authentication: Select the authentication method the API requires. When authentication is configured, use the Auth Profile Reference field to reference a stored auth profile. The platform resolves credentials from the auth profile at runtime. Configure auth profiles in Workspace settings under Auth Profiles.

Alternatively, provide the OAuth fields directly, as per the selected authentication method.

Query Parameters: Define key-value pairs to append to the endpoint URL. Click + Add to add a parameter.

Headers: Define custom headers to include with every request. Click + Add to add a header. You can also use variables.

**Parameters **define the inputs the LLM provides when invoking this tool. The platform uses these to construct the request payload and inform the LLM of the data it needs to supply.

Click + Add to define a parameter manually, or click Parse to auto-detect parameters from {{input.X}} references already used in the endpoint URL, headers, or query parameters.

Each parameter requires a name, a type, a description, and a required status. The description is critical, as the LLM uses it to determine what value to provide.

Advanced Settings

Advanced Settings controls the tool’s reliability and performance behavior.

Field	Default	Description
Return Type	object	The data type returned by the tool. Used in the DSL signature and LLM schema to define what the agent can expect from the tool response.
mTLS	None	Selects an mTLS profile to present a client certificate during the TLS handshake. Configure this only when the destination service requires mutual TLS authentication.
Timeout (ms)	30000	Maximum time, in milliseconds, the platform waits for the HTTP request to complete before timing out. Maximum supported value: 120000 ms.
Retries	0	Number of times the platform retries the request if it fails. Set to 0 to disable retries.
Retry Delay (ms)	1000	Time in milliseconds to wait between retry attempts.
Retry Strategy	Legacy	Determines how retry attempts are performed when a request fails.
Rate Limit/min	Unlimited	Maximum number of requests per minute. Leave blank for no limit.
Circuit Breaker	Off	Opens the circuit after consecutive request failures to prevent repeated calls to an unhealthy service. When enabled, configure the failure threshold and reset time.
Failure Threshold	5	Number of consecutive request failures required before the circuit breaker opens and temporarily blocks further requests.
Reset Time (ms)	60000	Time, in milliseconds, the circuit breaker remains open before allowing another request to determine whether the service has recovered.
Idempotency Header	None	Specifies the HTTP header used to send an idempotency key with requests. Use this when the target service supports idempotent operations to prevent duplicate processing of repeated requests.

Step 3: Testing the tool

After the tool is created, go to the Testing tab. Click Run Test and provide sample values. Validate the request sent and the response received from the service.

Attaching tool to the agent

Via UI

• Go to the **Tools **page under Agent.
• Click Attach Tool.
• Add the selected Tool.

Via DSL

• Open the agent DSL editor by clicking DSL at the top of the agent page.
• In the editor, type /http-tool to trigger the tool insertion shortcut.
• Select the tool from the list and click Insert Tool. The platform inserts the tool definition into the DSL.
• Click Compile to validate and Save to apply.