Tool calls

Modern AI models can invoke tools (also called functions) to perform specific tasks like retrieving data, performing calculations, or triggering actions. Streaming tool call information to users provides visibility into what the AI is doing, creates opportunities for rich generative UI experiences, and builds trust through transparency.

​

What are tool calls?

Tool calls occur when an AI model decides to invoke a specific function or tool to accomplish a task. Rather than only returning text, the model can request to execute tools you’ve defined, such as fetching weather data, searching a database, or performing calculations. A tool call consists of:

• Tool name: The identifier of the tool being invoked
• Tool input: Parameters passed to the tool, often structured as JSON
• Tool output: The result returned after execution

As an application developer, you decide how to surface tool calls to users. You may choose to display all tool calls, selectively surface specific tools or inputs/outputs, or keep tool calls entirely private. Surfacing tool calls supports:

• Trust and transparency: Users see what actions the AI is taking, building confidence in the agent
• Human-in-the-loop workflows: Expose tool calls resolved by humans where users can review and approve tool execution before it happens
• Generative UI: Build dynamic, contextual UI components based on the structured tool data

​

Publish tool calls

Publish tool call and model output messages to the channel. In the example below, the responseId is included in the message extras to allow subscribers to correlate all messages belonging to the same response. The message name allows the client to distinguish between the different message types:

​

Subscribe to tool calls

Subscribe to tool call and model output messages on the channel. In the example below, the responseId from the message extras is used to group tool calls and model output messages belonging to the same response. The message name allows the client to distinguish between the different message types:

​

Generative UI

Tool calls provide structured data that can form the basis of generative UI - dynamically creating UI components based on the tool being invoked, its parameters, and the results returned. Rather than just displaying raw tool call information, you can render rich, contextual components that provide a better user experience. For example, when a weather tool is invoked, instead of showing raw JSON like { location: 'San Francisco', temp: 72, conditions: 'sunny' }, you can render a weather card component with icons, formatted temperature, and visual indicators:

​

Client-side tools

Some tools need to be executed directly on the client device rather than on the server, allowing agents to dynamically access information available on the end user’s device as needed. These include tools that access device capabilities such as GPS location, camera, SMS, local files, or other native functionality. Client-side tool calls follow a request-response pattern over Ably channels:

1. The agent publishes a tool call request to the channel.
2. The client receives and executes the tool using device APIs.
3. The client publishes the result back to the channel.
4. The agent receives the result and continues processing.

The client subscribes to tool call requests, executes the tool using device APIs, and publishes the result back to the channel. The toolCallId enables correlation between tool call requests and results: The agent subscribes to tool results to continue processing. The toolCallId correlates the result back to the original request:

​

Progress updates

Some tool calls take significant time to complete, such as processing large files, performing complex calculations, or executing multi-step operations. For long-running tools, streaming progress updates to users provides visibility into execution status and improves the user experience by showing that work is actively happening. You can deliver progress updates using two approaches:

• Messages: Best for discrete status updates and milestone events
• LiveObjects: Best for continuous numeric progress and shared state synchronization

​

Progress updates via messages

Publish progress messages to the channel as the tool executes, using the toolCallId to correlate progress updates with the specific tool call: Subscribe to progress updates on the client by listening for the tool_progress message type: Message-based progress is useful for:

• Step-by-step status descriptions
• Milestone notifications
• Workflow stages with distinct phases
• Audit trails requiring discrete event records

​

Progress updates via LiveObjects

Use LiveObjects for state-based progress tracking. LiveObjects provides a shared data layer where progress state is automatically synchronized across all subscribed clients, making it ideal for continuous progress tracking. Use LiveCounter for numeric progress values like completion percentages or item counts. Use LiveMap to track complex progress state with multiple fields. First, import and initialize the LiveObjects plugin: Create a LiveMap to track tool progress: Subscribe to LiveObjects updates on the client to render realtime progress: LiveObjects-based progress is useful for:

• Continuous progress bars with frequent updates
• Distributed tool execution across multiple workers
• Complex progress state with multiple fields
• Scenarios where multiple agents or processes contribute to the same progress counter

​

Choosing the right approach

Choose messages when:

• Progress updates are infrequent (every few seconds or at specific milestones)
• You need a complete audit trail of all progress events
• Progress information is descriptive text rather than numeric
• Each update represents a distinct event or stage transition

Choose LiveObjects when:

• Progress updates are frequent (multiple times per second)
• You’re tracking numeric progress like percentages or counts
• Multiple processes or workers contribute to the same progress counter
• You want to minimize message overhead for high-frequency updates

You can combine both approaches for comprehensive progress tracking. Use LiveObjects for high-frequency numeric progress and messages for important milestone notifications:

​

Human-in-the-loop workflows

Tool calls resolved by humans are one approach to implementing human-in-the-loop workflows. When an agent encounters a tool call that needs human resolution, it publishes the tool call to the channel and waits for the human to publish the result back over the channel. For example, a tool that modifies data, performs financial transactions, or accesses sensitive resources might require explicit user approval before execution. The tool call information is surfaced to the user, who can then approve or reject the action.