Class: ToolCallManager<TToolsOrContext, TContext>#

Defined in: packages/ai/src/activities/chat/tools/tool-calls.ts:123

Manages tool call accumulation and execution for the chat() method's automatic tool execution loop.

Responsibilities:

• Accumulates streaming tool call events (ID, name, arguments)
• Validates tool calls (filters out incomplete ones)
• Executes tool execute functions with parsed arguments
• Emits TOOL_CALL_END events for client visibility
• Returns tool result messages for conversation history

This class is used internally by the AI.chat() method to handle the automatic tool execution loop. It can also be used independently for custom tool execution logic.

Example#

const manager = new ToolCallManager(tools);

// During streaming, accumulate tool calls
for await (const chunk of stream) {
  if (chunk.type === 'TOOL_CALL_START') {
    manager.addToolCallStartEvent(chunk);
  } else if (chunk.type === 'TOOL_CALL_ARGS') {
    manager.addToolCallArgsEvent(chunk);
  }
}

// After stream completes, execute tools
if (manager.hasToolCalls()) {
  const toolResults = yield* manager.executeTools(finishEvent);
  messages = [...messages, ...toolResults];
  manager.clear();
}

const manager = new ToolCallManager(tools);

// During streaming, accumulate tool calls
for await (const chunk of stream) {
  if (chunk.type === 'TOOL_CALL_START') {
    manager.addToolCallStartEvent(chunk);
  } else if (chunk.type === 'TOOL_CALL_ARGS') {
    manager.addToolCallArgsEvent(chunk);
  }
}

// After stream completes, execute tools
if (manager.hasToolCalls()) {
  const toolResults = yield* manager.executeTools(finishEvent);
  messages = [...messages, ...toolResults];
  manager.clear();
}

Type Parameters#

TToolsOrContext#

TToolsOrContext = ReadonlyArray<AnyTool>

TContext#

TContext = TToolsOrContext extends ReadonlyArray<AnyTool> ? ContextFromTools<TToolsOrContext> : TToolsOrContext

Constructors#

Constructor#

new ToolCallManager<TToolsOrContext, TContext>(tools): ToolCallManager<TToolsOrContext, TContext>;

new ToolCallManager<TToolsOrContext, TContext>(tools): ToolCallManager<TToolsOrContext, TContext>;

Defined in: packages/ai/src/activities/chat/tools/tool-calls.ts:134

Parameters#

tools#

TToolsOrContext extends readonly AnyTool[] ? TToolsOrContext<TToolsOrContext> : readonly AnyTool[]

Returns#

ToolCallManager<TToolsOrContext, TContext>

Methods#

addToolCallArgsEvent()#

addToolCallArgsEvent(event): void;

addToolCallArgsEvent(event): void;

Defined in: packages/ai/src/activities/chat/tools/tool-calls.ts:164

Add a TOOL_CALL_ARGS event to accumulate arguments (AG-UI)

Parameters#

event#

ToolCallArgsEvent

Returns#

void

addToolCallStartEvent()#

addToolCallStartEvent(event): void;

addToolCallStartEvent(event): void;

Defined in: packages/ai/src/activities/chat/tools/tool-calls.ts:145

Add a TOOL_CALL_START event to begin tracking a tool call (AG-UI)

Parameters#

event#

ToolCallStartEvent

Returns#

void

clear()#

clear(): void;

clear(): void;

Defined in: packages/ai/src/activities/chat/tools/tool-calls.ts:324

Clear the tool calls map for the next iteration

Returns#

void

completeToolCall()#

completeToolCall(event): void;

completeToolCall(event): void;

Defined in: packages/ai/src/activities/chat/tools/tool-calls.ts:178

Complete a tool call with its final input Called when TOOL_CALL_END is received

Parameters#

event#

ToolCallEndEvent

Returns#

void

executeTools()#

executeTools(finishEvent, ...contextArgs): AsyncGenerator<ToolCallEndEvent, ModelMessage<
  | string
  | ContentPart<unknown, unknown, unknown, unknown, unknown>[]
| null>[], void>;

executeTools(finishEvent, ...contextArgs): AsyncGenerator<ToolCallEndEvent, ModelMessage<
  | string
  | ContentPart<unknown, unknown, unknown, unknown, unknown>[]
| null>[], void>;

Defined in: packages/ai/src/activities/chat/tools/tool-calls.ts:213

Execute all tool calls and return tool result messages Yields TOOL_CALL_END events for streaming

Parameters#

finishEvent#

RunFinishedEvent

RUN_FINISHED event from the stream

contextArgs#

...ExecuteToolsContextArgs<TContext>

Returns#

AsyncGenerator<ToolCallEndEvent, ModelMessage< | string | ContentPart<unknown, unknown, unknown, unknown, unknown>[] | null>[], void>

getToolCalls()#

getToolCalls(): ToolCall<unknown>[];

getToolCalls(): ToolCall<unknown>[];

Defined in: packages/ai/src/activities/chat/tools/tool-calls.ts:202

Get all complete tool calls (filtered for valid ID and name)

Returns#

ToolCall<unknown>[]

hasToolCalls()#

hasToolCalls(): boolean;

hasToolCalls(): boolean;

Defined in: packages/ai/src/activities/chat/tools/tool-calls.ts:195

Check if there are any complete tool calls to execute

Returns#

boolean