# 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](https://ably.com/docs/ai-transport/messaging/human-in-the-loop.md) 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](https://ably.com/docs/messages.md#properties) to allow subscribers to correlate all messages belonging to the same response. The message [`name`](https://ably.com/docs/messages.md#properties) allows the client to distinguish between the different message types:

<Code>

### Javascript

```
const channel = realtime.channels.get('your-channel-name');

// Example: stream returns events like:
// { type: 'tool_call', name: 'get_weather', args: '{"location":"San Francisco"}', toolCallId: 'tool_123', responseId: 'resp_abc123' }
// { type: 'tool_result', name: 'get_weather', result: '{"temp":72,"conditions":"sunny"}', toolCallId: 'tool_123', responseId: 'resp_abc123' }
// { type: 'message', text: 'The weather in San Francisco is 72°F and sunny.', responseId: 'resp_abc123' }

for await (const event of stream) {
  if (event.type === 'tool_call') {
    // Publish tool call arguments
    await channel.publish({
      name: 'tool_call',
      data: {
        name: event.name,
        args: event.args
      },
      extras: {
        headers: {
          responseId: event.responseId,
          toolCallId: event.toolCallId
        }
      }
    });
  } else if (event.type === 'tool_result') {
    // Publish tool call results
    await channel.publish({
      name: 'tool_result',
      data: {
        name: event.name,
        result: event.result
      },
      extras: {
        headers: {
          responseId: event.responseId,
          toolCallId: event.toolCallId
        }
      }
    });
  } else if (event.type === 'message') {
    // Publish model output messages
    await channel.publish({
      name: 'message',
      data: event.text,
      extras: {
        headers: {
          responseId: event.responseId
        }
      }
    });
  }
}
```
### Python

```
channel = realtime.channels.get('your-channel-name')

# Example: stream returns events like:
# { 'type': 'tool_call', 'name': 'get_weather', 'args': '{"location":"San Francisco"}', 'toolCallId': 'tool_123', 'responseId': 'resp_abc123' }
# { 'type': 'tool_result', 'name': 'get_weather', 'result': '{"temp":72,"conditions":"sunny"}', 'toolCallId': 'tool_123', 'responseId': 'resp_abc123' }
# { 'type': 'message', 'text': 'The weather in San Francisco is 72°F and sunny.', 'responseId': 'resp_abc123' }

async for event in stream:
    if event['type'] == 'tool_call':
        # Publish tool call arguments
        message = Message(
            name='tool_call',
            data={
                'name': event['name'],
                'args': event['args']
            },
            extras={
                'headers': {
                    'responseId': event['responseId'],
                    'toolCallId': event['toolCallId']
                }
            }
        )
        await channel.publish(message)
    elif event['type'] == 'tool_result':
        # Publish tool call results
        message = Message(
            name='tool_result',
            data={
                'name': event['name'],
                'result': event['result']
            },
            extras={
                'headers': {
                    'responseId': event['responseId'],
                    'toolCallId': event['toolCallId']
                }
            }
        )
        await channel.publish(message)
    elif event['type'] == 'message':
        # Publish model output messages
        message = Message(
            name='message',
            data=event['text'],
            extras={
                'headers': {
                    'responseId': event['responseId']
                }
            }
        )
        await channel.publish(message)
```
### Java

