@ai-sdk/workflow 1.0.0-beta.9 → 1.0.0-canary.33

package/src/workflow-agent.ts

@@ -7,21 +7,24 @@ import type {
   SharedV4ProviderOptions,
 } from '@ai-sdk/provider';
 import {
-  type Experimental_LanguageModelStreamPart as ModelCallStreamPart,
+  Output,
+  experimental_filterActiveTools as filterActiveTools,
   type FinishReason,
   type LanguageModelResponseMetadata,
   type LanguageModelUsage,
+  type Experimental_LanguageModelStreamPart as ModelCallStreamPart,
   type ModelMessage,
-  Output,
   type StepResult,
   type StopCondition,
-  type StreamTextOnStepFinishCallback,
+  type GenerateTextOnStepFinishCallback,
   type SystemModelMessage,
+  type ActiveTools,
   type ToolCallRepairFunction,
   type ToolChoice,
   type ToolSet,
   type UIMessage,
-  LanguageModel,
+  type LanguageModel,
+  type Prompt,
 } from 'ai';
 import {
   convertToLanguageModelPrompt,
@@ -30,19 +33,18 @@ import {
   standardizePrompt,
 } from 'ai/internal';
 import { streamTextIterator } from './stream-text-iterator.js';
-import type { CompatibleLanguageModel } from './types.js';
 
 // Re-export for consumers
 export type { CompatibleLanguageModel } from './types.js';
 
 /**
  * Callback function to be called after each step completes.
- * Alias for the AI SDK's StreamTextOnStepFinishCallback, using
+ * Alias for the AI SDK's GenerateTextOnStepFinishCallback, using
  * WorkflowAgent-consistent naming.
  */
 export type WorkflowAgentOnStepFinishCallback<
   TTools extends ToolSet = ToolSet,
-> = StreamTextOnStepFinishCallback<TTools, any>;
+> = GenerateTextOnStepFinishCallback<TTools, any>;
 
 /**
  * Infer the type of the tools of a workflow agent.
@@ -92,7 +94,7 @@ export type ProviderOptions = SharedV4ProviderOptions;
 /**
  * Telemetry settings for observability.
  */
-export interface TelemetrySettings {
+export interface TelemetryOptions {
   /**
    * Enable or disable telemetry. Defaults to true.
    */
@@ -339,7 +341,11 @@ export interface PrepareCallOptions<
   tools: TTools;
   instructions?: string | SystemModelMessage | Array<SystemModelMessage>;
   toolChoice?: ToolChoice<TTools>;
-  experimental_telemetry?: TelemetrySettings;
+  telemetry?: TelemetryOptions;
+  /**
+   * @deprecated Use `telemetry` instead. This alias will be removed in a future major release.
+   */
+  experimental_telemetry?: TelemetryOptions;
   experimental_context?: unknown;
   messages: ModelMessage[];
 }
@@ -405,9 +411,16 @@ export interface WorkflowAgentOptions<
   toolChoice?: ToolChoice<TTools>;
 
   /**
-   * Optional telemetry configuration (experimental).
+   * Optional telemetry configuration.
    */
-  experimental_telemetry?: TelemetrySettings;
+  telemetry?: TelemetryOptions;
+
+  /**
+   * Optional telemetry configuration.
+   *
+   * @deprecated Use `telemetry` instead. This alias will be removed in a future major release.
+   */
+  experimental_telemetry?: TelemetryOptions;
 
   /**
    * Default context that is passed into tool execution for every stream call on this agent.
@@ -434,7 +447,7 @@ export interface WorkflowAgentOptions<
    *
    * Per-stream `activeTools` values passed to `stream()` override this default.
    */
-  activeTools?: Array<keyof NoInfer<TTools>>;
+  activeTools?: ActiveTools<NoInfer<TTools>>;
 
   /**
    * Default output specification for structured outputs.
@@ -490,12 +503,12 @@ export interface WorkflowAgentOptions<
   /**
    * Callback called before a tool's execute function runs.
    */
-  experimental_onToolCallStart?: WorkflowAgentOnToolCallStartCallback;
+  experimental_onToolExecutionStart?: WorkflowAgentOnToolExecutionStartCallback;
 
   /**
    * Callback called after a tool execution completes.
    */
-  experimental_onToolCallFinish?: WorkflowAgentOnToolCallFinishCallback;
+  experimental_onToolExecutionEnd?: WorkflowAgentOnToolExecutionEndCallback;
 
   /**
    * Prepare the parameters for the stream call.
@@ -595,7 +608,7 @@ export type WorkflowAgentOnStepStartCallback<TTools extends ToolSet = ToolSet> =
 /**
  * Callback that is called before a tool's execute function runs.
  */
-export type WorkflowAgentOnToolCallStartCallback = (event: {
+export type WorkflowAgentOnToolExecutionStartCallback = (event: {
   /** The tool call being executed */
   readonly toolCall: ToolCall;
   /** The current step number (0-based) */
@@ -607,7 +620,7 @@ export type WorkflowAgentOnToolCallStartCallback = (event: {
  * Uses a discriminated union pattern: check `success` to determine
  * whether `output` or `error` is available.
  */
-export type WorkflowAgentOnToolCallFinishCallback = (
+export type WorkflowAgentOnToolExecutionEndCallback = (
   event:
     | {
         /** The tool call that was executed */
@@ -714,13 +727,6 @@ export type WorkflowAgentStreamOptions<
       | StopCondition<NoInfer<ToolSet>, any>
       | Array<StopCondition<NoInfer<ToolSet>, any>>;
 
-    /**
-     * Maximum number of sequential LLM calls (steps), e.g. when you use tool calls.
-     * A maximum number can be set to prevent infinite loops in the case of misconfigured tools.
-     * By default, it's unlimited (the agent loops until completion).
-     */
-    maxSteps?: number;
-
     /**
      * The tool choice strategy. Default: 'auto'.
      * Overrides the toolChoice from the constructor if provided.
@@ -731,12 +737,19 @@ export type WorkflowAgentStreamOptions<
      * Limits the tools that are available for the model to call without
      * changing the tool call and result types in the result.
      */
-    activeTools?: Array<keyof NoInfer<TTools>>;
+    activeTools?: ActiveTools<NoInfer<TTools>>;
+
+    /**
+     * Optional telemetry configuration.
+     */
+    telemetry?: TelemetryOptions;
 
     /**
-     * Optional telemetry configuration (experimental).
+     * Optional telemetry configuration.
+     *
+     * @deprecated Use `telemetry` instead. This alias will be removed in a future major release.
      */
-    experimental_telemetry?: TelemetrySettings;
+    experimental_telemetry?: TelemetryOptions;
 
     /**
      * Context that is passed into tool execution.
@@ -833,12 +846,12 @@ export type WorkflowAgentStreamOptions<
     /**
      * Callback called before a tool's execute function runs.
      */
-    experimental_onToolCallStart?: WorkflowAgentOnToolCallStartCallback;
+    experimental_onToolExecutionStart?: WorkflowAgentOnToolExecutionStartCallback;
 
     /**
      * Callback called after a tool execution completes.
      */
-    experimental_onToolCallFinish?: WorkflowAgentOnToolCallFinishCallback;
+    experimental_onToolExecutionEnd?: WorkflowAgentOnToolExecutionEndCallback;
 
     /**
      * Callback function called before each step in the agent loop.
@@ -1005,12 +1018,12 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
     | Array<SystemModelMessage>;
   private generationSettings: GenerationSettings;
   private toolChoice?: ToolChoice<TBaseTools>;
-  private telemetry?: TelemetrySettings;
+  private telemetry?: TelemetryOptions;
   private experimentalContext: unknown;
   private stopWhen?:
     | StopCondition<ToolSet, any>
     | Array<StopCondition<ToolSet, any>>;
-  private activeTools?: Array<keyof TBaseTools>;
+  private activeTools?: ActiveTools<TBaseTools>;
   private output?: OutputSpecification<any, any>;
   private experimentalRepairToolCall?: ToolCallRepairFunction<TBaseTools>;
   private experimentalDownload?: DownloadFunction;
@@ -1019,8 +1032,8 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
   private constructorOnFinish?: WorkflowAgentOnFinishCallback<ToolSet>;
   private constructorOnStart?: WorkflowAgentOnStartCallback;
   private constructorOnStepStart?: WorkflowAgentOnStepStartCallback;
-  private constructorOnToolCallStart?: WorkflowAgentOnToolCallStartCallback;
-  private constructorOnToolCallFinish?: WorkflowAgentOnToolCallFinishCallback;
+  private constructorOnToolExecutionStart?: WorkflowAgentOnToolExecutionStartCallback;
+  private constructorOnToolExecutionEnd?: WorkflowAgentOnToolExecutionEndCallback;
   private prepareCall?: PrepareCallCallback<TBaseTools>;
 
   constructor(options: WorkflowAgentOptions<TBaseTools>) {
@@ -1030,7 +1043,7 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
     // `instructions` takes precedence over deprecated `system`
     this.instructions = options.instructions ?? options.system;
     this.toolChoice = options.toolChoice;
-    this.telemetry = options.experimental_telemetry;
+    this.telemetry = options.telemetry ?? options.experimental_telemetry;
     this.experimentalContext = options.experimental_context;
     this.stopWhen = options.stopWhen;
     this.activeTools = options.activeTools;
@@ -1042,8 +1055,10 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
     this.constructorOnFinish = options.onFinish;
     this.constructorOnStart = options.experimental_onStart;
     this.constructorOnStepStart = options.experimental_onStepStart;
-    this.constructorOnToolCallStart = options.experimental_onToolCallStart;
-    this.constructorOnToolCallFinish = options.experimental_onToolCallFinish;
+    this.constructorOnToolExecutionStart =
+      options.experimental_onToolExecutionStart;
+    this.constructorOnToolExecutionEnd =
+      options.experimental_onToolExecutionEnd;
     this.prepareCall = options.prepareCall;
 
     // Extract generation settings
@@ -1085,7 +1100,7 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
       options.experimental_context ?? this.experimentalContext;
     let effectiveToolChoiceFromPrepare = options.toolChoice ?? this.toolChoice;
     let effectiveTelemetryFromPrepare =
-      options.experimental_telemetry ?? this.telemetry;
+      options.telemetry ?? options.experimental_telemetry ?? this.telemetry;
 
     // Resolve messages for prepareCall: use messages directly, or convert prompt
     const resolvedMessagesForPrepareCall: ModelMessage[] =
@@ -1101,6 +1116,7 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
         tools: this.tools,
         instructions: effectiveInstructions,
         toolChoice: effectiveToolChoiceFromPrepare as ToolChoice<TBaseTools>,
+        telemetry: effectiveTelemetryFromPrepare,
         experimental_telemetry: effectiveTelemetryFromPrepare,
         experimental_context: effectiveExperimentalContext,
         messages: resolvedMessagesForPrepareCall,
@@ -1119,7 +1135,9 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
       if (prepared.toolChoice !== undefined)
         effectiveToolChoiceFromPrepare =
           prepared.toolChoice as ToolChoice<TBaseTools>;
-      if (prepared.experimental_telemetry !== undefined)
+      if (prepared.telemetry !== undefined)
+        effectiveTelemetryFromPrepare = prepared.telemetry;
+      else if (prepared.experimental_telemetry !== undefined)
         effectiveTelemetryFromPrepare = prepared.experimental_telemetry;
       if (prepared.maxOutputTokens !== undefined)
         effectiveGenerationSettings.maxOutputTokens = prepared.maxOutputTokens;
@@ -1146,10 +1164,11 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
 
     const prompt = await standardizePrompt({
       system: effectiveInstructions,
+      allowSystemInMessages: true, // TODO: consider exposing this as a parameter
       ...(effectivePrompt != null
         ? { prompt: effectivePrompt }
         : { messages: effectiveMessages! }),
-    });
+    } as Prompt);
 
     // Process tool approval responses before starting the agent loop.
     // This mirrors how stream-text.ts handles tool-approval-response parts:
@@ -1282,9 +1301,7 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
 
     const effectiveAbortSignal = mergeAbortSignals(
       options.abortSignal ?? effectiveGenerationSettings.abortSignal,
-      options.timeout != null
-        ? AbortSignal.timeout(options.timeout)
-        : undefined,
+      options.timeout,
     );
 
     // Merge generation settings: constructor defaults < prepareCall < stream options
@@ -1341,13 +1358,13 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
       this.constructorOnStepStart,
       options.experimental_onStepStart,
     );
-    const mergedOnToolCallStart = mergeCallbacks(
-      this.constructorOnToolCallStart,
-      options.experimental_onToolCallStart,
+    const mergedOnToolExecutionStart = mergeCallbacks(
+      this.constructorOnToolExecutionStart,
+      options.experimental_onToolExecutionStart,
     );
-    const mergedOnToolCallFinish = mergeCallbacks(
-      this.constructorOnToolCallFinish,
-      options.experimental_onToolCallFinish,
+    const mergedOnToolExecutionEnd = mergeCallbacks(
+      this.constructorOnToolExecutionEnd,
+      options.experimental_onToolExecutionEnd,
     );
 
     // Determine effective tool choice
@@ -1360,7 +1377,10 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
     const effectiveActiveTools = options.activeTools ?? this.activeTools;
     const effectiveTools =
       effectiveActiveTools && effectiveActiveTools.length > 0
-        ? filterTools(this.tools, effectiveActiveTools as string[])
+        ? (filterActiveTools({
+            tools: this.tools,
+            activeTools: effectiveActiveTools,
+          }) ?? this.tools)
         : this.tools;
 
     // Initialize context
@@ -1380,7 +1400,7 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
       });
     }
 
-    // Helper to wrap executeTool with onToolCallStart/onToolCallFinish callbacks
+    // Helper to wrap executeTool with onToolExecutionStart/onToolExecutionEnd callbacks
     const executeToolWithCallbacks = async (
       toolCall: { toolCallId: string; toolName: string; input: unknown },
       tools: ToolSet,
@@ -1395,8 +1415,8 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
         input: toolCall.input,
       };
 
-      if (mergedOnToolCallStart) {
-        await mergedOnToolCallStart({
+      if (mergedOnToolExecutionStart) {
+        await mergedOnToolExecutionStart({
           toolCall: toolCallEvent,
           stepNumber: currentStepNumber,
         });
@@ -1408,8 +1428,8 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
         result = await executeTool(toolCall, tools, messages, context);
       } catch (err) {
         const durationMs = Date.now() - startTime;
-        if (mergedOnToolCallFinish) {
-          await mergedOnToolCallFinish({
+        if (mergedOnToolExecutionEnd) {
+          await mergedOnToolExecutionEnd({
             toolCall: toolCallEvent,
             stepNumber: currentStepNumber,
             durationMs,
@@ -1421,14 +1441,14 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
       }
 
       const durationMs = Date.now() - startTime;
-      if (mergedOnToolCallFinish) {
+      if (mergedOnToolExecutionEnd) {
         const isError =
           result.output &&
           'type' in result.output &&
           (result.output.type === 'error-text' ||
             result.output.type === 'error-json');
         if (isError) {
-          await mergedOnToolCallFinish({
+          await mergedOnToolExecutionEnd({
             toolCall: toolCallEvent,
             stepNumber: currentStepNumber,
             durationMs,
@@ -1436,7 +1456,7 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
             error: 'value' in result.output ? result.output.value : undefined,
           });
         } else {
-          await mergedOnToolCallFinish({
+          await mergedOnToolExecutionEnd({
             toolCall: toolCallEvent,
             stepNumber: currentStepNumber,
             durationMs,
@@ -1471,7 +1491,7 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
       writable: options.writable,
       prompt: modelPrompt,
       stopConditions: options.stopWhen ?? this.stopWhen,
-      maxSteps: options.maxSteps,
+
       onStepFinish: mergedOnStepFinish,
       onStepStart: mergedOnStepStart,
       onError: options.onError,
@@ -1481,7 +1501,7 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
       generationSettings: mergedGenerationSettings,
       toolChoice: effectiveToolChoice as ToolChoice<ToolSet>,
       experimental_context: experimentalContext,
-      experimental_telemetry: effectiveTelemetry,
+      telemetry: effectiveTelemetry,
       includeRawChunks: options.includeRawChunks ?? false,
       repairToolCall: (options.experimental_repairToolCall ??
         this.experimentalRepairToolCall) as
@@ -1525,11 +1545,16 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
 
         // Only execute tools if there are tool calls
         if (toolCalls.length > 0) {
+          const invalidToolCalls = toolCalls.filter(tc => tc.invalid === true);
+          const validToolCalls = toolCalls.filter(tc => tc.invalid !== true);
+
           // Separate provider-executed tool calls from client-executed ones
-          const nonProviderToolCalls = toolCalls.filter(
+          const nonProviderToolCalls = validToolCalls.filter(
             tc => !tc.providerExecuted,
           );
-          const providerToolCalls = toolCalls.filter(tc => tc.providerExecuted);
+          const providerToolCalls = validToolCalls.filter(
+            tc => tc.providerExecuted,
+          );
 
           // Check which tools need approval (can be async)
           const approvalNeeded = await Promise.all(
@@ -1593,7 +1618,15 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
                 ),
               );
 
-            const resolvedResults = [...executableResults, ...providerResults];
+            const continuationInvalidResults = invalidToolCalls.map(
+              createInvalidToolResult,
+            );
+            const resolvedResults = [
+              ...executableResults,
+              ...providerResults,
+              ...continuationInvalidResults,
+            ];
+            const executedResults = [...executableResults, ...providerResults];
 
             const allToolCalls: ToolCall[] = toolCalls.map(tc => ({
               type: 'tool-call' as const,
@@ -1602,7 +1635,7 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
               input: tc.input,
             }));
 
-            const allToolResults: ToolResult[] = resolvedResults.map(r => ({
+            const allToolResults: ToolResult[] = executedResults.map(r => ({
               type: 'tool-result' as const,
               toolCallId: r.toolCallId,
               toolName: r.toolName,
@@ -1690,25 +1723,32 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
             providerToolCalls.map(toolCall =>
               resolveProviderToolResult(toolCall, providerExecutedToolResults),
             );
+          const continuationInvalidToolResults = invalidToolCalls.map(
+            createInvalidToolResult,
+          );
 
-          // Combine results in the original order
-          const toolResults = toolCalls.map(tc => {
+          // Combine executable/provider results in the original order,
+          // while preserving invalid tool calls as error results for the
+          // next model step without emitting them as synthetic UI success.
+          const continuationToolResults = toolCalls.flatMap(tc => {
+            const invalidResult = continuationInvalidToolResults.find(
+              r => r.toolCallId === tc.toolCallId,
+            );
+            if (invalidResult) return [invalidResult];
             const clientResult = clientToolResults.find(
               r => r.toolCallId === tc.toolCallId,
             );
-            if (clientResult) return clientResult;
+            if (clientResult) return [clientResult];
             const providerResult = providerToolResults.find(
               r => r.toolCallId === tc.toolCallId,
             );
-            if (providerResult) return providerResult;
-            // This should never happen, but return empty result as fallback
-            return {
-              type: 'tool-result' as const,
-              toolCallId: tc.toolCallId,
-              toolName: tc.toolName,
-              output: { type: 'text' as const, value: '' },
-            };
+            if (providerResult) return [providerResult];
+            return [];
           });
+          const executedToolResults = continuationToolResults.filter(
+            result =>
+              !invalidToolCalls.some(tc => tc.toolCallId === result.toolCallId),
+          );
 
           // Write tool results and step boundaries to the stream so the
           // UI can transition tool parts to output-available state and
@@ -1716,7 +1756,7 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
           if (options.writable) {
             await writeToolResultsWithStepBoundary(
               options.writable,
-              toolResults.map(r => ({
+              executedToolResults.map(r => ({
                 toolCallId: r.toolCallId,
                 toolName: r.toolName,
                 input: toolCalls.find(tc => tc.toolCallId === r.toolCallId)
@@ -1733,7 +1773,7 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
             toolName: tc.toolName,
             input: tc.input,
           }));
-          lastStepToolResults = toolResults.map(r => ({
+          lastStepToolResults = executedToolResults.map(r => ({
             type: 'tool-result' as const,
             toolCallId: r.toolCallId,
             toolName: r.toolName,
@@ -1741,7 +1781,7 @@ export class WorkflowAgent<TBaseTools extends ToolSet = ToolSet> {
             output: 'value' in r.output ? r.output.value : undefined,
           }));
 
-          result = await iterator.next(toolResults);
+          result = await iterator.next(continuationToolResults);
         } else {
           // Final step with no tool calls - reset tracking
           lastStepToolCalls = [];
@@ -1979,19 +2019,6 @@ function aggregateUsage(steps: StepResult<any, any>[]): LanguageModelUsage {
   } as LanguageModelUsage;
 }
 
-function filterTools<TTools extends ToolSet>(
-  tools: TTools,
-  activeTools: string[],
-): ToolSet {
-  const filtered: ToolSet = {};
-  for (const toolName of activeTools) {
-    if (toolName in tools) {
-      filtered[toolName] = tools[toolName];
-    }
-  }
-  return filtered;
-}
-
 // Matches AI SDK's getErrorMessage from @ai-sdk/provider-utils
 function getErrorMessage(error: unknown): string {
   if (error == null) {
@@ -2056,6 +2083,22 @@ function resolveProviderToolResult(
   };
 }
 
+function createInvalidToolResult(toolCall: {
+  toolCallId: string;
+  toolName: string;
+  error?: unknown;
+}): LanguageModelV4ToolResultPart {
+  return {
+    type: 'tool-result' as const,
+    toolCallId: toolCall.toolCallId,
+    toolName: toolCall.toolName,
+    output: {
+      type: 'error-text' as const,
+      value: getErrorMessage(toolCall.error),
+    },
+  };
+}
+
 async function executeTool(
   toolCall: { toolCallId: string; toolName: string; input: unknown },
   tools: ToolSet,

package/src/workflow-chat-transport.ts

@@ -1,12 +1,12 @@
 import {
+  parseJsonEventStream,
+  uiMessageChunkSchema,
   type ChatRequestOptions,
   type ChatTransport,
   type PrepareReconnectToStreamRequest,
   type PrepareSendMessagesRequest,
-  parseJsonEventStream,
   type UIMessage,
   type UIMessageChunk,
-  uiMessageChunkSchema,
 } from 'ai';
 import {
   convertAsyncIteratorToReadableStream,