HTTP vs client tools

Both let an agent do something. They differ in where the code runs.

	HTTP	Client
Runs on	Your server	Your app, over WebSocket
Works on	Every call type	Browser and WebSocket only
Latency	Server round-trip	No round-trip
Timeout	2.5s default, 40s max	None enforced
Secrets	Safe — server-side	Never — the user can read them
Good for	Data, mutations, integrations	UI changes, local state

Decide with these questions

Does it need a secret? → HTTP. Anything the browser can reach, the user can read. Will this agent ever answer a phone? → HTTP. There is no client on a phone call, so a client tool simply never fires. Is the thing you need only in the browser? → Client. What the user is looking at, what is in their cart, which tab is open. Is it a real mutation? → HTTP. Bookings and payments should not depend on a browser tab staying open.

The most common mistake is building a client tool for an agent that later gets a phone number. It works perfectly in testing and silently does nothing in production. If in doubt, build HTTP.

HTTP tools

{
  "type": "http",
  "name": "Check order",
  "modelToolName": "checkOrderStatus",
  "description": "Look up an order. Use when the caller asks where their order is.",
  "httpMethod": "GET",
  "baseUrlPattern": "https://api.yourcompany.com/orders/{orderId}",
  "timeout": "5s",
  "dynamicParameters": {
    "orderId": { "location": "path", "required": true,
                 "schema": { "type": "string", "description": "The order number" } }
  }
}

Internal addresses are rejected. RFC 1918 ranges, loopback, IPv6 unique-local, and link-local — including the cloud metadata endpoint at 169.254.169.254 — all fail validation.A tool is a URL the model can cause your infrastructure to call, so it cannot be aimed inward.

Client tools

No URL and no location on parameters — nothing is being placed into an HTTP request.

{
  "type": "client",
  "name": "Show product",
  "modelToolName": "showProduct",
  "description": "Scroll to and highlight a product. Use when the caller asks to see a specific item.",
  "dynamicParameters": {
    "productId": { "required": true,
                   "schema": { "type": "string", "description": "The product SKU" } }
  }
}

Then register a handler:

session.registerTool("showProduct", async ({ productId }) => {
  document.querySelector(`[data-product="${productId}"]`)
    ?.scrollIntoView({ behavior: "smooth" });
  return { result: "shown" };
});

The registered name must match modelToolName exactly. A mismatch is the most common reason a correctly-defined client tool never fires.

See Client tools for the protocol, with and without the SDK.

Using both

Nothing stops you. A retail agent might use an HTTP tool to check real stock and a client tool to highlight the item on screen — the same conversation, one fact from your database and one action in the browser.

Get started

Core concepts

Tools

Telephony

Apps & SDKs

Guides

Examples

Speech to text

Help

Decide with these questions

HTTP tools

Client tools

Using both

​Decide with these questions

​HTTP tools

​Client tools

​Using both

Decide with these questions

HTTP tools

Client tools

Using both