[KongchangAI]
· 3 min read· 1,539 words

@ai-sdk/workflow 2.0.105 Update: Tool Approval and Timeout Control Land

@ai-sdk/workflow 2.0.105 Update: Tool Approval and Timeout Control Land

@ai-sdk/workflow 2.0.105 adds approval, segmented timeouts, and streaming behavior, aligning with ToolLoopAgent.

@ai-sdk/workflow@2.0.105 is a patch release with multiple behavioral fixes and new config. The core addition is toolApproval, settable in the constructor or per call and taking precedence over needsApproval; approval runs in the workflow context, and rejections return execution-denied without pausing the workflow. timeout becomes a segmented { totalMs, stepMs, firstChunkMs, chunkMs } object and can terminate a model step even if the provider ignores abort. Streaming and abort behavior also align with ToolLoopAgent, and experimental_refineToolInput is added.

The workflow module in the AI SDK ecosystem has always played the role of "stringing together multi-step agent orchestration," but it has often been compared with ToolLoopAgent on tool approval, timeout management, and streaming behavior, with several behavioral inconsistencies. @ai-sdk/workflow@2.0.105 is an update released under a patch-level version number that nonetheless packs in quite a few new capabilities: it fills in details aligned with ToolLoopAgent and also introduces configuration options that were previously missing, such as toolApproval, toolOrder, and the timeout object.

rss source: @ai-sdk/workflow@2.0.105

Tool governance: approval and ordering become first-class configuration

toolApproval takes approval out of the model step

The most notable addition in this update is the introduction of toolApproval. WorkflowAgent can now accept approval configuration in its constructor, or on each generate() or stream() call, and this configuration takes precedence over the tool's own needsApproval setting. One easily overlooked but crucial design point: the approval function runs in the workflow context, outside the persisted model step, which means approval logic does not contaminate the replayable boundary of model calls.

For callers, the two approval outcomes are handled differently: an approved call executes directly within the same step; a rejected call receives an execution-denied tool result but does not pause the entire workflow. This contrasts with the approach in many orchestration frameworks where "approval failure means interruption," and is better suited to scenarios that need to run for a long time and cannot fail entirely because of a single rejection.

toolOrder controls the order in which tools are exposed

toolOrder can be set in the constructor, on a single generate()/stream() call, and in prepareCall and prepareStep. Listed tools are sent first in the given order, and unlisted tools follow in alphabetical order. For teams sensitive to prompt engineering, tool order affects the model's selection tendencies, and this configuration turns what was previously implicit ordering into something that can be explicitly declared.

ToolLoopAgent is the agent abstraction in the AI SDK for multi-step tool calling; it handles loop scheduling between the model and tools until the model no longer requests tools or the step limit is reached. Compared with WorkflowAgent, ToolLoopAgent leans more toward automatic looping within a single session, while WorkflowAgent targets persistable, orchestrated multi-step workflows. The two share underlying mechanisms such as model calls and tool execution, but historically differed in boundary behaviors such as approval, timeout, and streaming abort. This update aligns several WorkflowAgent behaviors with ToolLoopAgent, with the goal of sparing developers from having to relearn a set of semantics when migrating between the two and reducing hidden bugs caused by behavioral divergence.

needsApproval is a tool-level approval declaration, usually written in the tool definition, indicating that the tool requires human or external logic confirmation before being called. A tool's own needsApproval is static and global; toolApproval, by contrast, is dynamic configuration at the call level, which can be passed in the constructor or on each generate()/stream() call and takes higher precedence. This layered design allows teams to temporarily tighten or relax approval policy for specific calls without modifying tool definitions.

Timeout system: from a single number to segmented control

Previously generate() and stream() only accepted a single number as timeout; now they support the object form timeout: { totalMs, stepMs, firstChunkMs, chunkMs }. stepMs limits a single model call, while in stream() firstChunkMs and chunkMs constrain the first chunk output and the inter-chunk wait time, respectively. Invalid timeout values are rejected with InvalidArgumentError.

One implementation-level improvement is worth mentioning: when a provider's streaming response ignores the abort signal, the timeout can now also terminate that model step. This is a direct response to the common pain point of "timeouts that amount to nothing"—previously, cancellation semantics for streaming interfaces depended on downstream cooperation; now the upstream can unilaterally provide a fallback.

AbortSignal is the Web standard cancellation primitive, and the AI SDK uses it to propagate abort requests. When the caller triggers an abort, the signal notifies all listeners to stop working. But whether a streaming HTTP response can actually be cancelled depends on whether the provider implementation listens to that signal; some providers stop checking abort after the stream is established, causing cancellation requests to be ignored. This update adds an upstream fallback on the timeout path: even if the provider ignores the abort signal, the timeout timer still actively terminates that model step, preventing streaming calls from hanging indefinitely. This changes the previously fragile semantics in which "timeout depends on downstream cooperation."

