Creating external tools

Call any HTTP API from an Agent. External tools map Agent parameters to URL, headers, and body templates.

Create an external tool

1. Click Tools in the sidebar
2. Click Create Tool
3. Select External (HTTP API)
4. Configure:
   • Name: Unique identifier (e.g., lookup_customer)
   • Description: What the tool does and when to use it
   • URL: API endpoint
   • Method: GET, POST, PUT, DELETE (default is POST)
   • Headers: Authentication and content type
   • Parameters: Define inputs
5. Click Create

Configuring the HTTP request

URL

Use {{parameterName}} template variables for dynamic values:

https://api.example.com/customers/{{customerId}}
https://api.example.com/search?q={{query}}&limit={{limit}}

GET requests: Parameters not substituted into the URL are automatically packed into the query string.

Headers

Add authentication and content type:

Authorization: Bearer {{secret:api_key}}
Content-Type: application/json
X-Custom-Header: {{headerValue}}

Default content type is application/json if not specified.

Request body

For POST and PUT requests, define the body as JSON with {{variable}} template slots. Place each variable unquoted where its value belongs — the tool serializes the value to its correct JSON type for you.

1
{
2
  "id": {{customerId}},
3
  "name": {{name}},
4
  "active": {{isActive}},
5
  "metadata": {
6
    "source": "runtype-agent"
7
  }
8
}

Each value keeps its type, so a number stays a number and a boolean stays a boolean. The table below shows how each parameter type interpolates:

String values are escaped before they are inserted, so quotes, backslashes, and control characters in a parameter value cannot break out of their JSON context or inject new fields.

If you don’t define a body template, the tool keeps its earlier behavior: every parameter not already used in the URL path or query string is serialized into a flat JSON object.

Managed secrets

Store credentials securely with {{secret:NAME}} references. Secrets resolve at runtime and are never exposed to Agents or returned in responses:

Authorization: Bearer {{secret:api_key}}
X-API-Key: {{secret:external_service_key}}

Add secrets in Settings → Secrets, then reference them by name in headers, URL, or body.

Defining parameters

Map each parameter to a {{variable}} in the request URL, headers, or body:

1. Click + Add Parameter
2. Configure:
   • Name: Must match template variable name
   • Type: string, number, boolean, object, array
   • Description: Clear explanation for the Agent
   • Required: Whether the parameter is mandatory
   • Default: Fallback value if not providedExample: For URL https://api.example.com/customers/{{customerId}}, add parameter customerId (string, required).

Response handling

The tool returns the HTTP response body to the Agent. If the API returns a non-2xx status, the tool fails and the Agent receives the status code and response body as an error.

Ensure your API returns structured JSON that Agents can work with. Example response:

1
{
2
  "customerId": "12345",
3
  "name": "Jane Doe",
4
  "tier": "premium",
5
  "orderCount": 47
6
}

The Agent receives this object and can reference fields like response.name or response.tier.

Authentication

API key in header

Authorization: Bearer {{secret:api_key}}
X-API-Key: {{secret:service_key}}

Basic auth

If your API requires Basic Auth, base64-encode username:password and send it in the header:

Authorization: Basic 

Use managed secrets for the credentials value.

OAuth tokens

Authorization: Bearer {{secret:oauth_token}}

Error handling

External tools can fail if:

• API is unreachable
• Authentication fails (401, 403)
• Rate limits exceeded (429)
• Invalid parameters (400)
• Server errors (500+)If the API returns a non-2xx status, the tool fails and the Agent receives the status code and response body as an error. The Agent can retry with different parameters or fall back to another tool.

Testing external tools

1. Click Test on the tool page
2. Provide sample parameter values
3. Click Run Test
4. Review the HTTP request sent
5. Check the response received
6. Iterate until working correctly

Example tools

Customer lookup

Name: lookup_customer
Description: Retrieves customer information by email or ID
Method: GET
URL: https://api.yourapp.com/customers/{{customerId}}
Headers:
  Authorization: Bearer {{secret:api_key}}
Parameters:
  - customerId (string, required): Customer ID to look up

Create support ticket

Name: create_ticket
Description: Creates a support ticket in the ticketing system
Method: POST
URL: https://api.ticketing.com/v1/tickets
Headers:
  Authorization: Bearer {{secret:ticketing_token}}
  Content-Type: application/json
Body:
{
  "subject": {{subject}},
  "description": {{description}},
  "priority": {{priority}},
  "customerId": {{customerId}}
}
Parameters:
  - subject (string, required): Ticket subject
  - description (string, required): Detailed description
  - priority (string, required): Priority level (low, medium, high)
  - customerId (string, required): Customer ID

Product search

Name: search_products
Description: Searches product catalog by query
Method: GET
URL: https://api.yourstore.com/products/search?q={{query}}&limit={{limit}}
Headers:
  X-API-Key: {{secret:store_key}}
Parameters:
  - query (string, required): Search query
  - limit (number, default: 10): Max results to return

Best practices

• Clear descriptions. Help Agents understand when to use the tool.
• Validate responses. Ensure API returns usable JSON.
• Handle rate limits. Document limits in tool description.
• Meaningful errors. Return error messages Agents can understand.
• Test against the live API with real credentials before attaching the tool to an Agent.
• Document side effects. Note if tool creates or modifies data.
• Use managed secrets. Never hardcode credentials in tool configs.

Next steps

• Creating custom tools — JavaScript and Python-based tools
• Agent tools — how Agents select and invoke tools
• What are Tools? — conceptual background