ai 6.0.96 → 6.0.97

package/src/agent/agent.ts

@@ -5,7 +5,14 @@ import { StreamTextTransform } from '../generate-text/stream-text';
 import { StreamTextResult } from '../generate-text/stream-text-result';
 import { ToolSet } from '../generate-text/tool-set';
 import { TimeoutConfiguration } from '../prompt/call-settings';
-import { ToolLoopAgentOnStepFinishCallback } from './tool-loop-agent-on-step-finish-callback';
+import type {
+  ToolLoopAgentOnFinishCallback,
+  ToolLoopAgentOnStartCallback,
+  ToolLoopAgentOnStepFinishCallback,
+  ToolLoopAgentOnStepStartCallback,
+  ToolLoopAgentOnToolCallFinishCallback,
+  ToolLoopAgentOnToolCallStartCallback,
+} from './tool-loop-agent-settings';
 
 /**
  * Parameters for calling an agent.
@@ -57,10 +64,35 @@ export type AgentCallParameters<CALL_OPTIONS, TOOLS extends ToolSet = {}> = ([
      */
     timeout?: TimeoutConfiguration;
 
+    /**
+     * Callback that is called when the agent operation begins, before any LLM calls.
+     */
+    experimental_onStart?: ToolLoopAgentOnStartCallback<TOOLS>;
+
+    /**
+     * Callback that is called when a step (LLM call) begins, before the provider is called.
+     */
+    experimental_onStepStart?: ToolLoopAgentOnStepStartCallback<TOOLS>;
+
+    /**
+     * Callback that is called before each tool execution begins.
+     */
+    experimental_onToolCallStart?: ToolLoopAgentOnToolCallStartCallback<TOOLS>;
+
+    /**
+     * Callback that is called after each tool execution completes.
+     */
+    experimental_onToolCallFinish?: ToolLoopAgentOnToolCallFinishCallback<TOOLS>;
+
     /**
      * Callback that is called when each step (LLM call) is finished, including intermediate steps.
      */
     onStepFinish?: ToolLoopAgentOnStepFinishCallback<TOOLS>;
