Client tools - Cartesia Docs

Client tools let an agent trigger actions in the connected application, such as opening a page or reading client-side state. They are available only over the WebSocket API. When the model invokes a client tool, Cartesia sends a client_tool_call event. Your application runs the function and, when required, responds with client_tool_result.

Define a client tool

{
  "type": "client",
  "name": "open_cart",
  "description": "Opens the shopping cart. Use it when the user wants to review or check out their cart.",
  "pre_tool_speech": "auto",
  "execution_mode": "async",
  "expects_response": false,
  "parameters": {
    "type": "object",
    "properties": {
      "cart_id": {
        "type": "string",
        "description": "Cart to open."
      }
    },
    "required": ["cart_id"]
  }
}

Create the tool with POST /v1/agents/tools, then attach its ID through config.tools. See Tools for the shared execution settings.

Parameters

parameters must be a JSON Schema object. Properties may use string, integer, number, boolean, or an array of one of those scalar types. String properties may include an enum. Use required to identify values the model must supply.

Response behavior

expects_response: true makes the agent wait for a client_tool_result with the same tool_call_id. Use it when the result affects the conversation.
expects_response: false completes the tool after dispatch. Use it for client-side actions that the agent does not need to confirm.

response_timeout_secs is available only when expects_response is true.

Handle a tool call

// ws is the connection from the WebSocket API quick start.
async function runTool(name, parameters) {
  if (name === "open_cart") {
    // Open the cart in your interface.
    return { opened: true, cart_id: parameters.cart_id };
  }
  throw new Error(`Unknown tool: ${name}`);
}

ws.onmessage = async (message) => {
  const event = JSON.parse(message.data);
  if (event.type !== "client_tool_call") return;

  const result = await runTool(event.tool_name, event.parameters);

  if (event.expects_response) {
    ws.send(JSON.stringify({
      type: "client_tool_result",
      tool_call_id: event.tool_call_id,
      result: JSON.stringify(result),
      is_error: false,
    }));
  }
};

Results are strings up to 4 KiB. On failure, send is_error: true with a short result that the model can act on. See the WebSocket event reference for complete event schemas.

​Define a client tool

​Parameters

​Response behavior

​Handle a tool call

Define a client tool

Parameters

Response behavior

Handle a tool call