@ai-sdk/workflow 2.0.70 → 2.0.72

package/src/workflow-agent.ts

@@ -51,6 +51,8 @@ import {
   convertToLanguageModelPrompt,
   mergeAbortSignals,
   mergeCallbacks,
+  mapWithConcurrency,
+  prepareToolCallConcurrency,
   signToolApproval,
   standardizePrompt,
   validateApprovedToolApprovals,
@@ -426,6 +428,7 @@ export interface PrepareCallOptions<
   tools: TTools;
   instructions?: Instructions;
   toolChoice?: ToolChoice<TTools>;
+  toolCallConcurrency?: number;
   stopWhen?:
     | StopCondition<NoInfer<TTools>, TRuntimeContext>
     | Array<StopCondition<NoInfer<TTools>, TRuntimeContext>>;
@@ -514,6 +517,13 @@ export type WorkflowAgentOptions<
      */
     toolChoice?: ToolChoice<TTools>;
 
+    /**
+     * Maximum number of local tool calls that may execute concurrently within a step.
+     * Set to `1` to execute calls sequentially in model order, including approved
+     * calls. By default, all local tool calls execute concurrently.
+     */
+    toolCallConcurrency?: number;
+
     /**
      * Optional telemetry configuration.
      */
@@ -578,6 +588,7 @@ export type WorkflowAgentOptions<
 
     /**
      * Default custom download function to use for URLs.
+     * Mark the function with `'use step'` when used in a workflow.
      *
      * Per-stream `experimental_download` values passed to `stream()` override this default.
      */
@@ -998,6 +1009,13 @@ export type WorkflowAgentCallOptions<
      */
     toolChoice?: ToolChoice<TTools>;
 
+    /**
+     * Maximum number of local tool calls that may execute concurrently within a step.
+     * Set to `1` to execute calls sequentially in model order, including approved
+     * calls. By default, all local tool calls execute concurrently.
+     */
+    toolCallConcurrency?: number;
+
     /**
      * Limits the tools that are available for the model to call without
      * changing the tool call and result types in the result.
@@ -1074,6 +1092,7 @@ export type WorkflowAgentCallOptions<
     /**
      * Custom download function to use for URLs.
      * By default, files are downloaded if the model does not support the URL for the given media type.
+     * Mark the function with `'use step'` when used in a workflow.
      */
     experimental_download?: DownloadFunction;
 
@@ -1538,6 +1557,7 @@ export class WorkflowAgent<
   private instructions?: Instructions;
   private generationSettings: GenerationSettings;
   private toolChoice?: ToolChoice<TBaseTools>;
+  private toolCallConcurrency?: number;
   private telemetry?: TelemetryOptions<TRuntimeContext, TBaseTools>;
   private runtimeContext?: TRuntimeContext;
   private toolsContext?: InferToolSetContext<TBaseTools>;
@@ -1586,6 +1606,7 @@ export class WorkflowAgent<
     // `instructions` takes precedence over deprecated `system`
     this.instructions = options.instructions ?? options.system;
     this.toolChoice = options.toolChoice;
+    this.toolCallConcurrency = options.toolCallConcurrency;
     this.telemetry = options.telemetry;
     this.runtimeContext = options.runtimeContext;
     this.toolsContext = options.toolsContext;
@@ -1725,6 +1746,8 @@ export class WorkflowAgent<
         Context | undefined
       >;
     let effectiveToolChoiceFromPrepare = options.toolChoice ?? this.toolChoice;
+    let effectiveToolCallConcurrency =
+      options.toolCallConcurrency ?? this.toolCallConcurrency;
     let effectiveStopWhenFromPrepare =
       options.stopWhen ??
       this.stopWhen ??
@@ -1752,6 +1775,7 @@ export class WorkflowAgent<
         tools: this.tools,
         instructions: effectiveInstructions,
         toolChoice: effectiveToolChoiceFromPrepare as ToolChoice<TBaseTools>,
+        toolCallConcurrency: effectiveToolCallConcurrency,
         stopWhen: effectiveStopWhenFromPrepare,
         activeTools: effectiveActiveToolsFromPrepare,
         experimental_download: effectiveDownloadFromPrepare,
@@ -1779,6 +1803,8 @@ export class WorkflowAgent<
       if (prepared.toolChoice !== undefined)
         effectiveToolChoiceFromPrepare =
           prepared.toolChoice as ToolChoice<TBaseTools>;
+      if (prepared.toolCallConcurrency !== undefined)
+        effectiveToolCallConcurrency = prepared.toolCallConcurrency;
       if (prepared.stopWhen !== undefined)
         effectiveStopWhenFromPrepare = prepared.stopWhen;
       if (prepared.activeTools !== undefined)
@@ -1816,6 +1842,9 @@ export class WorkflowAgent<
         effectiveGenerationSettings.providerOptions = prepared.providerOptions;
     }
 
