Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

ToolCallManager.md

222 lines5.4 KB

1---
2id: ToolCallManager
3title: ToolCallManager
4---
5​
6# Class: ToolCallManager\<TToolsOrContext, TContext\>
7​
8Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:210](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L210)
9​
10Manages tool call accumulation and execution for the chat() method's automatic tool execution loop.
11​
12Responsibilities:
13- Accumulates streaming tool call events (ID, name, arguments)
14- Validates tool calls (filters out incomplete ones)
15- Executes tool `execute` functions with parsed arguments
16- Emits `TOOL_CALL_END` events for client visibility
17- Returns tool result messages for conversation history
18​
19This class is used internally by the AI.chat() method to handle the automatic
20tool execution loop. It can also be used independently for custom tool execution logic.
21​
22## Example
23​
24```typescript
25const manager = new ToolCallManager(tools);
26​
27// During streaming, accumulate tool calls
28for await (const chunk of stream) {
29 if (chunk.type === 'TOOL_CALL_START') {
30 manager.addToolCallStartEvent(chunk);
31 } else if (chunk.type === 'TOOL_CALL_ARGS') {
32 manager.addToolCallArgsEvent(chunk);
33 }
35​
36// After stream completes, execute tools
37if (manager.hasToolCalls()) {
38 const toolResults = yield* manager.executeTools(finishEvent);
39 messages = [...messages, ...toolResults];
40 manager.clear();
42```
43​
44## Type Parameters
45​
46### TToolsOrContext
47​
48`TToolsOrContext` = `ReadonlyArray`\<[`AnyTool`](../type-aliases/AnyTool.md)\>
49​
50### TContext
51​
52`TContext` = `TToolsOrContext` *extends* `ReadonlyArray`\<[`AnyTool`](../type-aliases/AnyTool.md)\> ? `ContextFromTools`\<`TToolsOrContext`\> : `TToolsOrContext`
53​
54## Constructors
55​
56### Constructor
57​
58```ts
59new ToolCallManager<TToolsOrContext, TContext>(tools): ToolCallManager<TToolsOrContext, TContext>;
60```
61​
62Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:221](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L221)
63​
64#### Parameters
65​
66##### tools
67​
68`TToolsOrContext` *extends* readonly [`AnyTool`](../type-aliases/AnyTool.md)[] ? `TToolsOrContext`\<`TToolsOrContext`\> : readonly [`AnyTool`](../type-aliases/AnyTool.md)[]
69​
70#### Returns
71​
72`ToolCallManager`\<`TToolsOrContext`, `TContext`\>
73​
74## Methods
75​
76### addToolCallArgsEvent()
77​
78```ts
79addToolCallArgsEvent(event): void;
80```
81​
82Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:251](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L251)
83​
84Add a TOOL_CALL_ARGS event to accumulate arguments (AG-UI)
85​
86#### Parameters
87​
88##### event
89​
90[`ToolCallArgsEvent`](../interfaces/ToolCallArgsEvent.md)
91​
92#### Returns
93​
94`void`
95​
96***
97​
98### addToolCallStartEvent()
99​
100```ts
101addToolCallStartEvent(event): void;
102```
103​
104Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:232](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L232)
105​
106Add a TOOL_CALL_START event to begin tracking a tool call (AG-UI)
107​
108#### Parameters
109​
110##### event
111​
112[`ToolCallStartEvent`](../interfaces/ToolCallStartEvent.md)
113​
114#### Returns
115​
116`void`
117​
118***
119​
120### clear()
121​
122```ts
123clear(): void;
124```
125​
126Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:411](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L411)
127​
128Clear the tool calls map for the next iteration
129​
130#### Returns
131​
132`void`
133​
134***
135​
136### completeToolCall()
137​
138```ts
139completeToolCall(event): void;
140```
141​
142Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:265](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L265)
143​
144Complete a tool call with its final input
145Called when TOOL_CALL_END is received
146​
147#### Parameters
148​
149##### event
150​
151[`ToolCallEndEvent`](../interfaces/ToolCallEndEvent.md)
152​
153#### Returns
154​
155`void`
156​
157***
158​
159### executeTools()
160​
161```ts
162executeTools(finishEvent, ...contextArgs): AsyncGenerator<ToolCallEndEvent, ModelMessage<
163 | string
164 | ContentPart<unknown, unknown, unknown, unknown, unknown>[]
165| null>[], void>;
166```
167​
168Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:300](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L300)
169​
170Execute all tool calls and return tool result messages
171Yields TOOL_CALL_END events for streaming
172​
173#### Parameters
174​
175##### finishEvent
176​
177[`RunFinishedEvent`](../interfaces/RunFinishedEvent.md)
178​
179RUN_FINISHED event from the stream
180​
181##### contextArgs
182​
183...`ExecuteToolsContextArgs`\<`TContext`\>
184​
185#### Returns
186​
187`AsyncGenerator`\<[`ToolCallEndEvent`](../interfaces/ToolCallEndEvent.md), [`ModelMessage`](../interfaces/ModelMessage.md)\<
188 \| `string`
189 \| [`ContentPart`](../type-aliases/ContentPart.md)\<`unknown`, `unknown`, `unknown`, `unknown`, `unknown`\>[]
190 \| `null`\>[], `void`\>
191​
192***
193​
194### getToolCalls()
195​
196```ts
197getToolCalls(): ToolCall<unknown>[];
198```
199​
200Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:289](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L289)
201​
202Get all complete tool calls (filtered for valid ID and name)
203​
204#### Returns
205​
206[`ToolCall`](../interfaces/ToolCall.md)\<`unknown`\>[]
207​
208***
209​
210### hasToolCalls()
211​
212```ts
213hasToolCalls(): boolean;
214```
215​
216Defined in: [packages/ai/src/activities/chat/tools/tool-calls.ts:282](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-calls.ts#L282)
217​
218Check if there are any complete tool calls to execute
219​
220#### Returns
221​
222`boolean`