Make HTTP API calls as agent tools. Call tools let agents interact with REST APIs directly — the agent sends a request and gets the response back.

Basic Usage

Call tools are defined in the agent's YAML config:

yaml

1tools:2  - name: get_weather3    type: call4    description: Get current weather for a city5    call:6      method: GET7      url: https://api.weather.com/v1/current?city={{args.city}}8      input_schema:9        type: object10        properties:11          city:12            type: string13            description: City name

When the agent calls get_weather(city="London"), the runtime makes a GET request to https://api.weather.com/v1/current?city=London and returns the response body as the tool result.

How It Works

Agent decides to call the tool based on the conversation
Runtime resolves URL templates ({{context.X}}, {{args.X}})
Runtime injects auth credentials (headers, bearer token)
Request is sent and response is returned to the agent

The agent never sees credentials — auth is handled entirely by the runtime.

URL Templates

URLs support two kinds of template variables:

Syntax	Source	Resolved when
`{{context.X}}`	Per-chat context values	Chat creation
`{{args.X}}`	Tool call arguments	Each tool call

{{args.X}} values are consumed from the request body — they appear in the URL but are removed from the JSON body sent to the endpoint.

yaml

1url: https://api.example.com/projects/{{context.project_id}}/items/{{args.item_id}}

Authentication

Configure auth in the tool's call.auth section. Credentials come from your team's secrets (belt secrets set).

Bearer Token

yaml

1call:2  auth:3    type: bearer4    secret: my_api_key    # team secret name5  method: GET6  url: https://api.example.com/data

Sends Authorization: Bearer <secret_value> on every request.

API Key Header

yaml

1call:2  auth:3    type: api_key4    secret: my_api_key5    header: X-API-Key     # custom header name6  method: POST7  url: https://api.example.com/action

Integration (OAuth)

yaml

1call:2  auth:3    type: integration4    integration: google5  method: GET6  url: https://www.googleapis.com/calendar/v3/calendars/primary/events

Uses a configured OAuth integration from your team settings.

No Auth

yaml

1call:2  auth:3    type: none4  method: GET5  url: https://api.example.com/public

Input Schema

Define the tool's parameters with input_schema. This becomes the JSON Schema the LLM sees:

yaml

1call:2  method: POST3  url: https://api.example.com/search4  input_schema:5    type: object6    properties:7      query:8        type: string9        description: Search query10      limit:11        type: integer12        description: Max results to return13      filters:14        type: object15        description: Key-value filter pairs

For POST/PUT requests, the input schema fields become the JSON request body (minus any {{args.X}} values consumed by the URL).

For GET/DELETE requests, parameters can be embedded in the URL via {{args.X}} templates.

Require Approval

For destructive or expensive operations:

yaml

1tools:2  - name: delete_record3    type: call4    description: Permanently delete a record5    require_approval: true6    call:7      auth:8        type: bearer9        secret: admin_key10      method: DELETE11      url: https://api.example.com/records/{{args.id}}12      input_schema:13        type: object14        properties:15          id:16            type: string17            description: Record ID to delete

The agent pauses and waits for user confirmation before executing.

Context

Call tools work with agent context — per-chat variables declared in the agent config and passed when creating a chat.

yaml

1# Agent config2context:3  - name: project_id4    description: Project to operate on5    required: true67tools:8  - name: list_tasks9    type: call10    description: List tasks in the project11    call:12      auth:13        type: bearer14        secret: pm_api_key15      method: GET16      url: https://api.example.com/projects/{{context.project_id}}/tasks

Pass context when running the agent:

bash

1belt agent run myteam/pm-agent "list open tasks" \2  --context project_id=proj_123

Full Example

A pricing configuration agent with multiple call tools:

yaml

1name: pricing-agent2description: Configure pricing for store apps3core_app:4  ref: openrouter/claude-sonnet-4556context:7  - name: version_id8    description: Store version ID9    required: true1011tools:12  - name: get_pricing13    type: call14    description: Returns current pricing state15    call:16      auth:17        type: bearer18        secret: api_key19      method: GET20      url: https://api.example.com/versions/{{context.version_id}}/pricing2122  - name: save_draft23    type: call24    description: Save pricing config as draft25    call:26      auth:27        type: bearer28        secret: api_key29      method: PUT30      url: https://api.example.com/versions/{{context.version_id}}/pricing/draft31      input_schema:32        type: object33        properties:34          prices:35            type: object36            description: Price variables (name to value in cents)37          total_expression:38            type: string39            description: CEL expression for total fee4041  - name: publish42    type: call43    description: Promote draft to live pricing44    require_approval: true45    call:46      auth:47        type: bearer48        secret: api_key49      method: POST50      url: https://api.example.com/versions/{{context.version_id}}/pricing/publish