+    const toolCallConcurrency = prepareToolCallConcurrency(
+      options.toolCallConcurrency ?? effectiveToolCallConcurrency,
+    );
     const effectiveTelemetry = effectiveTelemetryFromPrepare;
     const telemetryDispatcher = createRestrictedTelemetryDispatcher<
       any,
@@ -1834,7 +1863,8 @@ export class WorkflowAgent<
         ? { prompt: effectivePrompt }
         : { messages: effectiveMessages! }),
     } as Prompt);
-    const download = effectiveDownloadFromPrepare;
+    const workflowDownload: DownloadFunction = async requests =>
+      requests.map(() => null);
     const sandbox = options.experimental_sandbox ?? this.experimentalSandbox;
     // Model steps enforce the absolute deadline below. Avoid creating a native
     // timeout signal in the workflow VM, where timer APIs are unavailable.
@@ -1866,13 +1896,15 @@ export class WorkflowAgent<
       effectiveRuntimeContext,
       effectiveToolsContext,
       effectiveToolChoiceFromPrepare,
+      toolCallConcurrency,
       effectiveStopWhenFromPrepare,
       effectiveActiveToolsFromPrepare,
       effectiveToolApprovalSecret,
       effectiveTelemetry,
       telemetryDispatcher,
       prompt,
-      download,
+      download: effectiveDownloadFromPrepare,
+      workflowDownload,
       sandbox,
       effectiveAbortSignal,
       timeoutAt,
@@ -1902,6 +1934,7 @@ export class WorkflowAgent<
       effectiveRuntimeContext,
       effectiveToolsContext,
       effectiveToolChoiceFromPrepare,
+      toolCallConcurrency,
       effectiveStopWhenFromPrepare,
       effectiveActiveToolsFromPrepare,
       effectiveToolApprovalSecret,
@@ -1909,6 +1942,7 @@ export class WorkflowAgent<
       telemetryDispatcher,
       prompt,
       download,
+      workflowDownload,
       sandbox,
       effectiveAbortSignal,
       timeoutAt,
@@ -1980,52 +2014,56 @@ export class WorkflowAgent<
         output: unknown;
       }> = [];
 
