Chat - Tool call events

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

Use the onToolCall callback to react to tool state changes 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

Observing tool invocations

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:

State	Description
`input-streaming`	Tool input is being streamed
`input-available`	Tool input is fully available
`approval-requested`	User approval is needed
`approval-responded`	User has responded to the approval
`output-available`	Tool output is ready
`output-error`	Tool execution failed
`output-denied`	User denied the tool call

Callback payload structure

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.

The demo below shows how onToolCall observes state transitions and feeds an external audit log:

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 defined lifecycle from input to output.
For approval flows, see the Tool approval and renderers demo.

API

ChatRoot