Client-Side Tools

When a tool needs access to local data, user permissions, or browser APIs, it has to run in your app rather than on the server. Client-side tools let you define custom functions that the model can call during a conversation.

How It Works

You send a message with tool definitions attached. When the model decides to call a tool, the SDK executes your function locally, sends the result back to the model, and the model continues with that information. In auto-execute mode, the SDK handles this entire flow automatically.

Tool Definition

Each tool needs a name and description to help the model decide when to use it, a parameters schema using JSON Schema, and an executor function with your code:

const tools = [{
  type: "function",
  name: "get_weather",
  description: "Get current weather for a location",
  parameters: {
    type: "object",
    properties: {
      location: { type: "string", description: "City name" }
    },
    required: ["location"]
  },
  executor: async (args) => {
    const response = await fetch(`/api/weather?city=${args.location}`);
    return response.json();
  }
}];
 
await sendMessage({
  content: "What's the weather in SF?",
  clientTools: tools,
});

Pass tools through useChat for basic tool calling, or useChatStorage for tool calling with message persistence.

Execution Modes

By default, auto-execute mode runs your function automatically and continues the conversation seamlessly.

For cases where you want user confirmation before executing a tool, use manual mode. The onToolCall callback gives you control over whether and how the tool runs:

const { sendMessage } = useChat({
  onToolCall: (toolCall) => {
    if (confirm(`Allow ${toolCall.name}?`)) {
      // Execute and continue manually
    }
  },
});

Pre-Built Tools

The SDK includes tools for Google Calendar (list, create, update events) and Google Drive (search, read files). These require user OAuth and run client-side only.