AI SDK is Vercel's framework-agnostic TypeScript toolkit for building AI-powered apps and agents — unified provider access, streaming, tool calling, structured output, and UI hooks. Workflow SDK complements it by making the multi-turn loop durable: the conversation state, hooks, and per-turn responses survive restarts and timeouts. Note that in this pattern the durability boundary is the entire turn — individual tool calls inside a turn are not durable on their own (see Pitfalls below).

For the full AI SDK reference (providers, streamText, generateObject, useChat, tool calling, etc.) see the AI SDK docs. This page covers the Workflow-specific integration points.

When to use streamText directly

Use streamText() instead of DurableAgent when you need:

• The raw AI SDK API — streamText().toUIMessageStream(), onChunk, smoothStream, or other options that map directly to the streamText return value rather than DurableAgent.stream()
• Per-turn durability — wrap the entire agent response (model + tools) in a single "use step" function so one user turn is the atomic retry unit; useful when you want all tool calls inside a turn to re-execute together
• Custom multi-turn orchestration — manual hook loops, per-turn stream slicing (sliceUntilFinish), or other workflow patterns shown below that don't map cleanly to DurableAgent

DurableAgent already supports stopWhen, prepareStep, onStepFinish, structured output (experimental_output), per-step model switching, and provider options. See the DurableAgent reference.

One workflow run = one full conversation. The workflow suspends between turns on a hook and resumes when the next user message arrives. Conversation state, tool history, and intermediate computation all live inside the run.

1. One workflow = one conversation. The workflow loops on a hook, keeping allMessages, tool history, and state alive across turns.
2. runTurn is the durability boundary. Each turn is one step. The model request and all tool calls inside it run as plain inline functions within that step. If anything throws mid-turn, the whole runTurn retries — individual tool calls are not separately durable. See Pitfalls.
3. Hook is created once. turnHook.create({ token: workflowRunId }) outside the loop — calling it twice with the same token throws HookConflictError.
4. preventClose: true on pipeTo keeps the durable writable open so the next turn can write to it.
5. sliceUntilFinish in the API reads chunks until type === "finish", then closes the HTTP response. The source reader is released — not cancelled — so the workflow stream keeps flowing.
6. startIndex: tailIndex + 1 gives each follow-up response only the new chunks, avoiding replay of previous turns.
7. /done resumes the hook so the workflow exits cleanly, then returns a synthetic start + finish so useChat transitions out of "streaming".

Non-obvious correctness details worth knowing before adapting this pattern.

Tools are not individually durable

streamText() is invoked from inside runTurn (a "use step" function), and the AI SDK calls each tool by directly invoking its execute function in that same step. Even if a tool body has its own "use step" directive, that directive is a no-op when called from another step — the function just runs inline.

The consequences:

• The atomic retry unit is the entire runTurn, not the individual tool call.
• If processRefund succeeds and then the model call (or a later tool) throws, the whole turn retries, and processRefund will run again.
• Tool calls do not appear as separate entries in the event log or observability dashboard.

Mitigations:

• Make side-effectful tool implementations idempotent — dedupe server-side on a stable key (e.g. orderId, an Idempotency-Key header, etc.).
• Or use DurableAgent, which runs tools at workflow scope — each tool can be marked "use step" to become its own durable, retryable step, or stay at workflow level to use primitives like sleep() and hooks.

Snapshot tailIndex before resuming the hook

const tailIndex = await probe.getTailIndex(); // FIRST
await probe.cancel();
await turnHook.resume(runId, { message: text }); // THEN
const stream = run.getReadable({ startIndex: tailIndex + 1 });

Reversing the order races the workflow: by the time you read tailIndex, the next turn has already written its start chunk, and your startIndex + 1 skips past it.

Don't call writable.close() inside a workflow function

I/O operations like closing streams must happen inside a "use step" function. Calling writable.close() directly in the workflow body throws Not supported in workflow functions. When the workflow returns, the runtime closes the underlying writable for you.

Don't use TransformStream.terminate() to slice the stream

A TransformStream with controller.terminate() on the finish chunk seems like the obvious fit for sliceUntilFinish, but throws Invalid state: TransformStream has been terminated when late-arriving chunks hit the transform callback. Manual pumping through a custom ReadableStream (as shown above) sidesteps the problem entirely.

Release the source reader, don't cancel it

In sliceUntilFinish, use reader.releaseLock() in the finally block rather than source.cancel(). Cancelling propagates upstream and closes the durable writable, breaking the next turn. Releasing the lock just detaches our reader; the durable stream keeps flowing.

Handle stale runId gracefully

Clients can send a runId from a long-gone workflow (localStorage, back button, server restart). Wrap the follow-up path in a try/catch for not found / expired and fall through to the first-turn code path to start a fresh workflow.

streamText vs DurableAgent

Use DurableAgent for most agent use cases. Use streamText when you need the raw AI SDK surface or a per-turn durability boundary.

AI SDK (docs)

• streamText() — core streaming function; toUIMessageStream() pipes into the durable writable
• tool() / tool calling — tools are plain async functions invoked by streamText inside the turn step; they are not individually durable in this pattern (see Pitfalls)
• stepCountIs() / stopWhen — bound the agent loop inside each turn
• convertToModelMessages() / createUIMessageStreamResponse() — UI ↔ model message conversion at the API boundary
• useChat() — React hook that consumes the UI message stream on the client

Workflow SDK

• "use step" — applied to runTurn to make each turn a durable, retryable unit
• defineHook() — suspension point for follow-up messages
• getWritable() — resumable stream output
• getRun() — run.getReadable({ startIndex }) for slicing per-turn streams
• WorkflowChatTransport — passes runId between turns