```
Channel channel = realtime.channels.get("your-channel-name");

// Example: stream returns events like:
// { type: 'tool_call', name: 'get_weather', args: '{"location":"San Francisco"}', toolCallId: 'tool_123', responseId: 'resp_abc123' }
// { type: 'tool_result', name: 'get_weather', result: '{"temp":72,"conditions":"sunny"}', toolCallId: 'tool_123', responseId: 'resp_abc123' }
// { type: 'message', text: 'The weather in San Francisco is 72°F and sunny.', responseId: 'resp_abc123' }

for (Event event : stream) {
    JsonObject extras = new JsonObject();
    JsonObject headers = new JsonObject();

    if (event.getType().equals("tool_call")) {
        // Publish tool call arguments
        JsonObject data = new JsonObject();
        data.addProperty("name", event.getName());
        data.addProperty("args", event.getArgs());

        headers.addProperty("responseId", event.getResponseId());
        headers.addProperty("toolCallId", event.getToolCallId());
        extras.add("headers", headers);

        channel.publish(new Message("tool_call", data, new MessageExtras(extras)));
    } else if (event.getType().equals("tool_result")) {
        // Publish tool call results
        JsonObject data = new JsonObject();
        data.addProperty("name", event.getName());
        data.addProperty("result", event.getResult());

        headers.addProperty("responseId", event.getResponseId());
        headers.addProperty("toolCallId", event.getToolCallId());
        extras.add("headers", headers);

        channel.publish(new Message("tool_result", data, new MessageExtras(extras)));
    } else if (event.getType().equals("message")) {
        // Publish model output messages
        headers.addProperty("responseId", event.getResponseId());
        extras.add("headers", headers);

        channel.publish(new Message("message", event.getText(), new MessageExtras(extras)));
    }
}
```
</Code>