+
+    /**
+     * Callback that is called when all steps are finished and the response is complete.
+     */
+    onFinish?: ToolLoopAgentOnFinishCallback<TOOLS>;
   };
 
 /**

package/src/agent/create-agent-ui-stream-response.ts

@@ -7,7 +7,7 @@ import { UIMessageStreamResponseInit } from '../ui-message-stream/ui-message-str
 import { InferUITools, UIMessage } from '../ui/ui-messages';
 import { Agent } from './agent';
 import { createAgentUIStream } from './create-agent-ui-stream';
-import { ToolLoopAgentOnStepFinishCallback } from './tool-loop-agent-on-step-finish-callback';
+import type { ToolLoopAgentOnStepFinishCallback } from './tool-loop-agent-settings';
 
 /**
  * Runs the agent and returns a response object with a UI message stream.

package/src/agent/create-agent-ui-stream.ts

@@ -8,7 +8,7 @@ import { InferUITools, UIMessage } from '../ui/ui-messages';
 import { validateUIMessages } from '../ui/validate-ui-messages';
 import { AsyncIterableStream } from '../util/async-iterable-stream';
 import { Agent } from './agent';
-import { ToolLoopAgentOnStepFinishCallback } from './tool-loop-agent-on-step-finish-callback';
+import type { ToolLoopAgentOnStepFinishCallback } from './tool-loop-agent-settings';
 
 /**
  * Runs the agent and stream the output as a UI message stream.

package/src/agent/index.ts

@@ -3,9 +3,13 @@ export {
   type AgentCallParameters,
   type AgentStreamParameters,
 } from './agent';
-export { type ToolLoopAgentOnFinishCallback } from './tool-loop-agent-on-finish-callback';
-export { type ToolLoopAgentOnStepFinishCallback } from './tool-loop-agent-on-step-finish-callback';
 export {
+  type ToolLoopAgentOnFinishCallback,
+  type ToolLoopAgentOnStartCallback,
+  type ToolLoopAgentOnStepFinishCallback,
+  type ToolLoopAgentOnStepStartCallback,
+  type ToolLoopAgentOnToolCallFinishCallback,
+  type ToolLoopAgentOnToolCallStartCallback,
   type ToolLoopAgentSettings,
 
   /**

package/src/agent/pipe-agent-ui-stream-to-response.ts

@@ -8,7 +8,7 @@ import { UIMessageStreamResponseInit } from '../ui-message-stream/ui-message-str
 import { InferUITools, UIMessage } from '../ui/ui-messages';
 import { Agent } from './agent';
 import { createAgentUIStream } from './create-agent-ui-stream';
-import { ToolLoopAgentOnStepFinishCallback } from './tool-loop-agent-on-step-finish-callback';
+import type { ToolLoopAgentOnStepFinishCallback } from './tool-loop-agent-settings';
 
 /**
  * Pipes the agent UI message stream to a Node.js ServerResponse object.

package/src/agent/tool-loop-agent-settings.ts

@@ -4,6 +4,14 @@ import {
   ProviderOptions,
   SystemModelMessage,
 } from '@ai-sdk/provider-utils';
+import type {
+  OnFinishEvent,
+  OnStartEvent,
+  OnStepFinishEvent,
+  OnStepStartEvent,
+  OnToolCallFinishEvent,
+  OnToolCallStartEvent,
+} from '../generate-text/callback-events';
 import { Output } from '../generate-text/output';
 import { PrepareStepFunction } from '../generate-text/prepare-step';
 import { StopCondition } from '../generate-text/stop-condition';
@@ -15,8 +23,32 @@ import { TelemetrySettings } from '../telemetry/telemetry-settings';
 import { LanguageModel, ToolChoice } from '../types/language-model';
 import { DownloadFunction } from '../util/download/download-function';
 import { AgentCallParameters } from './agent';
-import { ToolLoopAgentOnFinishCallback } from './tool-loop-agent-on-finish-callback';
-import { ToolLoopAgentOnStepFinishCallback } from './tool-loop-agent-on-step-finish-callback';
+
+export type ToolLoopAgentOnStartCallback<
+  TOOLS extends ToolSet = ToolSet,
+  OUTPUT extends Output = Output,
+> = (event: OnStartEvent<TOOLS, OUTPUT>) => PromiseLike<void> | void;
+
+export type ToolLoopAgentOnStepStartCallback<
+  TOOLS extends ToolSet = ToolSet,
+  OUTPUT extends Output = Output,
+> = (event: OnStepStartEvent<TOOLS, OUTPUT>) => PromiseLike<void> | void;
+
+export type ToolLoopAgentOnToolCallStartCallback<
+  TOOLS extends ToolSet = ToolSet,
+> = (event: OnToolCallStartEvent<TOOLS>) => PromiseLike<void> | void;
+
+export type ToolLoopAgentOnToolCallFinishCallback<
+  TOOLS extends ToolSet = ToolSet,
+> = (event: OnToolCallFinishEvent<TOOLS>) => PromiseLike<void> | void;
+
+export type ToolLoopAgentOnStepFinishCallback<TOOLS extends ToolSet = {}> = (
+  stepResult: OnStepFinishEvent<TOOLS>,
+) => Promise<void> | void;
+
+export type ToolLoopAgentOnFinishCallback<TOOLS extends ToolSet = {}> = (
+  event: OnFinishEvent<TOOLS>,
+) => PromiseLike<void> | void;
 
 /**
  * Configuration options for an agent.
@@ -89,6 +121,33 @@ export type ToolLoopAgentSettings<
    */
   experimental_repairToolCall?: ToolCallRepairFunction<NoInfer<TOOLS>>;
 
+  /**
+   * Callback that is called when the agent operation begins, before any LLM calls.
+   */
+  experimental_onStart?: ToolLoopAgentOnStartCallback<NoInfer<TOOLS>, OUTPUT>;
+
+  /**
+   * Callback that is called when a step (LLM call) begins, before the provider is called.
+   */
+  experimental_onStepStart?: ToolLoopAgentOnStepStartCallback<
+    NoInfer<TOOLS>,
+    OUTPUT
+  >;
+
+  /**
+   * Callback that is called before each tool execution begins.
+   */
+  experimental_onToolCallStart?: ToolLoopAgentOnToolCallStartCallback<
+    NoInfer<TOOLS>
+  >;
+
+  /**
+   * Callback that is called after each tool execution completes.
+   */
+  experimental_onToolCallFinish?: ToolLoopAgentOnToolCallFinishCallback<
+    NoInfer<TOOLS>
+  >;
+
   /**
    * Callback that is called when each step (LLM call) is finished, including intermediate steps.
    */

