Chat - Tool call events

Observe tool invocation state changes with onToolCall and drive side effects outside the message list.

This demo focuses on the onToolCall callback and how to use it for side effects that live outside the message store:

• observing tool input and output state changes
• building a local audit log from tool invocations
• reacting to specific tool names with app-level logic

Key concepts

The onToolCall callback

Register onToolCall on ChatProvider to observe every tool invocation state change during streaming:

<ChatProvider
  adapter={adapter}
  onToolCall={({ toolCall }) => {
    console.log(`Tool "${toolCall.toolName}" is now ${toolCall.state}`);

    if (toolCall.state === 'output-available') {
      // Drive side effects — update dashboards, trigger notifications, etc.
    }
  }}
>
  <MyChat />
</ChatProvider>

Tool invocation states

The toolCall.state field tracks the tool lifecycle:

The ChatOnToolCallPayload

interface ChatOnToolCallPayload {
  toolCall: ChatToolInvocation | ChatDynamicToolInvocation;
}

The toolCall object includes toolCallId, toolName, state, input, output, errorText, and approval fields — all typed based on your ChatToolDefinitionMap augmentation.

Key takeaways

• onToolCall fires on every tool state change — not just when output is available
• Use it for side effects outside the store: logging, analytics, external API calls
• Tool invocation state progresses through a well-defined lifecycle from input to output
• For approval flows, see the Tool approval and renderers demo

See also

• Streaming for the tool chunk protocol reference
• Type augmentation for typing tool input and output
• Tool approval and renderers for approval flows and custom part rendering
• State and store for all callback signatures

API

• ChatRoot