Creating external tools

Call an HTTP API from an Agent by configuring an external Tool. Set the endpoint, request method, headers, body, and parameters in the dashboard.

Create an external Tool

Create an external Tool with these steps:

1. Click Tools in the sidebar.
2. Click Create Tool.
3. Select External API.
4. Enter a name and description. Describe what the endpoint does and when to use it.
5. Click Create Tool.
6. Configure the request and parameters on the tool page.
7. Click Save.

Configure the HTTP request

Choose GET, POST, PUT, PATCH, or DELETE in HTTP Method. The default is POST.

URL

Use {{PARAMETER_NAME}} expressions to insert parameter values into the URL. Use a URL pattern like this:

https://example.com/customers/{{CUSTOMER_ID}}
https://example.com/search?q={{QUERY}}&limit={{LIMIT}}

Replace CUSTOMER_ID, QUERY, and LIMIT with the names of parameters that you define in Parameters.

For GET requests, Runtype appends parameters that the URL does not use to the query string. It omits undefined and null values and JSON-encodes object and array values.

Headers

Add request headers in this format:

Authorization: Bearer {{secret:API_KEY}}
Content-Type: application/json
X-Custom-Header: {{HEADER_VALUE}}

Replace API_KEY with a managed secret name and HEADER_VALUE with a parameter name. Runtype sends application/json by default. Set Content-Type to another value when the endpoint requires it.

Request body

For non-GET methods, enter an optional JSON template in Body Template (Optional). Leave each parameter expression unquoted. Runtype encodes each value as JSON before it inserts the value into the body.

Use a body template like this:

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

Replace CUSTOMER_ID, NAME, and IS_ACTIVE with parameter names. Runtype preserves each value’s JSON type. Strings receive quotes, while numbers, booleans, null values, objects, and arrays retain their JSON types.

The request body renders parameter values as shown in this table:

Leave the expression bare. If NAME is a string and you write "name": "{{NAME}}", Runtype produces invalid JSON and logs a validation warning.

Runtype escapes string values before insertion. Quotes, backslashes, and control characters remain inside the JSON string.

If you leave Body Template (Optional) empty, Runtype serializes each parameter that the URL does not use into a flat JSON object for non-GET requests.

Managed secrets

Create a managed secret in Managing secrets before you add a credential reference. Use the secret name in a URL, header, or request body:

Authorization: Bearer {{secret:API_KEY}}
X-API-Key: {{secret:EXTERNAL_SERVICE_KEY}}

Replace API_KEY and EXTERNAL_SERVICE_KEY with the names of managed secrets in your account. Runtype resolves these references at request time and does not expose the secret values to the Agent or return them in tool results.

Define parameters

Define parameters that match the expressions in the URL, headers, and body with these steps:

1. Click Parameters in the tool editor.
2. Click Add Parameter.
3. Enter a name that matches the expression, without the braces.
4. Select String, Number, Boolean, Object, or Array in Type.
5. Enter a description that explains the parameter’s value.
6. Turn Required on when the Agent must provide the parameter.
7. Enter a fallback in Default Value when the parameter is optional.
8. Click Save.

Configure authentication

Use a managed secret for each credential that you send to the external API.

API key or bearer token

Add the credential to a request header with a secret reference:

Authorization: Bearer {{secret:API_KEY}}
X-API-Key: {{secret:API_KEY}}

Replace API_KEY with the managed secret name that stores the credential.

Basic authentication

For Basic authentication, store the base64-encoded username and password pair in a managed secret. Add the encoded value to the Authorization header:

Authorization: Basic {{secret:BASIC_AUTH_VALUE}}

Replace BASIC_AUTH_VALUE with the managed secret name that stores the encoded credential.

OAuth access token

For an OAuth access token, send the token as a bearer credential:

Authorization: Bearer {{secret:OAUTH_ACCESS_TOKEN}}

Replace OAUTH_ACCESS_TOKEN with the managed secret name that stores the token.

Handle responses

Runtype returns a JSON response as an object when the response includes an application/json content type. It returns other response bodies as text. A non-2xx status causes the Tool to fail and includes the status code and response body in the error.

Return structured JSON when the Agent needs to use individual response fields. Use a response like this:

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

The Agent can use fields from the returned object, such as name and tier.

Handle errors

An external Tool reports an error when one of these conditions occurs:

• The API is unreachable.
• Authentication fails with status 401 or 403.
• The API returns a rate-limit status such as 429.
• The API rejects a parameter with status 400.
• The API returns a server error with status 500 or higher.

Inspect the status code and response body to identify the failure. Update the request or the parameter values, then run the test again.

Test an external Tool

Run a test from the tool editor with these steps:

1. Open Test Tool.
2. Enter sample parameter values.
3. Click Run Test.
4. Review the returned result in the Result tab.
5. Review previous runs in the History tab.

Example tools

Use these configurations as starting points for common external Tools.

Customer lookup

Use a GET Tool to look up a customer by ID:

Name: lookup_customer
Description: Retrieves customer information by ID
Method: GET
URL: https://example.com/customers/{{CUSTOMER_ID}}
Headers:
  Authorization: Bearer {{secret:CUSTOMER_API_KEY}}
Parameters:
  - CUSTOMER_ID (string, required): Customer ID to look up

Replace CUSTOMER_ID with the parameter name and CUSTOMER_API_KEY with the managed secret name.

Create a support ticket

Use a POST Tool to create a support ticket:

Name: create_ticket
Description: Creates a support ticket in the ticketing system
Method: POST
URL: https://example.com/tickets
Headers:
  Authorization: Bearer {{secret:TICKETING_TOKEN}}
  Content-Type: application/json
Body:
{
  "subject": {{SUBJECT}},
  "description": {{DESCRIPTION}},
  "priority": {{PRIORITY}},
  "customerId": {{CUSTOMER_ID}}
}
Parameters:
  - SUBJECT (string, required): Ticket subject
  - DESCRIPTION (string, required): Detailed description
  - PRIORITY (string, required): Ticket priority
  - CUSTOMER_ID (string, required): Customer ID

Replace the parameter names with the names that you define, and replace TICKETING_TOKEN with the managed secret name.

Product search

Use a GET Tool to search a product catalog:

Name: search_products
Description: Searches a product catalog by query
Method: GET
URL: https://example.com/products/search?q={{QUERY}}&limit={{LIMIT}}
Headers:
  X-API-Key: {{secret:STORE_KEY}}
Parameters:
  - QUERY (string, required): Search query
  - LIMIT (number, default: 10): Maximum number of results

Replace QUERY and LIMIT with parameter names, and replace STORE_KEY with the managed secret name.

Best practices

Apply these practices when you configure an external Tool:

• Write a clear description that explains when to use the Tool.
• Return structured JSON when the Agent needs individual response fields.
• Document rate limits in the Tool description.
• Return error messages that identify the failure.
• Test the Tool with credentials that can call the target API before you attach it to an Agent.
• Describe side effects when the Tool creates or modifies data.
• Use managed secrets instead of hardcoding credentials in the Tool configuration.

Next steps

Continue with one of these guides:

• Agent tools: attach Tools to Agents and configure tool use
• Managing secrets: create and manage secret references
• Creating custom tools: run custom JavaScript or Python tools
• What are Tools?: compare built-in, custom, and external Tools