package/src/agent/tool-loop-agent.ts

@@ -1,14 +1,12 @@
 import { generateText } from '../generate-text/generate-text';
 import { GenerateTextResult } from '../generate-text/generate-text-result';
 import { Output } from '../generate-text/output';
-import { StepResult } from '../generate-text/step-result';
 import { stepCountIs } from '../generate-text/stop-condition';
 import { streamText } from '../generate-text/stream-text';
 import { StreamTextResult } from '../generate-text/stream-text-result';
 import { ToolSet } from '../generate-text/tool-set';
 import { Prompt } from '../prompt';
 import { Agent, AgentCallParameters, AgentStreamParameters } from './agent';
-import { ToolLoopAgentOnStepFinishCallback } from './tool-loop-agent-on-step-finish-callback';
 import { ToolLoopAgentSettings } from './tool-loop-agent-settings';
 
 /**
@@ -57,15 +55,29 @@ export class ToolLoopAgent<
   }): Promise<
     Omit<
       ToolLoopAgentSettings<CALL_OPTIONS, TOOLS, OUTPUT>,
-      'prepareCall' | 'instructions' | 'onStepFinish'
+      | 'prepareCall'
+      | 'instructions'
+      | 'experimental_onStart'
+      | 'experimental_onStepStart'
+      | 'experimental_onToolCallStart'
+      | 'experimental_onToolCallFinish'
+      | 'onStepFinish'
+      | 'onFinish'
     > &
       Prompt
   > {
-    const { onStepFinish: _settingsOnStepFinish, ...settingsWithoutCallback } =
-      this.settings;
+    const {
+      experimental_onStart: _settingsOnStart,
+      experimental_onStepStart: _settingsOnStepStart,
+      experimental_onToolCallStart: _settingsOnToolCallStart,
+      experimental_onToolCallFinish: _settingsOnToolCallFinish,
+      onStepFinish: _settingsOnStepFinish,
+      onFinish: _settingsOnFinish,
+      ...settingsWithoutCallbacks
+    } = this.settings;
 
     const baseCallArgs = {
-      ...settingsWithoutCallback,
+      ...settingsWithoutCallbacks,
       stopWhen: this.settings.stopWhen ?? stepCountIs(20),
       ...options,
     };
@@ -89,19 +101,17 @@ export class ToolLoopAgent<
     };
   }
 
-  private mergeOnStepFinishCallbacks(
-    methodCallback: ToolLoopAgentOnStepFinishCallback<TOOLS> | undefined,
-  ): ToolLoopAgentOnStepFinishCallback<TOOLS> | undefined {
-    const constructorCallback = this.settings.onStepFinish;
-
-    if (methodCallback && constructorCallback) {
-      return async (stepResult: StepResult<TOOLS>) => {
-        await constructorCallback(stepResult);
-        await methodCallback(stepResult);
-      };
+  private mergeCallbacks<T extends (event: any) => PromiseLike<void> | void>(
+    settingsCallback: T | undefined,
+    methodCallback: T | undefined,
+  ): T | undefined {
+    if (methodCallback && settingsCallback) {
+      return (async (event: Parameters<T>[0]) => {
+        await settingsCallback(event);
+        await methodCallback(event);
+      }) as unknown as T;
     }
-
-    return methodCallback ?? constructorCallback;
+    return methodCallback ?? settingsCallback;
   }
 
   /**
@@ -110,7 +120,12 @@ export class ToolLoopAgent<
   async generate({
     abortSignal,
     timeout,
+    experimental_onStart,
+    experimental_onStepStart,
+    experimental_onToolCallStart,
+    experimental_onToolCallFinish,
     onStepFinish,
+    onFinish,
     ...options
   }: AgentCallParameters<CALL_OPTIONS, TOOLS>): Promise<
     GenerateTextResult<TOOLS, OUTPUT>
@@ -119,7 +134,27 @@ export class ToolLoopAgent<
       ...(await this.prepareCall(options)),
       abortSignal,
       timeout,
-      onStepFinish: this.mergeOnStepFinishCallbacks(onStepFinish),
+      experimental_onStart: this.mergeCallbacks(
+        this.settings.experimental_onStart,
+        experimental_onStart,
+      ),
+      experimental_onStepStart: this.mergeCallbacks(
+        this.settings.experimental_onStepStart,
+        experimental_onStepStart,
+      ),
+      experimental_onToolCallStart: this.mergeCallbacks(
+        this.settings.experimental_onToolCallStart,
+        experimental_onToolCallStart,
+      ),
+      experimental_onToolCallFinish: this.mergeCallbacks(
+        this.settings.experimental_onToolCallFinish,
+        experimental_onToolCallFinish,
+      ),
+      onStepFinish: this.mergeCallbacks(
+        this.settings.onStepFinish,
+        onStepFinish,
+      ),
+      onFinish: this.mergeCallbacks(this.settings.onFinish, onFinish),
     });
   }
 
@@ -130,7 +165,12 @@ export class ToolLoopAgent<
     abortSignal,
     timeout,
     experimental_transform,
+    experimental_onStart,
+    experimental_onStepStart,
+    experimental_onToolCallStart,
+    experimental_onToolCallFinish,
     onStepFinish,
+    onFinish,
     ...options
   }: AgentStreamParameters<CALL_OPTIONS, TOOLS>): Promise<
     StreamTextResult<TOOLS, OUTPUT>
@@ -140,7 +180,27 @@ export class ToolLoopAgent<
       abortSignal,
       timeout,
       experimental_transform,
-      onStepFinish: this.mergeOnStepFinishCallbacks(onStepFinish),
+      experimental_onStart: this.mergeCallbacks(
+        this.settings.experimental_onStart,
+        experimental_onStart,
+      ),
+      experimental_onStepStart: this.mergeCallbacks(
+        this.settings.experimental_onStepStart,
+        experimental_onStepStart,
+      ),
+      experimental_onToolCallStart: this.mergeCallbacks(
+        this.settings.experimental_onToolCallStart,
+        experimental_onToolCallStart,
+      ),
+      experimental_onToolCallFinish: this.mergeCallbacks(
+        this.settings.experimental_onToolCallFinish,
+        experimental_onToolCallFinish,
+      ),
+      onStepFinish: this.mergeCallbacks(
+        this.settings.onStepFinish,
+        onStepFinish,
+      ),
+      onFinish: this.mergeCallbacks(this.settings.onFinish, onFinish),
     });
   }
 }

package/src/agent/tool-loop-agent-on-finish-callback.ts

@@ -1,31 +0,0 @@
-import { StepResult } from '../generate-text/step-result';
-import { ToolSet } from '../generate-text/tool-set';
-import { LanguageModelUsage } from '../types/usage';
-
-/**
- * Callback that is set using the `onFinish` option.
- *
- * @param event - The event that is passed to the callback.
- */
-export type ToolLoopAgentOnFinishCallback<TOOLS extends ToolSet = {}> = (
-  event: StepResult<TOOLS> & {
-    /**
-     * Details for all steps.
-     */
-    readonly steps: StepResult<TOOLS>[];
-
-    /**
-     * Total usage for all steps. This is the sum of the usage of all steps.
-     */
-    readonly totalUsage: LanguageModelUsage;
-
-    /**
-     * Context that is passed into tool execution.
-     *
-     * Experimental (can break in patch releases).
-     *
-     * @default undefined
-     */
-    experimental_context: unknown;
-  },
-) => PromiseLike<void> | void;

package/src/agent/tool-loop-agent-on-step-finish-callback.ts

@@ -1,11 +0,0 @@
-import { StepResult } from '../generate-text/step-result';
-import { ToolSet } from '../generate-text/tool-set';
-
-/**
- * Callback that is set using the `onStepFinish` option.
- *
- * @param stepResult - The result of the step.
- */
-export type ToolLoopAgentOnStepFinishCallback<TOOLS extends ToolSet = {}> = (
-  stepResult: StepResult<TOOLS>,
-) => Promise<void> | void;