Streaming and abort behavior: aligning with ToolLoopAgent

Several fixes in this patch address behavioral consistency between WorkflowAgent and ToolLoopAgent, and a clear convergence path can be seen.

Correction of abort semantics

When WorkflowAgent is interrupted during a model step by an abort carrying a custom abort reason, it now calls onAbort instead of onError; generate() still rejects with that reason, while stream() resolves the completed steps just as it does for an abort without a reason. This distinction lets callers clearly tell "user-initiated cancellation" apart from "execution error," without having to infer it from error message strings.

onAbort and onError are two lifecycle callbacks of WorkflowAgent, corresponding to the two types of termination reasons: "active cancellation" and "execution failure." Aborts can carry a custom reason (for example, the user clicking cancel or an upstream service closing), and previously such aborts were classified under onError, forcing callers to determine the real cause from error message strings. After the fix, aborts with a custom reason go through onAbort, generate() rejects with that reason, and stream() resolves the completed steps, consistent with the handling of aborts without a reason. This distinction makes cancellation and errors distinguishable at the type level, making it easier for upper layers to apply different retry or cleanup strategies.

Result value of async generator tools

WorkflowAgent now uses the last value yielded by an async generator tool as the tool result, consistent with ToolLoopAgent; if the generator throws after yielding, a tool error is produced. Such semantic details previously tended to cause behavioral divergence between the two Agents, and unifying them now lowers migration costs.

Handling of unknown tools and invalid input

When the model calls an unknown tool or passes input that does not conform to the schema, stream() now retains that tool call, marks it as invalid, and produces a tool-error part in the step, consistent with the behavior of generate() and ToolLoopAgent; the model still receives the error as the tool result, giving it a chance to self-correct.

Other alignment items

The return value semantics of prepareStep have also been aligned: the returned instructions (or the deprecated system) replace the current step's instructions and propagate forward, providerOptions are merged with agent options, and headers override the call's own headers. Steps in the WorkflowAgent.stream() result now carry the provider name and model ID of the model that was called. stream() also triggers the onInputAvailable hook when a provider emits a tool call without first streaming the tool input. In addition, WorkflowAgent.generate() and stream() now log warnings for each model call through the AI SDK's warning logger, with output globally controlled by AI_SDK_LOG_WARNINGS; generate() also prints a warning when it stops at the default step limit—previously this kind of "silent truncation" was easily mistaken for normal completion.

New capability experimental_refineToolInput

WorkflowAgent supports experimental_refineToolInput in the constructor and on individual calls; the refined tool input is used for tool execution, step results, callbacks, and the next model call, the same behavior as in ToolLoopAgent. The experimental prefix in the name signals that this is still an experimental interface, and adoption in production should come with an expectation of version changes.

Upgrade recommendations

This version number is patch-level, but the changes span behavioral fixes and new configuration options, so the actual impact goes beyond a patch. Code that relies on onError to handle aborts, or on the old single-number timeout, needs to be checked for impact; meanwhile, teams that want human intervention via toolApproval, or want to govern streaming stability with segmented timeouts, can adopt this version. It is recommended to first verify in a test environment the scope of toolApproval and the impact of toolOrder on the model's tool selection, then move to production.

One-line Summary

@ai-sdk/workflow 2.0.105 fills in approval, segmented timeouts, and streaming behavior, aligning with ToolLoopAgent.

Paragraph Summary

Although @ai-sdk/workflow@2.0.105 is a patch version, it brings multiple behavioral fixes and new configuration. The core addition is toolApproval, which can be passed in the constructor or on individual calls, takes precedence over the tool's own needsApproval, executes approval in the workflow context, and on rejection returns execution-denied without pausing the entire workflow. timeout has been upgraded from a single number to a segmented object { totalMs, stepMs, firstChunkMs, chunkMs }, and can still terminate the model step even when the provider ignores the abort signal. Streaming and abort behavior are aligned with ToolLoopAgent: aborts with custom reasons call onAbort instead of onError, and stream() resolves the completed steps; async generator tools take the last yielded value; unknown tools or invalid input are marked invalid and produce tool-error; prepareStep return value semantics, provider info recording, and warning logging are also unified. Additionally, experimental_refineToolInput is new. Upgrading requires checking dependencies on onError and single-number timeout.

#@ai-sdk/workflow#toolApproval#ToolLoopAgent#AI SDK#timeout configuration
Share:

Related articles