ai 7.0.139 → 7.0.140

package/docs/03-agents/07-workflow-agent.mdx

@@ -881,3 +881,23 @@ Other options carry over with the same names: `prepareStep`, `onStart`, `onStepS
 - [WorkflowChatTransport API Reference](/docs/reference/ai-sdk-workflow/workflow-chat-transport) for stream reconnection options
 - [Building Agents](/docs/agents/building-agents) for the in-memory `ToolLoopAgent` alternative
 - [Loop Control](/docs/agents/loop-control) for advanced stop conditions
+
+## Tool execution concurrency
+
+Set `toolCallConcurrency` to limit how many local tool calls execute concurrently
+within a step. Use `1` when calls must execute sequentially in model order:
+
+```ts
+const agent = new WorkflowAgent({
+  model,
+  tools,
+  toolCallConcurrency: 1,
+});
+```
+
+The limit applies to both `generate()` and `stream()`, including approved tool
+calls resumed from message history. It must be a positive integer. By default,
+all local calls execute concurrently; provider-executed tools are unaffected.
+You can also return the setting from `prepareCall` or pass it to `generate()` or
+`stream()`. Explicit call options take precedence over `prepareCall`, which takes
+precedence over the constructor default.

package/docs/03-ai-sdk-core/15-tools-and-tool-calling.mdx

@@ -511,6 +511,35 @@ const result = await generateText({
 });
 ```
 
+### Tool call execution concurrency
+
+By default, when a model generates multiple tool calls in one step,
+`generateText`, `streamText`, and `ToolLoopAgent` execute those calls
+concurrently. Set `toolCallConcurrency` to a positive integer to limit how many
+SDK-executed tool calls run at once.
+
+Use `toolCallConcurrency: 1` when later calls need to observe side effects from
+earlier calls. The SDK starts calls sequentially in the order the model
+generated them:
+
+```ts highlight="5"
+const result = await generateText({
+  model: __MODEL__,
+  tools,
+  prompt: 'Update the file, then read it.',
+  toolCallConcurrency: 1,
+});
+```
+
+This option controls execution of tool calls that the SDK runs locally. It does
+not change how many tool calls the model may generate, and it does not schedule
+provider-executed tools or client-side tools. Provider options such as
+`parallelToolCalls` control model generation instead.
+
+When the operation is aborted, active tools receive the abort signal and queued
+tool calls are not started. A streaming tool holds its concurrency slot until
+its final output or error.
+
 ### Tool execution lifecycle callbacks
 
 You can use `onToolExecutionStart` and `onToolExecutionEnd` to observe tool execution.

package/docs/07-reference/01-ai-sdk-core/01-generate-text.mdx

@@ -571,6 +571,13 @@ To see `generateText` in action, check out [these examples](#examples).
       description:
         'Controls the order in which tools are sent to the provider. The list can be partial. Tools not listed in `toolOrder` are sent after the listed tools, sorted alphabetically. Tool names are restricted to the string keys of the tool set.',
     },
