From 7b1599058b497009bfd8f57926a44250272870e4 Mon Sep 17 00:00:00 2001 From: Mario Zechner Date: Mon, 20 Apr 2026 22:35:43 +0200 Subject: [PATCH] docs(agent): clarify parallel tool ordering closes #3468 --- packages/agent/CHANGELOG.md | 4 ++++ packages/agent/README.md | 4 +++- packages/agent/src/types.ts | 5 +++-- 3 files changed, 10 insertions(+), 3 deletions(-) diff --git a/packages/agent/CHANGELOG.md b/packages/agent/CHANGELOG.md index 183eb9e4..c15c716c 100644 --- a/packages/agent/CHANGELOG.md +++ b/packages/agent/CHANGELOG.md @@ -2,6 +2,10 @@ ## [Unreleased] +### Changed + +- Clarified parallel tool execution ordering docs to specify that final tool lifecycle and tool-result artifacts are emitted in tool completion order. + ## [0.67.68] - 2026-04-17 ## [0.67.67] - 2026-04-17 diff --git a/packages/agent/README.md b/packages/agent/README.md index 1e2847e7..21f50a73 100644 --- a/packages/agent/README.md +++ b/packages/agent/README.md @@ -101,9 +101,11 @@ prompt("Read config.json") Tool execution mode is configurable: -- `parallel` (default): preflight tool calls sequentially, execute allowed tools concurrently, emit final `tool_execution_end` and `toolResult` messages in assistant source order +- `parallel` (default): preflight tool calls sequentially, execute allowed tools concurrently, and emit `tool_execution_end`, toolResult messages, and `turn_end.toolResults` in the order tool calls finish - `sequential`: execute tool calls one by one, matching the historical behavior +In parallel mode, final tool lifecycle and tool-result artifacts follow tool completion order, not assistant source order. A later tool call may therefore finish before an earlier one, including when it is blocked during preflight. + The mode can be set globally via `toolExecution` in the agent config, or per-tool via `executionMode` on `AgentTool`. If any tool call in a batch targets a tool with `executionMode: "sequential"`, the entire batch executes sequentially regardless of the global setting. The `beforeToolCall` hook runs after `tool_execution_start` and validated argument parsing. It can block execution. The `afterToolCall` hook runs after tool execution finishes and before `tool_execution_end` and final tool result message events are emitted. diff --git a/packages/agent/src/types.ts b/packages/agent/src/types.ts index 599e3ae6..511f15ae 100644 --- a/packages/agent/src/types.ts +++ b/packages/agent/src/types.ts @@ -30,7 +30,7 @@ export type StreamFn = ( * * - "sequential": each tool call is prepared, executed, and finalized before the next one starts. * - "parallel": tool calls are prepared sequentially, then allowed tools execute concurrently. - * Final tool results are still emitted in assistant source order. + * Final tool lifecycle and tool-result artifacts are emitted in tool completion order. */ export type ToolExecutionMode = "sequential" | "parallel"; @@ -185,7 +185,8 @@ export interface AgentLoopConfig extends SimpleStreamOptions { /** * Tool execution mode. * - "sequential": execute tool calls one by one - * - "parallel": preflight tool calls sequentially, then execute allowed tools concurrently + * - "parallel": preflight tool calls sequentially, then execute allowed tools concurrently; + * final tool lifecycle and tool-result artifacts are emitted in tool completion order * * Default: "parallel" */