🆕 WorkflowAgent (@ai-sdk/workflow)

[gr2m]

Create a new @ai-sdk/workflow package that exports WorkflowAgent, which will be the successor of DurableAgent

ToolLoopAgent parity plan

The underlying streamText in core already supports all 6 callback types. The gap is that WorkflowAgent doesn't accept or pass them through. However, WorkflowAgent doesn't call streamText directly — it uses streamTextIterator → doStreamStep → streamModelCall. So the callbacks need to be threaded through that chain.

Phase 1: Wire missing callbacks through WorkflowAgent API ✅ (#14036)

1. Add the 4 missing callback types to WorkflowAgentOptions and WorkflowAgentStreamOptions interfaces
2. Add mergeCallbacks utility (extracted from ToolLoopAgent pattern)
3. Pass callbacks through streamTextIterator to doStreamStep (which uses streamModelCall)
4. Emit callbacks at the right points in the iterator loop

Unblocked 14 of 16 GAP tests. 2 remain as it.fails() to track event shape parity (see below).

Remaining work from Phase 1: Align callback event shapes with ToolLoopAgent. WorkflowAgent's callback events are simpler than ToolLoopAgent's. ToolLoopAgent events (defined in core-events.ts) include callId, provider, modelId, stepNumber, messages, abortSignal, functionId, metadata, experimental_context, typed toolCall with TypedToolCall<TOOLS>, and durationMs on tool call finish. WorkflowAgent events currently only provide a subset (e.g., onToolCallStart only has toolCall with a plain ToolCall type). Once the event shapes converge, the callback types could be unified as shared AgentOnStartCallback, AgentOnStepStartCallback, etc. instead of separate WorkflowAgent* and ToolLoopAgent* types.

Phase 2: Add prepareCall support ✅ (#14037)

1. Add prepareCall to WorkflowAgentOptions
2. Call it in stream() before the iterator, similar to ToolLoopAgent's prepareCall()

Unblocked 1 GAP test.

Remaining work from Phase 2: ToolLoopAgent's prepareCall also supports stopWhen, activeTools, and experimental_download in its input/output types — these are not yet in WorkflowAgent's PrepareCallOptions/PrepareCallResult. Additionally, ToolLoopAgent supports typed CALL_OPTIONS that flow through prepareCall as options — WorkflowAgent doesn't have this concept.

Phase 3: Add workflow serialization support to all provider models ✅ (#13779)

Adds WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE to all 59 provider model classes (language, image, embedding, speech, transcription, video). Adds serializeModel() and deserializeModelConfig() helpers to @ai-sdk/provider-utils:

• serializeModel resolves config.headers() at serialization time so auth credentials survive the step boundary as plain key-value objects
• deserializeModelConfig wraps plain-object headers back into a function on deserialization

Makes headers optional in all provider config types so deserialized models work without pre-configured auth. Includes documentation for third-party provider authors.

Remaining work from Phase 3: async headers providers. Four providers have async getHeaders which can't be resolved synchronously at serialization time. These need per-provider handling or a model factory function workaround:

• Gateway — async OIDC token resolution (AI_GATEWAY_API_KEY env var fallback)
• Amazon Bedrock (anthropic subprovider) — async SigV4 credential loading (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY env vars)
• KlingAI — async JWT generation from KLINGAI_ACCESS_KEY/KLINGAI_SECRET_KEY env vars
• Google Vertex — async Resolvable headers (GOOGLE_VERTEX_API_KEY env var for express mode)

Phase 4: Add needsApproval support ✅ (#14084)

1. Before executing a tool, check tool.needsApproval (boolean or async function)
2. If approval needed, pause the loop and return pending tool calls (like client-side tools)
3. Handle approval resumption: collect tool-approval-response parts, execute approved tools, create denial results
4. Write tool results and step boundaries to the UI stream so tool parts transition to output-available state and convertToModelMessages produces correct message structure for multi-turn conversations

This unblocked 2 GAP tests.

Phase 5: Telemetry integration listeners

1. Wire through telemetry integration listeners from experimental_telemetry
2. Call them alongside agent callbacks at each lifecycle point

This unblocks 3 GAP tests.

Phase 6: Clean up duplication

1. Extract shared mergeCallbacks utility ✅ (done in feat(workflow): add onStart, onStepStart, onToolCallStart, onToolCallFinish callbacks #14036 — moved to ai/internal, used by both ToolLoopAgent and WorkflowAgent)
2. Remove duplicate filterTools (use one location)
3. Replace getErrorMessage with import from @ai-sdk/provider-utils
4. Remove safeParseInput if unused
5. Simplify prepareStep override application in streamTextIterator

Future work

• WorkflowAgent: provider metadata filtering across turns #14293 — Provider metadata filtering across turns
• WorkflowAgent: binary data normalization across step boundaries #14294 — Binary data normalization across step boundaries
• WorkflowAgent: provider-executed tool approvals are silently dropped on resume #14292 — WorkflowAgent has the inverse bug: provider-executed tool approvals are silently dropped (sent zero times) on the approval resume path

Done

• Separate UIMessageChunk conversion from model streaming (refactor: separate UIMessageChunk conversion from model streaming #13780)
  Extracts UIMessageChunk conversion from doStreamStep into a standalone utility, making the model streaming layer independent of UI concerns. doStreamStep returns raw LanguageModelV4StreamPart[] chunks; UIMessageChunk conversion is a separate, optional step. writable becomes optional in WorkflowAgentStreamOptions — when omitted, the agent streams ModelMessages only. Follows streamText's toUIMessageStream() pattern.
• Use experimental_streamModelCall in doStreamStep (refactor: use experimental_streamModelCall in doStreamStep #13820)
  Replace doStreamStep internals with experimental_streamModelCall. Eliminates ~300 lines of duplicated stream transformation, gains tool call parsing/repair, retry logic, and Experimental_ModelCallStreamPart stream types.
• Export mergeAbortSignals from ai/internal (refactor: use shared mergeAbortSignals from ai/internal in WorkflowAgent #13616)
  Exports the existing mergeAbortSignals utility from ai/internal and replaces the manual ~25-line abort signal + timeout merging code in WorkflowAgent with the shared utility. Uses AbortSignal.timeout() instead of manual setTimeout + AbortController, matching how generateText/streamText handle the same concern.
• Wire missing callbacks (Phase 1) (feat(workflow): add onStart, onStepStart, onToolCallStart, onToolCallFinish callbacks #14036)
  Adds experimental_onStart, experimental_onStepStart, experimental_onToolCallStart, experimental_onToolCallFinish callbacks to WorkflowAgent. Extracts mergeCallbacks into ai/internal as shared utility used by both ToolLoopAgent and WorkflowAgent. Also fixes sideEffects: false breaking workflow step discovery and replaces resolveLanguageModel from ai/internal with gateway from ai to fix Next.js webpack resolution in step bundles.
• Add prepareCall support (Phase 2) (feat(workflow): add prepareCall callback #14037)
  Adds prepareCall callback to WorkflowAgentOptions, called once before the agent loop to transform model, instructions, generation settings, etc. tools excluded from return type since they're bound at construction time for type safety.

No longer pursued

• Stream-to-StepResult aggregator (Extract chunksToStepResult as shared utility in ai/internal #13459)
  chunksToStep was removed when experimental_streamModelCall was adopted in refactor: use experimental_streamModelCall in doStreamStep #13820.
• Public message conversion (step → messages for next turn) (Export toResponseMessages from ai/internal #13474)
  toolsToModelTools was removed when experimental_streamModelCall was adopted in refactor: use experimental_streamModelCall in doStreamStep #13820.
• Tool descriptor extraction (Extract getToolDescriptors as shared utility in ai/internal #13477)
  toolsToModelTools() was removed with the streamModelCall refactor.
• Extract V3→UIMessageChunk stream transform as shared utility (Extract V3→UIMessageChunk transform as shared utility in ai/internal #13433)
  Superseded by the streamModelCall refactor which eliminated the V3 stream layer.
• String-based model IDs in core functions
  Already supported — LanguageModel type accepts strings, all core functions resolve them via the global provider.
• Declarative stop conditions
  Not necessary — stopWhen runs in the agent's control loop outside step boundaries, so function-based conditions work without serialization. maxSteps covers the simple case as a serializable number.

Notes

• Resumption: the client-side is expected to specify which chunk to resume from at the workflow stream level (the V4StreamPart). If that maps 1-1 to UIMessageChunk, or if there's a way to map the correct resumption index from the number of UIMessageChunk parts that the client-side has received, that's what needs to be considered.
• repairToolCall not serializable across step boundaries. ToolCallRepairFunction is a function and can't cross the 'use step' serialization boundary. Left out of WorkflowAgent for now — experimental_streamModelCall handles repair internally when called outside a step boundary.
• abortSignal serialization. AbortSignal objects can't be serialized across step boundaries. The Workflow team is working on adding serialization support for abort signals.
• Tools validation: because of serialization/deserialization needed for step functions, we use validation capabilities and transformations of libraries like zod. Serialization is lossy.

Related issues

• Make AI SDK work in Workflow #12164

[vercel-ai-sdk]

SHALL NOT PASS

[gr2m]

The snapshot build published (https://github.com/vercel/ai/actions/runs/21530986703/job/62046593364) published @ai-sdk/durable-agent@0.0.1 instead of the usual snapshot versions. That was not planned.

[KaiKloepfer]

@gr2m I did some work on improving this from the workflow side, might be relevant to you? vercel/workflow#928 Still not full compatibility, but we got stuck on the same issues when trying to port a v6 app to use workflow.

[rovo89]

@gr2m I think this is the right approach, avoiding a lot of compatibility layers. However, it seems that the code is copied more or less 1:1 from the workflow code, which has simplified lots of things. For example, OpenAI's web_search doesn't work for me because toolsToModelTools() is extremely basic. I'm hoping this will be much closer to the original ToolLoopAgent.

I would offer to help, but I assume you already have own ideas how things should work (and I know little about the AI SDK internals). Anyway, if I can do anything, I'm happy to help.

[gr2m]

@KaiKloepfer thanks will have a look!

@rovo89 I'm focused on #12381 right now, please feel free to send PRs for exploration of different approaches.

[rovo89]

My current attempt is to simpy use ToolLoopAgent in a step function. 🙈

export async function chat(writable: WritableStream<UIMessageChunk>, messages: UIMessage[]) {
  'use step';
  const agent = new ToolLoopAgent({...});
  const stream = await createAgentUIStream({
    agent,
    uiMessages: messages,
  })
  await stream.pipeTo(writable)
}

Streaming works fine and I can use it exactly like I'm used to.

DurableAgent has quite some limitations:

• Many details are implemented as very simplified stubs, such as the tool preparation which prevents using OpenAI provider tools.
• The default downloader doesn't work because fetch is blocked (need to use their fetch step function instead) and supportedUrls is empty.
• Model has to be provided as step function, therefore requires extra layer / provider wrapper packages. Custom provider registries are harder to use.
• Message metadata is a lot harder to add, requires disabling default start/finish chunks and sending them separately.
• ...

But of course, it has benefits. As far as I understood:

• Can resume multi-step calls instead of repeating from scratch. Not sure what happens if an error occurs mid-step (e.g. network failure) - will probably run that step again, but what about the already sent chunks?!?
• Tool calls are steps, so they can also be retried.
• Hooks can simplify human-in-the-loop / tool approvals.
• More stable environment for the loop controller.

Some ideas how similar features could be achieved in (a subclass of) ToolLoopAgent:

• Read back the stream to reconstruct the message chunks so far and continue from there. Or more abstract: Needs a way to "preload" the loop with the previously recorded intermediate step results and continue with the next step.
• AFAIU, calling a step function from another step has no special meaning, so no retries etc. That's only when they're called from a workflow function. Similar for hooks. Generally, ToolLoopAgent and the functions it calls are somehow orchestrating (like workflow functions), but they're far from just stitching steps together. That's why I think it makes sense to run them in a step function, but they could benefit from sub-steps. That needs further thoughts.
• Of course, this assumes that the setup is still the same on the next retry, like all tools being defined in the same way, which seems to be guaranteed in the workflow VM. Then again, how big is the risk that this happens accidently and how big could the damage be?

[gr2m]

I want to try two different approaches in separate PRs against gr2m/durable-agent

1. Try to refactor streamText() itself so that it works in a workflow context.
2. Refactor streamText() to export lower-level orchestration code which then can be used by DurableAgent

I think 1. won't be possible for several reasons but I want to see how far I can get.

For the providers, as a start I want to re-export all first-party providers with the symbols needed for workflow step serialization/deserialization and the "use step" directive in doStream()

[lgrammel]

move to utils

[gr2m]

as in packages/provider-utils or packages/ai/src/util where it is now?
https://github.com/vercel/ai/blob/4e8fa0e3bb478b72b243a972e53c5834517b3159/packages/ai/src/util/merge-listeners.ts

[lgrammel]

should this be typed to languagemodelv4 since the docs say it is for a language model (also should the param be called model)

[gr2m]

.config is a private implementation detail. We have access to it at runtime but typescript has no way to express that. Hence the any.

[lgrammel]

alternative: deserialize model that accepts model class prototype and config and then returns the model

(seems better if possible because then serializeModel / deserializeModel are clear opposites)

[gr2m]

Done in c11b83e — added deserializeModel(ModelClass, options) as the symmetric opposite of serializeModel, and updated all provider model classes to use it.

[lgrammel]

is this model specific?

[gr2m]

Yes some models are not serializable because of async headers methods

I mentioned this in the PR description

Remaining work from Phase 3: async headers providers. Four providers have async getHeaders which can't be resolved synchronously at serialization time. These need per-provider handling or a model factory function workaround:

• Gateway — async OIDC token resolution (AI_GATEWAY_API_KEY env var fallback)
• Amazon Bedrock (anthropic subprovider) — async SigV4 credential loading (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY env vars)
• KlingAI — async JWT generation from KLINGAI_ACCESS_KEY/KLINGAI_SECRET_KEY env vars
• Google Vertex — async Resolvable headers (GOOGLE_VERTEX_API_KEY env var for express mode)

The workflow team is looking into support of async serialize methods which will unblock support for these providers.