+    {
+      name: 'toolCallConcurrency',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Maximum number of tool calls that the SDK executes concurrently within a step. Set to `1` to execute calls sequentially in model-generated order. Must be a positive integer. By default, all tool calls execute concurrently.',
+    },
     {
       name: 'toolApproval',
       type: 'ToolApprovalConfiguration<TOOLS, RUNTIME_CONTEXT>',

package/docs/07-reference/01-ai-sdk-core/02-stream-text.mdx

@@ -622,6 +622,13 @@ To see `streamText` in action, check out [these examples](#examples).
       description:
         'Controls the order in which tools are sent to the provider. The list can be partial. Tools not listed in `toolOrder` are sent after the listed tools, sorted alphabetically. Tool names are restricted to the string keys of the tool set.',
     },
+    {
+      name: 'toolCallConcurrency',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Maximum number of tool calls that the SDK executes concurrently within a step. Set to `1` to execute calls sequentially in model-generated order. Must be a positive integer. By default, all tool calls execute concurrently.',
+    },
     {
       name: 'toolApproval',
       type: 'ToolApprovalConfiguration<TOOLS, RUNTIME_CONTEXT>',

package/docs/07-reference/01-ai-sdk-core/16-tool-loop-agent.mdx

@@ -104,6 +104,13 @@ To see `ToolLoopAgent` in action, check out [these examples](#examples).
       description:
         'Controls the order in which tools are sent to the provider. The list can be partial. Tools not listed in `toolOrder` are sent after the listed tools, sorted alphabetically. Tool names are restricted to the string keys of the tool set.',
     },
+    {
+      name: 'toolCallConcurrency',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Maximum number of tool calls that the SDK executes concurrently within an agent step. Set to `1` to execute calls sequentially in model-generated order. Must be a positive integer. By default, all tool calls execute concurrently.',
+    },
     {
       name: 'toolApproval',
       type: 'ToolApprovalConfiguration<TOOLS, RUNTIME_CONTEXT>',

package/docs/07-reference/04-ai-sdk-workflow/01-workflow-agent.mdx

@@ -101,6 +101,13 @@ To see `WorkflowAgent` in action, check out [these examples](#examples).
       description:
         'Default stop condition for the agent loop. When omitted, generate defaults to 20 steps, while stream has no maximum step count. Use `isStepCount()` to bound execution. Per-call values override this default.',
     },
+    {
+      name: 'toolCallConcurrency',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Maximum number of local tool calls executing concurrently within a step, including approved calls. Must be a positive integer. Set to 1 for sequential execution in model order. Defaults to unlimited concurrency. Can be changed by prepareCall; explicit generate/stream call options take precedence. Provider-executed tools are unaffected.',
+    },
     {
       name: 'activeTools',
       type: 'ActiveTools<TTools>',
@@ -569,6 +576,13 @@ const result = await agent.stream({
       isOptional: true,
       description: "Override the tool choice strategy for this call. Default: 'auto'.",
     },
+    {
+      name: 'toolCallConcurrency',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Override the local tool call concurrency limit for this call. Must be a positive integer. Set to 1 for sequential execution in model order, including approved calls. Takes precedence over the constructor and prepareCall.',
+    },
     {
       name: 'activeTools',
       type: 'ActiveTools<TTools>',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "7.0.139",
+  "version": "7.0.140",
   "type": "module",
   "description": "AI SDK by Vercel - build apps like ChatGPT, Claude, Gemini, and more with a single interface for any model using the Vercel AI Gateway or go direct to OpenAI, Anthropic, Google, or any other model provider.",
   "license": "Apache-2.0",
@@ -42,7 +42,7 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/gateway": "4.0.112",
+    "@ai-sdk/gateway": "4.0.113",
     "@ai-sdk/provider": "4.0.27",
     "@ai-sdk/provider-utils": "5.0.59"
   },

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

@@ -121,6 +121,14 @@ export type ToolLoopAgentSettings<
      */
     toolOrder?: ToolOrder<NoInfer<TOOLS>>;
 
+    /**
+     * Maximum number of tool calls that may execute concurrently within a step.
+     *
+     * Set to `1` to execute tool calls sequentially in the order they were
+     * generated. By default, all tool calls execute concurrently.
+     */
+    toolCallConcurrency?: number;
+
     /**
      * Optional specification for generating structured outputs.
      */
@@ -370,6 +378,7 @@ export type ToolLoopAgentSettings<
           | 'experimental_telemetry'
           | 'activeTools'
           | 'toolOrder'
+          | 'toolCallConcurrency'
           | 'toolApproval'
           | 'experimental_toolCallers'
           | 'experimental_toolApprovalSecret'
@@ -412,6 +421,7 @@ export type ToolLoopAgentSettings<
         | 'experimental_telemetry'
         | 'activeTools'
         | 'toolOrder'
+        | 'toolCallConcurrency'
         | 'toolApproval'
         | 'experimental_toolCallers'
         | 'experimental_toolApprovalSecret'

package/src/generate-text/collect-tool-approvals.ts

@@ -50,12 +50,15 @@ export function collectToolApprovals<TOOLS extends ToolSet>({
     string,
     TypedToolCall<TOOLS>
   > = Object.create(null);
+  const toolCallOrder: Record<string, number> = Object.create(null);
+  let nextToolCallIndex = 0;
   for (const message of messages) {
     if (message.role === 'assistant' && typeof message.content !== 'string') {
       const content = message.content;
       for (const part of content) {
         if (part.type === 'tool-call') {
           toolCallsByToolCallId[part.toolCallId] = part as TypedToolCall<TOOLS>;
+          toolCallOrder[part.toolCallId] = nextToolCallIndex++;
         }
       }
     }
@@ -130,5 +133,13 @@ export function collectToolApprovals<TOOLS extends ToolSet>({
     }
   }
 
+  // Approval responses can arrive in a different order than the model's calls.
+  // Restore model order before either generation API schedules their execution.
+  approvedToolApprovals.sort(
+    (a, b) =>
+      toolCallOrder[a.toolCall.toolCallId] -
+      toolCallOrder[b.toolCall.toolCallId],
+  );
+
   return { approvedToolApprovals, deniedToolApprovals };
 }

package/src/generate-text/execute-tools-from-stream.ts

@@ -26,6 +26,7 @@ import type {
   OnToolExecutionStartCallback,
 } from './tool-execution-events';
 import type { StaticToolOutputDenied } from './tool-output-denied';
+import { mapWithConcurrency } from './tool-call-concurrency';
 
 export type ToolExecutionEndStreamPart = {
   type: 'tool-execution-end';
@@ -63,6 +64,7 @@ export function executeToolsFromStream<
   onToolExecutionEnd,
   executeToolInTelemetryContext,
   runInTracingChannelSpan,
+  toolCallConcurrency,
 }: {
   stream: ReadableStream<ExecuteToolsInputStreamPart<TOOLS>>;
   tools: TOOLS | undefined;
@@ -82,6 +84,7 @@ export function executeToolsFromStream<
   runInTracingChannelSpan?: NonNullable<
     TelemetryDispatcher['runInTracingChannelSpan']
   >;
+  toolCallConcurrency?: number;
 }): ReadableStream<ExecuteToolsStreamPart<TOOLS>> {
   const toolCallsToExecute: Array<TypedToolCall<TOOLS>> = [];
 
@@ -226,8 +229,11 @@ export function executeToolsFromStream<
               return;
             }
 
-            await Promise.all(
-              toolCallsToExecute.map(async toolCall => {
+            await mapWithConcurrency({
+              items: toolCallsToExecute,
+              concurrency: toolCallConcurrency,
+              abortSignal,
+              execute: async toolCall => {
                 try {
                   // Note: we don't await the tool execution here (by leaving out 'await' on recordSpan),
                   // because we want to process the next chunk as soon as possible.
@@ -263,8 +269,8 @@ export function executeToolsFromStream<
                     error,
                   });
                 }
-              }),
-            );
+              },
+            });
           }
         }
       },

package/src/generate-text/generate-text.ts

@@ -124,6 +124,10 @@ import type { ToolOutput } from './tool-output';
 import type { ToolsContextParameter } from './tools-context-parameter';
 import { maybeSignApproval } from './tool-approval-signature';
 import { validateApprovedToolApprovals } from './validate-tool-approvals';
+import {
+  mapWithConcurrency,
+  prepareToolCallConcurrency,
+} from './tool-call-concurrency';
 
 const originalGenerateId = createIdGenerator({
   prefix: 'aitxt',
@@ -170,6 +174,7 @@ export type GenerateTextInclude = {
  * @param tools - Tools that are accessible to and can be called by the model. The model needs to support calling tools.
  * @param toolChoice - The tool choice strategy. Default: 'auto'.
  * @param toolOrder - Controls the order in which tools are sent to the provider. Tools not listed are appended alphabetically.
+ * @param toolCallConcurrency - Maximum number of tool calls that may execute concurrently within a step. Set to 1 for sequential execution. Default: unlimited.
  *
  * @param system - A system message that will be part of the prompt.
  * @param prompt - A simple text prompt. You can either use `prompt` or `messages` but not both.
@@ -255,6 +260,7 @@ export async function generateText<
   providerOptions,
   activeTools,
   toolOrder,
+  toolCallConcurrency,
   prepareStep,
   experimental_repairToolCall,
   repairToolCall = experimental_repairToolCall,
@@ -353,6 +359,14 @@ export async function generateText<
      */
     toolOrder?: ToolOrder<NoInfer<TOOLS>>;
 
+    /**
+     * Maximum number of tool calls that may execute concurrently within a step.
+     *
+     * Set to `1` to execute tool calls sequentially in the order they were
+     * generated. By default, all tool calls execute concurrently.
+     */
+    toolCallConcurrency?: number;
+
     /**
      * Optional specification for parsing structured outputs from the LLM response.
      */
@@ -571,6 +585,8 @@ export async function generateText<
     responseBody: include?.responseBody ?? false,
   };
 
+  const resolvedToolCallConcurrency =
+    prepareToolCallConcurrency(toolCallConcurrency);
   const model = resolveLanguageModel(modelArg);
   const resolvedToolCallers = resolveToolCallerConfiguration({
     tools,
@@ -770,6 +786,7 @@ export async function generateText<
             }),
           executeToolInTelemetryContext: telemetryDispatcher.executeTool,
           runInTracingChannelSpan,
+          toolCallConcurrency: resolvedToolCallConcurrency,
         });
 
         const toolContent: Array<any> = [];
@@ -1371,6 +1388,7 @@ export async function generateText<
                   executeToolInTelemetryContext:
                     telemetryDispatcher.executeTool,
                   runInTracingChannelSpan,
+                  toolCallConcurrency: resolvedToolCallConcurrency,
                 });
 
                 for (const result of toolExecutionResults) {
@@ -1643,6 +1661,7 @@ async function executeTools<TOOLS extends ToolSet>({
   onToolExecutionEnd,
   executeToolInTelemetryContext,
   runInTracingChannelSpan,
+  toolCallConcurrency,
 }: {
   toolCalls: Array<TypedToolCall<TOOLS>>;
   tools: TOOLS;
@@ -1658,31 +1677,33 @@ async function executeTools<TOOLS extends ToolSet>({
   runInTracingChannelSpan?: NonNullable<
     TelemetryDispatcher['runInTracingChannelSpan']
   >;
+  toolCallConcurrency: number | undefined;
 }): Promise<
   Array<{
     output: ToolOutput<TOOLS>;
     toolExecutionMs: number;
   }>
 > {
-  const toolResults = await Promise.all(
-    toolCalls.map(
-      async toolCall =>
-        await executeToolCall({
-          toolCall,
-          tools,
-          callId,
-          messages,
-          abortSignal,
-          timeout,
-          experimental_sandbox: sandbox,
-          toolsContext,
-          onToolExecutionStart,
-          onToolExecutionEnd,
-          executeToolInTelemetryContext,
-          runInTracingChannelSpan,
-        }),
-    ),
-  );
+  const toolResults = await mapWithConcurrency({
+    items: toolCalls,
+    concurrency: toolCallConcurrency,
+    abortSignal,
+    execute: async toolCall =>
+      await executeToolCall({
+        toolCall,
+        tools,
+        callId,
+        messages,
+        abortSignal,
+        timeout,
+        experimental_sandbox: sandbox,
+        toolsContext,
+        onToolExecutionStart,
+        onToolExecutionEnd,
+        executeToolInTelemetryContext,
+        runInTracingChannelSpan,
+      }),
+  });
 
   return toolResults.filter(
     (result): result is NonNullable<typeof result> => result != null,

package/src/generate-text/stream-text.ts

@@ -166,6 +166,10 @@ import type { ToolOutput } from './tool-output';
 import type { StaticToolOutputDenied } from './tool-output-denied';
 import type { ToolsContextParameter } from './tools-context-parameter';
 import { validateApprovedToolApprovals } from './validate-tool-approvals';
+import {
+  mapWithConcurrency,
+  prepareToolCallConcurrency,
+} from './tool-call-concurrency';
 
 const originalGenerateId = createIdGenerator({
   prefix: 'aitxt',
@@ -288,6 +292,7 @@ export type StreamTextOnAbortCallback<
  * @param model - The language model to use.
  * @param tools - Tools that are accessible to and can be called by the model. The model needs to support calling tools.
  * @param toolOrder - Controls the order in which tools are sent to the provider. Tools not listed are appended alphabetically.
+ * @param toolCallConcurrency - Maximum number of tool calls that may execute concurrently within a step. Set to 1 for sequential execution. Default: unlimited.
  *
  * @param system - A system message that will be part of the prompt.
  * @param prompt - A simple text prompt. You can either use `prompt` or `messages` but not both.
@@ -377,6 +382,7 @@ export function streamText<
   providerOptions,
   activeTools,
   toolOrder,
+  toolCallConcurrency,
   experimental_repairToolCall,
   repairToolCall = experimental_repairToolCall,
   experimental_refineToolInput: refineToolInput,
@@ -479,6 +485,14 @@ export function streamText<
      */
     toolOrder?: ToolOrder<NoInfer<TOOLS>>;
 
+    /**
+     * Maximum number of tool calls that may execute concurrently within a step.
+     *
+     * Set to `1` to execute tool calls sequentially in the order they were
+     * generated. By default, all tool calls execute concurrently.
+     */
+    toolCallConcurrency?: number;
+
     /**
      * Optional specification for parsing structured outputs from the LLM response.
      */
@@ -769,6 +783,8 @@ export function streamText<
       generateCallId?: IdGenerator;
     };
   }): StreamTextResult<TOOLS, RUNTIME_CONTEXT, OUTPUT> {
+  const resolvedToolCallConcurrency =
+    prepareToolCallConcurrency(toolCallConcurrency);
   const totalTimeoutMs = getTotalTimeoutMs(timeout);
   const stepTimeoutMs = getStepTimeoutMs(timeout);
   const firstChunkTimeoutMs = getFirstChunkTimeoutMs(timeout);
@@ -828,6 +844,7 @@ export function streamText<
     transforms: asArray(transform),
     activeTools,
     toolOrder,
+    toolCallConcurrency: resolvedToolCallConcurrency,
     repairToolCall,
     refineToolInput,
     stopConditions: asArray(stopWhen),
@@ -1212,6 +1229,7 @@ class DefaultStreamTextResult<
     transforms,
     activeTools,
     toolOrder,
+    toolCallConcurrency,
     repairToolCall,
     refineToolInput,
     stopConditions,
@@ -1268,6 +1286,7 @@ class DefaultStreamTextResult<
     transforms: Array<StreamTextTransform<TOOLS>>;
     activeTools: ActiveTools<TOOLS>;
     toolOrder: ToolOrder<TOOLS>;
+    toolCallConcurrency: number | undefined;
     repairToolCall: ToolCallRepairFunction<TOOLS> | undefined;
     refineToolInput: ToolInputRefinement<TOOLS> | undefined;
     stopConditions: Array<
@@ -2075,8 +2094,11 @@ class DefaultStreamTextResult<
 
           const toolOutputs: Array<ToolOutput<TOOLS>> = [];
 
-          await Promise.all(
-            localApprovedToolApprovals.map(async toolApproval => {
+          await mapWithConcurrency({
+            items: localApprovedToolApprovals,
+            concurrency: toolCallConcurrency,
+            abortSignal,
+            execute: async toolApproval => {
               const result = await executeToolCall({
                 toolCall: toolApproval.toolCall,
                 tools,
@@ -2105,8 +2127,8 @@ class DefaultStreamTextResult<
                 toolExecutionStepStreamController?.enqueue(result.output);
                 toolOutputs.push(result.output);
               }
-            }),
-          );
+            },
+          });
 
           // Local tool results (approved + denied) are sent as tool results:
           if (
@@ -2709,6 +2731,7 @@ class DefaultStreamTextResult<
 
             executeToolInTelemetryContext: telemetryDispatcher.executeTool,
             runInTracingChannelSpan: runInTracingChannelSpanInStep,
+            toolCallConcurrency,
           });
 
           // Conditionally include request.body based on include settings.

package/src/generate-text/tool-call-concurrency.ts

@@ -0,0 +1,80 @@
+import { InvalidArgumentError } from '../error/invalid-argument-error';
+
+/**
+ * Validates the maximum number of tool calls that may execute concurrently.
+ */
+export function prepareToolCallConcurrency(
+  toolCallConcurrency: number | undefined,
+): number | undefined {
+  if (toolCallConcurrency == null) {
+    return undefined;
+  }
+
+  if (!Number.isInteger(toolCallConcurrency)) {
+    throw new InvalidArgumentError({
+      parameter: 'toolCallConcurrency',
+      value: toolCallConcurrency,
+      message: 'toolCallConcurrency must be an integer',
+    });
+  }
+
+  if (toolCallConcurrency < 1) {
+    throw new InvalidArgumentError({
+      parameter: 'toolCallConcurrency',
+      value: toolCallConcurrency,
+      message: 'toolCallConcurrency must be >= 1',
+    });
+  }
+
+  return toolCallConcurrency;
+}
+
+/**
+ * Maps items with an optional concurrency limit while preserving result order.
+ *
+ * Workers claim items in input order. When the signal is aborted or an
+ * execution rejects, no additional queued items are started.
+ */
+export async function mapWithConcurrency<INPUT, OUTPUT>({
+  items,
+  concurrency,
+  abortSignal,
+  execute,
+}: {
+  items: Array<INPUT>;
+  concurrency: number | undefined;
+  abortSignal?: AbortSignal;
+  execute: (item: INPUT, index: number) => Promise<OUTPUT>;
+}): Promise<Array<OUTPUT>> {
+  if (concurrency == null || concurrency >= items.length) {
+    return Promise.all(items.map(execute));
+  }
+
+  const results = new Array<OUTPUT>(items.length);
+  let nextIndex = 0;
+  let stopped = false;
+
+  const worker = async () => {
+    while (!stopped) {
+      abortSignal?.throwIfAborted();
+
+      const index = nextIndex++;
+      if (index >= items.length) {
+        return;
+      }
+
+      try {
+        results[index] = await execute(items[index], index);
+      } catch (error) {
+        stopped = true;
+        throw error;
+      }
+    }
+  };
+
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, items.length) }, worker),
+  );
+
+  return results;
+}