<Aside data-type="note">
Model APIs like OpenAI's [Responses API](https://platform.openai.com/docs/api-reference/responses) and Anthropic's [Messages API](https://platform.claude.com/docs/en/api/messages) don't include tool results in their streams - instead, you execute tools in your code and return results to the model, but the model's output doesn't echo those results back. Agent SDKs like [OpenAI Agent SDK](https://platform.openai.com/docs/guides/agents-sdk) and [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) maintain context and surface both tool calls and results on the stream. When using model APIs directly, publish tool results to the channel separately if you want to surface them to subscribers.
</Aside>

<Aside data-type="note">
To learn how to stream individual tokens as they are generated, see the [token streaming](https://ably.com/docs/ai-transport/token-streaming.md) documentation.
</Aside>

<Aside data-type="note">
Set [`echoMessages`](https://ably.com/docs/api/realtime-sdk/types.md#client-options) to `false` on the agent's Ably client to prevent the agent from receiving its own tool call messages, avoiding billing for [echoed messages](https://ably.com/docs/pub-sub/advanced.md#echo).
</Aside>

## 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`](https://ably.com/docs/api/realtime-sdk/messages.md#extras) is used to group tool calls and model output messages belonging to the same response. The message [`name`](https://ably.com/docs/messages.md#properties) allows the client to distinguish between the different message types:

<Code>

### Javascript

```
const channel = realtime.channels.get('your-channel-name');

// Track responses by ID, each containing tool calls and final response
const responses = new Map();

// Subscribe to all events on the channel
await channel.subscribe((message) => {
  const responseId = message.extras?.headers?.responseId;

  if (!responseId) {
    console.warn('Message missing responseId');
    return;
  }

  // Initialize response object if needed
  if (!responses.has(responseId)) {
    responses.set(responseId, {
      toolCalls: new Map(),
      message: ''
    });
  }

  const response = responses.get(responseId);

  // Handle each message type
  switch (message.name) {
    case 'message':
      response.message = message.data;
      break;
    case 'tool_call':
      const toolCallId = message.extras?.headers?.toolCallId;
      response.toolCalls.set(toolCallId, {
        name: message.data.name,
        args: message.data.args
      });
      break;
    case 'tool_result':
      const resultToolCallId = message.extras?.headers?.toolCallId;
      const toolCall = response.toolCalls.get(resultToolCallId);
      if (toolCall) {
        toolCall.result = message.data.result;
      }
      break;
  }

  // Display the tool calls and response for this turn
  console.log(`Response ${responseId}:`, response);
});
```
### Python

```
channel = realtime.channels.get('your-channel-name')

# Track responses by ID, each containing tool calls and final response
responses = {}

# Subscribe to all events on the channel
def on_message(message):
    response_id = message.extras.get('headers', {}).get('responseId')

    if not response_id:
        print('Message missing responseId')
        return

    # Initialize response object if needed
    if response_id not in responses:
        responses[response_id] = {
            'toolCalls': {},
            'message': ''
        }

    response = responses[response_id]

    # Handle each message type
    if message.name == 'message':
        response['message'] = message.data
    elif message.name == 'tool_call':
        tool_call_id = message.extras.get('headers', {}).get('toolCallId')
        response['toolCalls'][tool_call_id] = {
            'name': message.data['name'],
            'args': message.data['args']
        }
    elif message.name == 'tool_result':
        result_tool_call_id = message.extras.get('headers', {}).get('toolCallId')
        tool_call = response['toolCalls'].get(result_tool_call_id)
        if tool_call:
            tool_call['result'] = message.data['result']

    # Display the tool calls and response for this turn
    print(f'Response {response_id}:', response)

await channel.subscribe(on_message)
```
### Java

```
Channel channel = realtime.channels.get("your-channel-name");

// Track responses by ID, each containing tool calls and final response
Map<String, Response> responses = new ConcurrentHashMap<>();

// Subscribe to all events on the channel
channel.subscribe(message -> {
    JsonObject headers = message.extras.asJsonObject().get("headers").getAsJsonObject();
    String responseId = headers != null ? headers.get("responseId").getAsString() : null;

    if (responseId == null) {
        System.err.println("Message missing responseId");
        return;
    }

    // Initialize response object if needed
    responses.putIfAbsent(responseId, new Response());
    Response response = responses.get(responseId);

    // Handle each message type
    switch (message.name) {
        case "message":
            response.setMessage((String) message.data);
            break;
        case "tool_call":
            String toolCallId = headers.get("toolCallId").getAsString();
            JsonObject data = (JsonObject) message.data;
            ToolCall toolCall = new ToolCall();
            toolCall.setName(data.get("name").getAsString());
            toolCall.setArgs(data.get("args").getAsString());
            response.getToolCalls().put(toolCallId, toolCall);
            break;
        case "tool_result":
            String resultToolCallId = headers.get("toolCallId").getAsString();
            ToolCall existingToolCall = response.getToolCalls().get(resultToolCallId);
            if (existingToolCall != null) {
                JsonObject resultData = (JsonObject) message.data;
                existingToolCall.setResult(resultData.get("result").getAsString());
            }
            break;
    }

    // Display the tool calls and response for this turn
    System.out.println("Response " + responseId + ": " + response);
});
```
</Code>

<Aside data-type="further-reading">
To learn about hydrating responses from channel history, including using `rewind` or `untilAttach`, handling in-progress responses, and correlating with database records, see client hydration in the [message-per-response](https://ably.com/docs/ai-transport/token-streaming/message-per-response.md#hydration) and [message-per-token](https://ably.com/docs/ai-transport/token-streaming/message-per-token.md#hydration) documentation.
</Aside>

## 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:

<Code>

### Javascript

```
const channel = realtime.channels.get('your-channel-name');

await channel.subscribe((message) => {
  // Render component when tool is invoked
  if (message.name === 'tool_call' && message.data.name === 'get_weather') {
    const args = JSON.parse(message.data.args);
    renderWeatherCard({ location: args.location, loading: true });
  }

  // Update component with results
  if (message.name === 'tool_result' && message.data.name === 'get_weather') {
    const result = JSON.parse(message.data.result);
    renderWeatherCard(result);
  }
});
```
### Python

```
channel = realtime.channels.get('your-channel-name')

def on_message(message):
    # Render component when tool is invoked
    if message.name == 'tool_call' and message.data['name'] == 'get_weather':
        args = json.loads(message.data['args'])
        render_weather_card({'location': args['location'], 'loading': True})

    # Update component with results
    if message.name == 'tool_result' and message.data['name'] == 'get_weather':
        result = json.loads(message.data['result'])
        render_weather_card(result)

await channel.subscribe(on_message)
```
### Java

```
Channel channel = realtime.channels.get("your-channel-name");

channel.subscribe(message -> {
    // Render component when tool is invoked
    if (message.name.equals("tool_call")) {
        JsonObject data = (JsonObject) message.data;
        if (data.get("name").getAsString().equals("get_weather")) {
            JsonObject args = JsonParser.parseString(data.get("args").getAsString()).getAsJsonObject();
            renderWeatherCard(args.get("location").getAsString(), true);
        }
    }

    // Update component with results
    if (message.name.equals("tool_result")) {
        JsonObject data = (JsonObject) message.data;
        if (data.get("name").getAsString().equals("get_weather")) {
            JsonObject result = JsonParser.parseString(data.get("result").getAsString()).getAsJsonObject();
            renderWeatherCard(result);
        }
    }
});
```
</Code>

<Aside data-type="note">
Models generate tool call arguments token by token, which you can stream to the client. When implementing token-level streaming, your UI should handle parsing partial JSON gracefully to render realtime updates as the arguments stream in. To learn more about approaches to token streaming, see the [token streaming](https://ably.com/docs/ai-transport/token-streaming.md) documentation.
</Aside>

## 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.

<Aside data-type="further-reading">
For more information about bi-directional communication patterns between agents and users, see [Accepting user input](https://ably.com/docs/ai-transport/messaging/accepting-user-input.md) and [Human-in-the-loop](https://ably.com/docs/ai-transport/messaging/human-in-the-loop.md).
</Aside>

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:

<Code>

### Javascript

```
const channel = realtime.channels.get('your-channel-name');

await channel.subscribe('tool_call', async (message) => {
  const { name, args } = message.data;
  const { responseId, toolCallId } = message.extras?.headers || {};

  if (name === 'get_location') {
    const result = await getGeolocationPosition();
    await channel.publish({
      name: 'tool_result',
      data: {
        name: name,
        result: {
          lat: result.coords.latitude,
          lng: result.coords.longitude
        }
      },
      extras: {
        headers: {
          responseId: responseId,
          toolCallId: toolCallId
        }
      }
    });
  }
});
```
### Python

```
channel = realtime.channels.get('your-channel-name')

async def on_tool_call(message):
    name = message.data['name']
    args = message.data.get('args')
    headers = message.extras.get('headers', {})
    response_id = headers.get('responseId')
    tool_call_id = headers.get('toolCallId')

    if name == 'get_location':
        result = await get_geolocation_position()
        message = Message(
            name='tool_result',
            data={
                'name': name,
                'result': {
                    'lat': result['coords']['latitude'],
                    'lng': result['coords']['longitude']
                }
            },
            extras={
                'headers': {
                    'responseId': response_id,
                    'toolCallId': tool_call_id
                }
            }
        )
        await channel.publish(message)

await channel.subscribe('tool_call', on_tool_call)
```
### Java

```
Channel channel = realtime.channels.get("your-channel-name");

channel.subscribe("tool_call", message -> {
    JsonObject data = (JsonObject) message.data;
    String name = data.get("name").getAsString();
    JsonObject headers = message.extras.asJsonObject().get("headers");
    String responseId = headers.get("responseId").getAsString();
    String toolCallId = headers.get("toolCallId").getAsString();

    if (name.equals("get_location")) {
        GeolocationPosition result = getGeolocationPosition();

        JsonObject resultData = new JsonObject();
        resultData.addProperty("name", name);
        JsonObject resultValue = new JsonObject();
        resultValue.addProperty("lat", result.getCoords().getLatitude());
        resultValue.addProperty("lng", result.getCoords().getLongitude());
        resultData.add("result", resultValue);

        JsonObject resultExtras = new JsonObject();
        JsonObject resultHeaders = new JsonObject();
        resultHeaders.addProperty("responseId", responseId);
        resultHeaders.addProperty("toolCallId", toolCallId);
        resultExtras.add("headers", resultHeaders);

        channel.publish(new Message("tool_result", resultData, new MessageExtras(resultExtras)));
    }
});
```
</Code>

<Aside data-type="note">
Client-side tools often require user permission to access device APIs. These permissions are managed by the device operating system, not the agent. Handle permission denials gracefully by publishing an error tool result so the AI can respond appropriately.
</Aside>

<Aside data-type="note">
Set [`echoMessages`](https://ably.com/docs/api/realtime-sdk/types.md#client-options) to `false` in the client options to prevent tool results from being echoed back to the client that published them. This avoids billing for the echoed message. When disabled, update your UI to reflect the tool execution status immediately upon sending rather than waiting for the echoed message. See [echoing messages](https://ably.com/docs/pub-sub/advanced.md#echo) for more details.
</Aside>

The agent subscribes to tool results to continue processing. The `toolCallId` correlates the result back to the original request:

<Code>

### Javascript

```
const pendingToolCalls = new Map();

await channel.subscribe('tool_result', (message) => {
  const { toolCallId, result } = message.data;
  const pending = pendingToolCalls.get(toolCallId);

  if (!pending) return;

  // Pass result back to the AI model to continue the conversation
  processResult(pending.responseId, toolCallId, result);

  pendingToolCalls.delete(toolCallId);
});
```
### Python

```
pending_tool_calls = {}

def on_tool_result(message):
    tool_call_id = message.data.get('toolCallId')
    result = message.data.get('result')
    pending = pending_tool_calls.get(tool_call_id)

    if not pending:
        return

    # Pass result back to the AI model to continue the conversation
    process_result(pending['responseId'], tool_call_id, result)

    del pending_tool_calls[tool_call_id]

await channel.subscribe('tool_result', on_tool_result)
```
### Java

```
Map<String, PendingToolCall> pendingToolCalls = new ConcurrentHashMap<>();

channel.subscribe("tool_result", message -> {
    JsonObject data = (JsonObject) message.data;
    String toolCallId = data.get("toolCallId").getAsString();
    JsonObject result = data.get("result").getAsJsonObject();
    PendingToolCall pending = pendingToolCalls.get(toolCallId);

    if (pending == null) {
        return;
    }

    // Pass result back to the AI model to continue the conversation
    processResult(pending.getResponseId(), toolCallId, result);

    pendingToolCalls.remove(toolCallId);
});
```
</Code>

## 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:

<Code>

#### Javascript

```
const channel = realtime.channels.get('your-channel-name');

// Publish initial tool call
await channel.publish({
  name: 'tool_call',
  data: {
    name: 'process_document',
    args: { documentId: 'doc_123', pages: 100 }
  },
  extras: {
    headers: {
      responseId: 'resp_abc123',
      toolCallId: 'tool_456'
    }
  }
});

// Publish progress updates as tool executes
await channel.publish({
  name: 'tool_progress',
  data: {
    name: 'process_document',
    status: 'Processing page 25 of 100',
    percentComplete: 25
  },
  extras: {
    headers: {
      responseId: 'resp_abc123',
      toolCallId: 'tool_456'
    }
  }
});

// Continue publishing progress as work progresses
await channel.publish({
  name: 'tool_progress',
  data: {
    name: 'process_document',
    status: 'Processing page 75 of 100',
    percentComplete: 75
  },
  extras: {
    headers: {
      responseId: 'resp_abc123',
      toolCallId: 'tool_456'
    }
  }
});

// Publish final result
await channel.publish({
  name: 'tool_result',
  data: {
    name: 'process_document',
    result: { processedPages: 100, summary: 'Document processed successfully' }
  },
  extras: {
    headers: {
      responseId: 'resp_abc123',
      toolCallId: 'tool_456'
    }
  }
});
```
#### Python

```
channel = realtime.channels.get('your-channel-name')

# Publish initial tool call
await channel.publish(Message(
    name='tool_call',
    data={
        'name': 'process_document',
        'args': {'documentId': 'doc_123', 'pages': 100}
    },
    extras={
        'headers': {
            'responseId': 'resp_abc123',
            'toolCallId': 'tool_456'
        }
    }
))

# Publish progress updates as tool executes
await channel.publish(Message(
    name='tool_progress',
    data={
        'name': 'process_document',
        'status': 'Processing page 25 of 100',
        'percentComplete': 25
    },
    extras={
        'headers': {
            'responseId': 'resp_abc123',
            'toolCallId': 'tool_456'
        }
    }
))

# Continue publishing progress as work progresses
await channel.publish(Message(
    name='tool_progress',
    data={
        'name': 'process_document',
        'status': 'Processing page 75 of 100',
        'percentComplete': 75
    },
    extras={
        'headers': {
            'responseId': 'resp_abc123',
            'toolCallId': 'tool_456'
        }
    }
))

# Publish final result
await channel.publish(Message(
    name='tool_result',
    data={
        'name': 'process_document',
        'result': {'processedPages': 100, 'summary': 'Document processed successfully'}
    },
    extras={
        'headers': {
            'responseId': 'resp_abc123',
            'toolCallId': 'tool_456'
        }
    }
))
```
#### Java

```
Channel channel = realtime.channels.get("your-channel-name");

// Helper method to create message extras with headers
MessageExtras createExtras(String responseId, String toolCallId) {
    JsonObject extrasJson = new JsonObject();
    JsonObject headers = new JsonObject();
    headers.addProperty("responseId", responseId);
    headers.addProperty("toolCallId", toolCallId);
    extrasJson.add("headers", headers);
    return new MessageExtras(extrasJson);
}

// Publish initial tool call
JsonObject toolCallData = new JsonObject();
toolCallData.addProperty("name", "process_document");
JsonObject args = new JsonObject();
args.addProperty("documentId", "doc_123");
args.addProperty("pages", 100);
toolCallData.add("args", args);

Message toolCall = new Message(
    "tool_call",
    toolCallData.toString(),
    createExtras("resp_abc123", "tool_456")
);
channel.publish(toolCall);

// Publish progress updates as tool executes
JsonObject progress1 = new JsonObject();
progress1.addProperty("name", "process_document");
progress1.addProperty("status", "Processing page 25 of 100");
progress1.addProperty("percentComplete", 25);

Message progressMsg1 = new Message(
    "tool_progress",
    progress1.toString(),
    createExtras("resp_abc123", "tool_456")
);
channel.publish(progressMsg1);

// Continue publishing progress as work progresses
JsonObject progress2 = new JsonObject();
progress2.addProperty("name", "process_document");
progress2.addProperty("status", "Processing page 75 of 100");
progress2.addProperty("percentComplete", 75);

Message progressMsg2 = new Message(
    "tool_progress",
    progress2.toString(),
    createExtras("resp_abc123", "tool_456")
);
channel.publish(progressMsg2);

// Publish final result
JsonObject resultData = new JsonObject();
resultData.addProperty("name", "process_document");
JsonObject result = new JsonObject();
result.addProperty("processedPages", 100);
result.addProperty("summary", "Document processed successfully");
resultData.add("result", result);

Message resultMsg = new Message(
    "tool_result",
    resultData.toString(),
    createExtras("resp_abc123", "tool_456")
);
channel.publish(resultMsg);
```
</Code>

Subscribe to progress updates on the client by listening for the `tool_progress` message type:

<Code>

#### Javascript

```
const channel = realtime.channels.get('your-channel-name');

// Track tool execution progress
const toolProgress = new Map();

await channel.subscribe((message) => {
  const { responseId, toolCallId } = message.extras?.headers || {};

  switch (message.name) {
    case 'tool_call':
      toolProgress.set(toolCallId, {
        name: message.data.name,
        status: 'Starting...',
        percentComplete: 0
      });
      renderProgressBar(toolCallId, 0);
      break;

    case 'tool_progress':
      const progress = toolProgress.get(toolCallId);
      if (progress) {
        progress.status = message.data.status;
        progress.percentComplete = message.data.percentComplete;
        renderProgressBar(toolCallId, message.data.percentComplete);
      }
      break;

    case 'tool_result':
      toolProgress.delete(toolCallId);
      renderCompleted(toolCallId, message.data.result);
      break;
  }
});
```
#### Python

```
channel = realtime.channels.get('your-channel-name')

# Track tool execution progress
tool_progress = {}

async def handle_message(message):
    headers = message.extras.get('headers', {}) if message.extras else {}
    response_id = headers.get('responseId')
    tool_call_id = headers.get('toolCallId')

    if message.name == 'tool_call':
        tool_progress[tool_call_id] = {
            'name': message.data.get('name'),
            'status': 'Starting...',
            'percentComplete': 0
        }
        render_progress_bar(tool_call_id, 0)

    elif message.name == 'tool_progress':
        progress = tool_progress.get(tool_call_id)
        if progress:
            progress['status'] = message.data.get('status')
            progress['percentComplete'] = message.data.get('percentComplete')
            render_progress_bar(tool_call_id, message.data.get('percentComplete'))

    elif message.name == 'tool_result':
        if tool_call_id in tool_progress:
            del tool_progress[tool_call_id]
        render_completed(tool_call_id, message.data.get('result'))

# Subscribe to all messages on the channel
await channel.subscribe(handle_message)
```
#### Java

```
Channel channel = realtime.channels.get("your-channel-name");

// Track tool execution progress
Map<String, JsonObject> toolProgress = new HashMap<>();

// Subscribe to all messages on the channel
channel.subscribe(message -> {
    JsonObject headers = message.extras != null
        ? message.extras.asJsonObject().getAsJsonObject("headers")
        : null;

    String responseId = headers != null && headers.has("responseId")
        ? headers.get("responseId").getAsString()
        : null;
    String toolCallId = headers != null && headers.has("toolCallId")
        ? headers.get("toolCallId").getAsString()
        : null;

    switch (message.name) {
        case "tool_call":
            JsonObject newProgress = new JsonObject();
            newProgress.addProperty("name", ((JsonObject) message.data).get("name").getAsString());
            newProgress.addProperty("status", "Starting...");
            newProgress.addProperty("percentComplete", 0);
            toolProgress.put(toolCallId, newProgress);
            renderProgressBar(toolCallId, 0);
            break;

        case "tool_progress":
            JsonObject progress = toolProgress.get(toolCallId);
            if (progress != null) {
                JsonObject progressData = (JsonObject) message.data;
                progress.addProperty("status", progressData.get("status").getAsString());
                progress.addProperty("percentComplete", progressData.get("percentComplete").getAsInt());
                renderProgressBar(toolCallId, progressData.get("percentComplete").getAsInt());
            }
            break;

        case "tool_result":
            toolProgress.remove(toolCallId);
            renderCompleted(toolCallId, ((JsonObject) message.data).get("result"));
            break;
    }
});
```
</Code>

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](https://ably.com/docs/liveobjects.md) 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](https://ably.com/docs/liveobjects/counter.md) for numeric progress values like completion percentages or item counts. Use [LiveMap](https://ably.com/docs/liveobjects/map.md) to track complex progress state with multiple fields.

First, import and initialize the LiveObjects plugin:

<Code>

#### Javascript

```
import * as Ably from 'ably';
import { LiveObjects, LiveMap, LiveCounter } from 'ably/liveobjects';

// Initialize client with LiveObjects plugin
const realtime = new Ably.Realtime({
  key: 'your-api-key',
  plugins: { LiveObjects }
});

// Get channel with LiveObjects capabilities
const channel = realtime.channels.get('your-channel-name', {
  modes: ['OBJECT_SUBSCRIBE', 'OBJECT_PUBLISH']
});

// Get the channel's LiveObjects root
const root = await channel.object.get();
```
</Code>

Create a LiveMap to track tool progress:

<Code>

#### Javascript

```
// Create a LiveMap to track tool progress
await root.set('tool_456_progress', LiveMap.create({
  status: 'starting',
  itemsProcessed: LiveCounter.create(0),
  totalItems: 100,
  currentItem: ''
}));

// Update progress as tool executes
const progress = root.get('tool_456_progress');

await progress.set('status', 'processing');
await progress.set('currentItem', 'item_25');
await progress.get('itemsProcessed').increment(25);

// Continue updating as work progresses
await progress.set('currentItem', 'item_75');
await progress.get('itemsProcessed').increment(50);

// Final increment to reach 100%
await progress.set('currentItem', 'item_100');
await progress.get('itemsProcessed').increment(25);

// Mark complete
await progress.set('status', 'completed');
```
</Code>

Subscribe to LiveObjects updates on the client to render realtime progress:

<Code>

#### Javascript

```
import * as Ably from 'ably';
import { LiveObjects } from 'ably/liveobjects';

// Initialize client with LiveObjects plugin
const realtime = new Ably.Realtime({
  key: 'your-api-key',
  plugins: { LiveObjects }
});

// Get channel with LiveObjects capabilities
const channel = realtime.channels.get('your-channel-name', {
  modes: ['OBJECT_SUBSCRIBE', 'OBJECT_PUBLISH']
});

// Get the channel's LiveObjects root
const root = await channel.object.get();

// Subscribe to progress updates
const progress = root.get('tool_456_progress');
progress.subscribe(() => {
  const status = progress.get('status').value();
  const itemsProcessed = progress.get('itemsProcessed').value();
  const totalItems = progress.get('totalItems').value();
  const percentComplete = Math.round((itemsProcessed / totalItems) * 100);

  renderProgressBar('tool_456', percentComplete, status);
});
```
</Code>

<Aside data-type="note">
LiveObjects requires enabling [LiveObjects capability](https://ably.com/docs/liveobjects.md) on your channel. LiveCounter ensures that concurrent increments from multiple sources are correctly synchronized, making it safe to update progress from distributed workers or parallel processes.
</Aside>

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:

<Code>

#### Javascript

```
// Update numeric progress continuously via LiveObjects
await progress.get('itemsProcessed').increment(1);

// Publish milestone messages at key points
if (itemsProcessed === totalItems / 2) {
  await channel.publish({
    name: 'tool_progress',
    data: {
      name: 'process_document',
      status: 'Halfway complete - 50 of 100 items processed'
    },
    extras: {
      headers: {
        responseId: 'resp_abc123',
        toolCallId: 'tool_456'
      }
    }
  });
}
```
</Code>

## 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.

<Aside data-type="further-reading">
For detailed implementation patterns and best practices for human-in-the-loop workflows, including authorization and verification strategies, see the [human-in-the-loop](https://ably.com/docs/ai-transport/messaging/human-in-the-loop.md) documentation.
</Aside>

## Related Topics

- [Accepting user input](https://ably.com/docs/ai-transport/messaging/accepting-user-input.md): Enable users to send prompts to AI agents over Ably with verified identity and message correlation.
- [Human-in-the-loop](https://ably.com/docs/ai-transport/messaging/human-in-the-loop.md): Implement human-in-the-loop workflows for AI agents using Ably capabilities and claims to ensure authorized users approve sensitive tool calls.
- [Chain of thought](https://ably.com/docs/ai-transport/messaging/chain-of-thought.md): Stream chain-of-thought reasoning from thinking models in AI applications
- [Citations](https://ably.com/docs/ai-transport/messaging/citations.md): Attach source citations to AI responses using message annotations
- [Completion and cancellation](https://ably.com/docs/ai-transport/messaging/completion-and-cancellation.md): Signal when AI responses are complete and support user-initiated cancellation of in-progress responses.

## Documentation Index

To discover additional Ably documentation:

1. Fetch [llms.txt](https://ably.com/llms.txt) for the canonical list of available pages.
2. Identify relevant URLs from that index.
3. Fetch target pages as needed.

Avoid using assumed or outdated documentation paths.