-      // Execute approved tools
-      for (const approval of approvedToolApprovals) {
-        // Provider-executed approvals are forwarded to the provider via the
-        // preserved approval response below, not executed locally.
-        if (approval.providerExecuted) {
-          continue;
-        }
-        const tool = (this.tools as ToolSet)[approval.toolName];
-        if (tool && typeof tool.execute === 'function') {
-          if (!tool.needsApproval) {
-            const reason = `Tool "${approval.toolName}" does not require approval`;
-            toolResultContent.push({
-              type: 'tool-result' as const,
-              toolCallId: approval.toolCallId,
-              toolName: approval.toolName,
-              output: await createLanguageModelToolResultOutput({
+      // Execute approved calls in model order with the same limit as new calls.
+      const approvedResults = await mapWithConcurrency({
+        items: approvedToolApprovals.filter(
+          approval => !approval.providerExecuted,
+        ),
+        concurrency: toolCallConcurrency,
+        abortSignal: effectiveAbortSignal,
+        execute: async approval => {
+          const tool = (this.tools as ToolSet)[approval.toolName];
+          if (tool && typeof tool.execute === 'function') {
+            if (!tool.needsApproval) {
+              const reason = `Tool "${approval.toolName}" does not require approval`;
+              return {
+                modelResult: {
+                  type: 'tool-result' as const,
+                  toolCallId: approval.toolCallId,
+                  toolName: approval.toolName,
+                  output: await createLanguageModelToolResultOutput({
+                    toolCallId: approval.toolCallId,
+                    toolName: approval.toolName,
+                    input: approval.input,
+                    output: reason,
+                    tool,
+                    errorMode: 'text',
+                    supportedUrls: {},
+                    download: workflowDownload,
+                  }),
+                },
+              };
+            }
+
+            // Re-validate through the shared core implementation: input schema,
+            // approval signature (when configured), and approval policy.
+            // Convert invalid input, denial, or signature errors to a tool error
+            // result so the agent loop can continue gracefully.
+            let revalidationReason: string | undefined;
+            try {
+              await validateWorkflowToolApprovalSignature({
+                secret: effectiveToolApprovalSecret,
+                approvalId: approval.collected.approvalRequest.approvalId,
                 toolCallId: approval.toolCallId,
                 toolName: approval.toolName,
                 input: approval.input,
-                output: reason,
-                tool,
-                errorMode: 'text',
-                supportedUrls: {},
-                download,
-              }),
-            });
-            continue;
-          }
-
-          // Re-validate through the shared core implementation: input schema,
-          // approval signature (when configured), and approval policy.
-          // Convert invalid input, denial, or signature errors to a tool error
-          // result so the agent loop can continue gracefully.
-          let revalidationReason: string | undefined;
-          try {
-            await validateWorkflowToolApprovalSignature({
-              secret: effectiveToolApprovalSecret,
-              approvalId: approval.collected.approvalRequest.approvalId,
-              toolCallId: approval.toolCallId,
-              toolName: approval.toolName,
-              input: approval.input,
-              signature: approval.collected.approvalRequest.signature,
-            });
+                signature: approval.collected.approvalRequest.signature,
+              });
 
-            const { deniedToolApprovals: policyDenied, invalidToolApprovals } =
-              await validateApprovedToolApprovals({
+              const {
+                deniedToolApprovals: policyDenied,
+                invalidToolApprovals,
+              } = await validateApprovedToolApprovals({
                 approvedToolApprovals: [approval.collected],
                 tools: this.tools as ToolSet,
                 toolApproval: undefined,
@@ -2035,58 +2073,67 @@ export class WorkflowAgent<
                 runtimeContext: effectiveRuntimeContext,
               });
 
-            if (invalidToolApprovals.length > 0) {
-              revalidationReason = getErrorMessage(
-                invalidToolApprovals[0].error,
-              );
-            } else if (policyDenied.length > 0) {
-              revalidationReason =
-                policyDenied[0].approvalResponse.reason ??
-                'Tool approval denied';
+              if (invalidToolApprovals.length > 0) {
+                revalidationReason = getErrorMessage(
+                  invalidToolApprovals[0].error,
+                );
+              } else if (policyDenied.length > 0) {
+                revalidationReason =
+                  policyDenied[0].approvalResponse.reason ??
+                  'Tool approval denied';
+              }
+            } catch (error) {
+              revalidationReason = getErrorMessage(error);
             }
-          } catch (error) {
-            revalidationReason = getErrorMessage(error);
-          }
 
-          if (revalidationReason != null) {
-            toolResultContent.push({
-              type: 'tool-result' as const,
-              toolCallId: approval.toolCallId,
-              toolName: approval.toolName,
-              output: await createLanguageModelToolResultOutput({
+            if (revalidationReason != null) {
+              return {
+                modelResult: {
+                  type: 'tool-result' as const,
+                  toolCallId: approval.toolCallId,
+                  toolName: approval.toolName,
+                  output: await createLanguageModelToolResultOutput({
+                    toolCallId: approval.toolCallId,
+                    toolName: approval.toolName,
+                    input: approval.input,
+                    output: revalidationReason,
+                    tool,
+                    errorMode: 'text',
+                    supportedUrls: {},
+                    download: workflowDownload,
+                  }),
+                },
+              };
+            }
+
+            const result = await executeToolWithCallbacks(
+              {
                 toolCallId: approval.toolCallId,
                 toolName: approval.toolName,
                 input: approval.input,
-                output: revalidationReason,
-                tool,
-                errorMode: 'text',
-                supportedUrls: {},
-                download,
-              }),
-            });
-            continue;
+              },
+              this.tools as ToolSet,
+              prompt.messages as unknown as LanguageModelV4Prompt,
+              effectiveToolsContext,
+              0,
+              sandbox,
+            );
+            return {
+              modelResult: result.modelResult,
+              rawResult: {
+                toolCallId: approval.toolCallId,
+                toolName: approval.toolName,
+                input: approval.input,
+                output: result.rawOutput,
+              },
+            };
           }
-
-          const result = await executeToolWithCallbacks(
-            {
-              toolCallId: approval.toolCallId,
-              toolName: approval.toolName,
-              input: approval.input,
-            },
-            this.tools as ToolSet,
-            prompt.messages as unknown as LanguageModelV4Prompt,
-            effectiveToolsContext,
-            0,
-            sandbox,
-          );
-          toolResultContent.push(result.modelResult);
-          approvedRawResults.push({
-            toolCallId: approval.toolCallId,
-            toolName: approval.toolName,
-            input: approval.input,
-            output: result.rawOutput,
-          });
-        }
+        },
+      });
+      for (const result of approvedResults) {
+        if (result == null) continue;
+        toolResultContent.push(result.modelResult);
+        if (result.rawResult != null) approvedRawResults.push(result.rawResult);
       }
 
       // Create denial results for denied tools
@@ -2183,7 +2230,7 @@ export class WorkflowAgent<
     const modelPrompt = await convertToLanguageModelPrompt({
       prompt,
       supportedUrls: {},
-      download,
+      download: workflowDownload,
     });
 
     // Merge generation settings: constructor defaults < prepareCall < stream options
@@ -2368,7 +2415,7 @@ export class WorkflowAgent<
             messages,
             resolvedContext,
             effectiveAbortSignal,
-            download,
+            workflowDownload,
             stepSandbox,
           );
         result =
@@ -2546,6 +2593,7 @@ export class WorkflowAgent<
       repairToolCall: (options.repairToolCall ??
         options.experimental_repairToolCall ??
         this.repairToolCall) as ToolCallRepairFunction<ToolSet> | undefined,
+      download,
       responseFormat: await (options.output ?? this.output)?.responseFormat,
       experimental_transform: options.experimental_transform as
         | StreamTextTransform<ToolSet>
@@ -2705,19 +2753,20 @@ export class WorkflowAgent<
             providerApprovalRequests.length > 0
           ) {
             // Execute any executable tools that were also called in this step
-            const executableResults = await Promise.all(
-              executableToolCalls.map(
-                (toolCall): Promise<WorkflowToolExecutionResult> =>
-                  executeToolWithCallbacks(
-                    toolCall,
-                    stepTools,
-                    iterMessages,
-                    toolsContext,
-                    currentStepNumber,
-                    toolExecutionSandbox,
-                  ),
-              ),
-            );
+            const executableResults = await mapWithConcurrency({
+              items: executableToolCalls,
+              concurrency: toolCallConcurrency,
+              abortSignal: effectiveAbortSignal,
+              execute: toolCall =>
+                executeToolWithCallbacks(
+                  toolCall,
+                  stepTools,
+                  iterMessages,
+                  toolsContext,
+                  currentStepNumber,
+                  toolExecutionSandbox,
+                ),
+            });
 
             // Collect provider tool results
             const providerResultEntries = await Promise.all(
@@ -2735,7 +2784,7 @@ export class WorkflowAgent<
                     toolCall,
                     capturedProviderToolResults,
                     stepTools,
-                    download,
+                    workflowDownload,
                   ),
                 })),
             );
@@ -2920,19 +2969,20 @@ export class WorkflowAgent<
           }
 
           // Execute client tools (all have execute functions at this point)
-          const clientToolResults = await Promise.all(
-            nonProviderToolCalls.map(
-              (toolCall): Promise<WorkflowToolExecutionResult> =>
-                executeToolWithCallbacks(
-                  toolCall,
-                  stepTools,
-                  iterMessages,
-                  toolsContext,
-                  currentStepNumber,
-                  toolExecutionSandbox,
-                ),
-            ),
-          );
+          const clientToolResults = await mapWithConcurrency({
+            items: nonProviderToolCalls,
+            concurrency: toolCallConcurrency,
+            abortSignal: effectiveAbortSignal,
+            execute: toolCall =>
+              executeToolWithCallbacks(
+                toolCall,
+                stepTools,
+                iterMessages,
+                toolsContext,
+                currentStepNumber,
+                toolExecutionSandbox,
+              ),
+          });
 
           // For provider-executed tools, use the results from the stream
           const providerToolResultEntries = await Promise.all(
@@ -2942,7 +2992,7 @@ export class WorkflowAgent<
                 toolCall,
                 capturedProviderToolResults,
                 stepTools,
-                download,
+                workflowDownload,
               ),
             })),
           );