Call an external API

Create an API Request tool when an agent needs one request to a service you already run. You configure the endpoint, authentication, input schema, response, timeout, and failure behavior without writing code.

Prerequisites

An HTTPS endpoint that accepts the request method and JSON arguments you plan to use.
Any bearer or HMAC secret stored in your organization Vault.
Permission to manage organization tools.

Create the draft

Dashboard
API

Go to Global Tools, choose New tool, then select API Request. Enter a tool name and Instructions. Instructions maps to the API description field. Use a name made of letters, numbers, underscores, or dashes.

The New tool page with API Request highlighted — Select API Request from the New tool page

Create the draft with POST /v1/agents/tools. Replace the .example URL and Vault secret name with values for your service before testing it.

tool.json

{
  "name": "lookup_order",
  "description": "Look up the current status of a Wayne Enterprises order.",
  "tool_type": "api_request",
  "config": {
    "type": "api_request",
    "url": "https://api.wayne.example/orders/status",
    "http_method": "POST",
    "auth": {
      "type": "bearer",
      "secret_name": "WAYNE_API_TOKEN"
    },
    "headers": [
      {
        "name": "X-Client",
        "value": "voice-agent"
      }
    ],
    "parameters": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string",
          "description": "The order identifier provided by the caller"
        }
      },
      "required": ["order_id"]
    },
    "strict": true,
    "webhook_format": "raw",
    "timeout_seconds": 10,
    "wait_for_response": true,
    "response": {
      "show_to_llm": true,
      "instructions": "Tell the caller the order status and expected delivery date."
    }
  }
}

Request

curl -X POST https://api.agents.slng.ai/v1/agents/tools \
  -H "Authorization: Bearer $SLNG_API_KEY" \
  -H "Content-Type: application/json" \
  -d @tool.json

Configure the request

Dashboard
API

Set the literal HTTPS Request URL and choose the Method. The URL cannot contain credentials or a fragment.

The API Request tool editor with the Request URL field highlighted — Configure the request URL, method, and authorization

Set the literal HTTPS URL in config.url and choose GET, POST, PUT, PATCH, or DELETE in config.http_method. The URL cannot contain credentials or a fragment.

Choose None, Bearer, or HMAC authentication. Bearer and HMAC settings reference a Vault secret by its SCREAMING_SNAKE_CASE name. Do not add Authorization, X-Signature-256, Host, or other transport headers yourself.

Define the parameters

Parameters are values the model extracts from the conversation and passes to the tool. For example, a forecast tool can define a city parameter so the model passes the city mentioned by the caller.

Dashboard
API

Use Builder to add each parameter. Give it a clear name and description so the model knows which value to extract. Mark a parameter as required when the request cannot run without it.

The Parameters section of the API Request tool editor with Add parameter highlighted — Add the parameters supplied to the request

Define the JSON Schema object in config.parameters. Add every required property to required, and describe each value precisely. Set config.strict to true to reject arguments that the schema does not define.

A GET request sends arguments as query parameters. Other methods send the arguments as the raw JSON request body. Tool-level header values are literals or Vault references.

The executor builds the query string from the tool’s parameters. Pass a fixed value like an API key as a parameter, and pin it with the attachment’s argument_overrides (or a parameter enum). A query string written into config.url is dropped, so keep the key in a parameter. When you test with /run, pass the value in sample_input.

Configure the response

Dashboard
API

Show the result to the model controls whether the result enters the conversation. Use Result instructions to tell the model how to interpret it.

The Response section of the API Request tool editor with Show the result to the model highlighted — Choose how the model receives the API response

Set response.show_to_llm and response.instructions. The API also accepts timeout_seconds from 1 to 60 and wait_for_response. Keep the default wait enabled when the agent needs the result before continuing.

Test and publish

Run the draft with representative inputs. Confirm the endpoint received the expected body and returned the expected JSON. You must complete a successful test for the current draft before publishing it.

Attach the published version

Attach the version to an agent. Set whether the model or a call event invokes it on the attachment, not on the tool draft.See Attach a tool to an agent.

Handle failures

A run can fail because the endpoint times out, returns an invalid response, or rejects authentication. Keep the timeout shorter than the maximum delay a caller should hear. Add a pre-action message on the attachment when a normal response can take several seconds. If the agent does not need the response, set wait_for_response to false. This also prevents the response from being shown to the LLM. See Tools API reference for the complete request and lifecycle endpoint contracts.

Get started

Regions

Execution layer

Agent Builder

Models

Integrate

Prerequisites

Handle failures

​Prerequisites

​Handle failures

Prerequisites

Handle failures