fix(ai): make experimental_context required in ToolLoopAgentOnFinishCallback (#12219)

kaizen403 · dancer · web-flow · commit 59fcf30370c4 · 2026-02-09T15:05:33.000Z
## Summary - Fixes type inconsistency where `ToolLoopAgentOnFinishCallback` had `experimental_context` as optional (`?`) while `StreamTextOnFinishCallback` and `GenerateTextOnFinishCallback` had it as required - Adds type tests to verify callback type compatibility between agent and streamText/generateText callbacks - Updates JSDoc comment to use "tool execution" wording for consistency with other callbacks ## Problem As reported in #12195, `ToolLoopAgentOnFinishCallback` defines `experimental_context?: unknown` (optional), but `StreamTextOnFinishCallback` and `GenerateTextOnFinishCallback` define `experimental_context: unknown` (required). Since `ToolLoopAgent` delegates to `streamText`/`generateText`, and both always pass `experimental_context` when invoking the callback ([stream-text.ts#L1011](https://github.com/vercel/ai/blob/main/packages/ai/src/generate-text/stream-text.ts#L1011), [generate-text.ts#L940](https://github.com/vercel/ai/blob/main/packages/ai/src/generate-text/generate-text.ts#L940)), the types should match. This inconsistency causes type errors when trying to use a `StreamTextOnFinishCallback` where `ToolLoopAgentOnFinishCallback` is expected (or vice versa). ## Solution Changed `experimental_context?: unknown` to `experimental_context: unknown` in `ToolLoopAgentOnFinishCallback` to match the other callback types. ## Testing - All 1812 tests pass including new type tests - Added 2 new type tests verifying bidirectional type compatibility between `StreamTextOnFinishCallback` and `ToolLoopAgentOnFinishCallback` - Full type check passes with no errors Fixes #12195 --------- Co-authored-by: kaizen403 <kaizen403@users.noreply.github.com> Co-authored-by: ‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌ <144584931+dancer@users.noreply.github.com> Co-authored-by: josh <josh@afterima.ge>
diff --git a/.changeset/fix-experimental-context-optionality.md b/.changeset/fix-experimental-context-optionality.md
@@ -0,0 +1,7 @@
+---
+'ai': patch
+---
+
+fix(ai): make experimental_context required in ToolLoopAgentOnFinishCallback
+
+This fixes a type inconsistency where `ToolLoopAgentOnFinishCallback` had `experimental_context` as optional while `StreamTextOnFinishCallback` and `GenerateTextOnFinishCallback` had it as required. Since `ToolLoopAgent` delegates to `streamText`/`generateText`, and both always pass `experimental_context` when invoking the callback, the types should match.
diff --git a/packages/ai/src/agent/tool-loop-agent-on-finish-callback.ts b/packages/ai/src/agent/tool-loop-agent-on-finish-callback.ts
@@ -20,12 +20,12 @@ export type ToolLoopAgentOnFinishCallback<TOOLS extends ToolSet = {}> = (
     readonly totalUsage: LanguageModelUsage;
 
     /**
-     * Context that is passed into tool calls.
+     * Context that is passed into tool execution.
      *
      * Experimental (can break in patch releases).
      *
      * @default undefined
      */
-    experimental_context?: unknown;
+    experimental_context: unknown;
   },
 ) => PromiseLike<void> | void;
diff --git a/packages/ai/src/agent/tool-loop-agent.test-d.ts b/packages/ai/src/agent/tool-loop-agent.test-d.ts
@@ -1,13 +1,39 @@
 import { describe, expectTypeOf, it } from 'vitest';
 import { z } from 'zod';
-import { Output } from '../generate-text';
+import { Output, StreamTextOnFinishCallback } from '../generate-text';
 import { MockLanguageModelV3 } from '../test/mock-language-model-v3';
 import { AsyncIterableStream } from '../util/async-iterable-stream';
 import { DeepPartial } from '../util/deep-partial';
 import { AgentCallParameters, AgentStreamParameters } from './agent';
 import { ToolLoopAgent } from './tool-loop-agent';
+import { ToolLoopAgentOnFinishCallback } from './tool-loop-agent-on-finish-callback';
 
 describe('ToolLoopAgent', () => {
+  describe('onFinish callback type compatibility', () => {
+    it('should allow StreamTextOnFinishCallback where ToolLoopAgentOnFinishCallback is expected', () => {
+      const streamTextCallback: StreamTextOnFinishCallback<{}> =
+        async event => {
+          const context: unknown = event.experimental_context;
+          context;
+        };
+
+      expectTypeOf(streamTextCallback).toMatchTypeOf<
+        ToolLoopAgentOnFinishCallback<{}>
+      >();
+    });
+
+    it('should allow ToolLoopAgentOnFinishCallback where StreamTextOnFinishCallback is expected', () => {
+      const agentCallback: ToolLoopAgentOnFinishCallback<{}> = async event => {
+        const context: unknown = event.experimental_context;
+        context;
+      };
+
+      expectTypeOf(agentCallback).toMatchTypeOf<
+        StreamTextOnFinishCallback<{}>
+      >();
+    });
+  });
+
   describe('generate', () => {
     it('should not allow system prompt', async () => {
       const agent = new ToolLoopAgent({

Original file line number	Diff line number	Diff line change
`@@ -20,12 +20,12 @@ export type ToolLoopAgentOnFinishCallback<TOOLS extends ToolSet = {}> = (`
`20`	`20`	`readonly totalUsage: LanguageModelUsage;`
`21`	`21`
`22`	`22`	`/**`
`23`		`- * Context that is passed into tool calls.`
	`23`	`+ * Context that is passed into tool execution.`
`24`	`24`	`*`
`25`	`25`	`* Experimental (can break in patch releases).`
`26`	`26`	`*`
`27`	`27`	`* @default undefined`
`28`	`28`	`*/`
`29`		`- experimental_context?: unknown;`
	`29`	`+ experimental_context: unknown;`
`30`	`30`	`},`
`31`	`31`	`) => PromiseLike<void> \| void;`