Skip to main content
The simplest way to give an agent a tool. Add an http block to a tool on your stored agent, and AssemblyAI calls the endpoint whenever the model invokes the tool. There’s no tool.call/tool.result round trip in your client; your app just streams audio. 
{
  "name": "get_weather",
  "description": "Get current weather for a location. Use this whenever the user asks about weather, temperature, or conditions.",
  "parameters": {
    "type": "object",
    "properties": {
      "latitude":  { "type": "number", "description": "Latitude in decimal degrees, e.g. 48.85." },
      "longitude": { "type": "number", "description": "Longitude in decimal degrees, e.g. 2.35." }
    },
    "required": ["latitude", "longitude"]
  },
  "execution_mode": "interactive",
  "timeout_seconds": 30,
  "http": {
    "url": "https://api.example.com/weather",
    "http_method": "GET",
    "headers": { "Authorization": "Bearer <secret>" }
  }
}
Add it when you create or update the agent. parameters is a JSON Schema object (the same format as function tools), so the accuracy hints (enum, examples, pattern, format) work here too.

​
How arguments map to the request

The model’s arguments are placed into the request based on the HTTP method:
MethodWhere arguments go
GET, DELETEQuery string. Each value stringified; null values dropped.
POST, PUT, PATCHJSON body. Native types preserved (numbers, nested objects).
Query params already in the tool url are merged with the model’s arguments, so you can pin fixed params in the URL and let the model fill the dynamic ones. The response body (capped at 8 KiB) is fed back to the model as the tool result.

​
Securing and constraining HTTP tools

  • Auth headers are write-only. Values in http.headers are encrypted at rest and returned masked as "***". Put API keys and bearer tokens here.
  • https and public hosts only. Requests to private, loopback, or link-local addresses are blocked; redirects are not followed.
  • Errors reach the model as text. A timeout or non-2xx returns a short message the model can recover from, so write your API to return useful error bodies, and tell the agent in its system_prompt how to handle a failure (for example, apologize and ask the caller to try again, or offer an alternative).
See the Manage agents reference for the full schema.

​
Make them more accurate

Everything on the Tools overview applies to HTTP tools: