WorkflowAgent

Creates a durable, resumable AI agent for use inside a workflow. WorkflowAgent handles the agent loop, tool schema serialization across workflow step boundaries, and built-in tool approval flows.

Unlike ToolLoopAgent from the ai package, WorkflowAgent is designed to survive process restarts, pause for human approval, and integrate with the Workflow DevKit's step mechanism.

WorkflowAgent supports runtimeContext for shared agent state and toolsContext for per-tool context. Because these values can cross workflow and step boundaries, keep them serializable durable data. Unlike ToolLoopAgent, do not place functions, class instances, symbols, database clients, or SDK clients in context; pass identifiers or configuration and recreate non-serializable resources inside step functions.

import { WorkflowAgent } from '@ai-sdk/workflow';
import { tool } from 'ai';
import { z } from 'zod';

const agent = new WorkflowAgent({
  model: 'anthropic/claude-sonnet-5.5',
  instructions: 'You are a helpful assistant.',
  tools: {
    weather: tool({
      description: 'Get the weather in a location',
      inputSchema: z.object({
        location: z.string(),
      }),
      execute: async ({ location }) => ({
        location,
        temperature: 72,
      }),
    }),
  },
});

const result = await agent.stream({
  messages: [
    {
      role: 'user',
      content: [{ type: 'text', text: 'What is the weather in NYC?' }],
    },
  ],
});

console.log(result.messages);

To see WorkflowAgent in action, check out these examples.

Import

import { WorkflowAgent } from "@ai-sdk/workflow"

Constructor

Parameters

Properties

Methods

generate()

Runs the durable agent loop using the model's non-streaming doGenerate() method. Model calls and tool execution use the same orchestration as stream().

const result = await agent.generate({ prompt: 'Summarize the findings.' });
console.log(result.text);
console.log(result.usage);

Accepts WorkflowAgentGenerateOptions, sharing prompt/messages, instructions, generation settings, tools and runtime context, preparation, stopping, output, and lifecycle options with stream(). It does not accept writable, includeRawChunks, experimental_transform, sendFinish, or preventClose. Without a configured stop condition, generation stops after at most 20 steps. stream() retains its existing unbounded default.

The include option accepts requestBody, responseBody, and requestMessages booleans, all defaulting to false. Enable them only when the additional request/response data is needed. Response IDs, timestamps, model IDs, headers, and provider metadata are retained when supplied by the model.

Returns

Returns Promise<WorkflowAgentGenerateResult> with the core GenerateTextResult semantics:

• text, finishReason, rawFinishReason, and finalStep describe the final step.
• content, files, sources, warnings, tool calls, and tool results cover all steps.
• usage and totalUsage sum all steps while retaining token details and unknown counts.
• responseMessages includes generated messages, even when prepareStep replaces the input history.
• output defaults to text, or follows the constructor/per-call output specification. Reading it throws NoOutputGeneratedError when output is unavailable, such as a final tool-calls response.

Inside a workflow, timeout bounds model calls, including retries and dispatch after suspension. It does not cancel a hook that a tool is waiting on. Use the Workflow runtime’s run.cancel() to stop a suspended run. See deadlines, cancellation, and replay.

Generation failures reject. The end callback runs before complete-output parsing; a parsing failure can therefore reject after onEnd has run. Existing Workflow callback shapes and preparation precedence apply; they are not all identical to core's callback APIs.

Approval requests appear in content and responseMessages without requiring a writable. To continue, append responseMessages to the original history and add a tool message containing the user's tool-approval-response. Preserve the request signature and tool-call input; use the same experimental_toolApprovalSecret environment-variable reference on continuation. Local approvals are validated before execution, and provider-executed approval responses are forwarded to the provider. See approval round trips.

stream()

Runs the agent loop, streaming responses and executing tool calls as needed. Returns a promise resolving to a WorkflowAgentStreamResult.

const result = await agent.stream({
  messages: [{ role: 'user', content: [{ type: 'text', text: 'Hello' }] }],
});

Returns

Returns a Promise<WorkflowAgentStreamResult> with the following properties:

repairToolCall in a workflow

repairToolCall runs inside the model step. When you use it in a workflow, define the callback as a function with a 'use step' directive. You can set it on the constructor or pass it to stream().

Workflow saves a reference to the registered function and loads its implementation inside the model step. Keep any values captured by the function serializable. An ordinary inline callback causes a serialization error when it crosses this step boundary.

The callback can be asynchronous. Return the repaired tool call, or null if the repair cannot be completed. See tool call repair for repair strategies.

experimental_transform in a workflow

Pass a transform factory, or an array of factories, to stream(). Mark each factory with 'use step' so Workflow can load it inside the model step. The factory must return a TransformStream synchronously. Keep any captured values serializable.

import type { LanguageModelV4StreamPart } from '@ai-sdk/provider';
import { WorkflowAgent } from '@ai-sdk/workflow';
import { getWritable } from 'workflow';

function uppercaseText() {
  'use step';

  return new TransformStream<
    LanguageModelV4StreamPart,
    LanguageModelV4StreamPart
  >({
    transform(part, controller) {
      controller.enqueue(
        part.type === 'text-delta'
          ? { ...part, delta: part.delta.toUpperCase() }
          : part,
      );
    },
  });
}

export async function uppercaseWorkflow() {
  'use workflow';

  const agent = new WorkflowAgent({ model: 'openai/gpt-5' });

  return agent.stream({
    messages: [{ role: 'user', content: 'Write a short greeting.' }],
    writable: getWritable(),
    experimental_transform: uppercaseText,
  });
}

Utilities

createModelCallToUIChunkTransform(options?)

Creates a TransformStream that converts raw ModelCallStreamPart chunks (written by the agent to the writable stream) into UIMessageChunk objects suitable for client consumption.

import { createModelCallToUIChunkTransform } from '@ai-sdk/workflow';

return createUIMessageStreamResponse({
  stream: run.readable.pipeThrough(createModelCallToUIChunkTransform()),
});

When resuming with a WorkflowChatTransport cursor, replay the raw workflow stream from index 0 and pass the non-negative UI chunk index to the transform:

const readable = run
  .getReadable({ startIndex: 0 })
  .pipeThrough(createModelCallToUIChunkTransform({ uiStartIndex: startIndex }));

uiStartIndex must be a non-negative safe integer. Raw model stream parts and UI message chunks are not one-to-one, so do not pass a UI chunk index to getReadable. Negative tail indexes require a durable stream that already stores UIMessageChunk objects.

toUIMessageChunk()

Converts a single ModelCallStreamPart to a UIMessageChunk. Returns undefined for parts that don't map to UI chunks.

import { toUIMessageChunk } from '@ai-sdk/workflow';

const uiChunk = toUIMessageChunk(modelCallPart);

Types

ActiveTools

type ActiveTools<TTools extends ToolSet> =
  | ReadonlyArray<keyof TTools & string>
  | undefined;

Limits a workflow agent call to the listed tool names. undefined means no tool restriction is applied.

InferWorkflowAgentUIMessage

Infers the UI message type for a WorkflowAgent instance. Optionally accepts a second type argument for custom message metadata.

import { WorkflowAgent, InferWorkflowAgentUIMessage } from '@ai-sdk/workflow';

const agent = new WorkflowAgent({
  model: 'anthropic/claude-sonnet-5.5',
  tools: { weather: weatherTool },
});

type MyAgentUIMessage = InferWorkflowAgentUIMessage<typeof agent>;

InferWorkflowAgentTools

Infers the tool set type of a WorkflowAgent instance.

import { WorkflowAgent, InferWorkflowAgentTools } from '@ai-sdk/workflow';

type MyTools = InferWorkflowAgentTools<typeof myAgent>;

Examples

Basic Agent with Tools

import { WorkflowAgent } from '@ai-sdk/workflow';
import { tool } from 'ai';
import { z } from 'zod';

const agent = new WorkflowAgent({
  model: 'anthropic/claude-sonnet-5.5',
  instructions: 'You are a helpful assistant.',
  tools: {
    weather: tool({
      description: 'Get weather for a location',
      inputSchema: z.object({
        location: z.string(),
      }),
      execute: async ({ location }) => ({
        location,
        temperature: 72,
        condition: 'sunny',
      }),
    }),
  },
});

const result = await agent.stream({
  messages: [
    {
      role: 'user',
      content: [{ type: 'text', text: 'What is the weather in NYC?' }],
    },
  ],
});

console.log(result.messages);
console.log(result.steps);

Agent in a Workflow with Durable Tools

import { WorkflowAgent, type ModelCallStreamPart } from '@ai-sdk/workflow';
import { convertToModelMessages, tool, type UIMessage } from 'ai';
import { getWritable } from 'workflow';
import { z } from 'zod';

// Tool execute functions marked with 'use step' become durable workflow steps
// with automatic retries and persistence
async function searchFlightsStep(input: {
  origin: string;
  destination: string;
}) {
  'use step';
  const response = await fetch(`https://api.flights.example/search?...`);
  return response.json();
}

export async function chat(messages: UIMessage[]) {
  'use workflow';

  const modelMessages = await convertToModelMessages(messages);

  const agent = new WorkflowAgent({
    model: 'anthropic/claude-sonnet-5.5',
    instructions: 'You are a flight booking assistant.',
    tools: {
      searchFlights: tool({
        description: 'Search for available flights',
        inputSchema: z.object({
          origin: z.string(),
          destination: z.string(),
        }),
        execute: searchFlightsStep,
      }),
    },
  });

  const result = await agent.stream({
    messages: modelMessages,
    writable: getWritable<ModelCallStreamPart>(),
  });

  return { messages: result.messages };
}

import { createModelCallToUIChunkTransform } from '@ai-sdk/workflow';
import { createUIMessageStreamResponse, type UIMessage } from 'ai';
import { start } from 'workflow/api';
import { chat } from '@/workflow/agent-chat';

export async function POST(request: Request) {
  const { messages }: { messages: UIMessage[] } = await request.json();

  const run = await start(chat, [messages]);

  return createUIMessageStreamResponse({
    stream: run.readable.pipeThrough(createModelCallToUIChunkTransform()),
  });
}

Agent with Structured Output

import { WorkflowAgent, Output } from '@ai-sdk/workflow';
import { z } from 'zod';

const analysisAgent = new WorkflowAgent({
  model: 'anthropic/claude-sonnet-5.5',
});

const result = await analysisAgent.stream({
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'Analyze: "The product exceeded my expectations!"',
        },
      ],
    },
  ],
  output: Output.object({
    schema: z.object({
      sentiment: z.enum(['positive', 'negative', 'neutral']),
      score: z.number(),
      summary: z.string(),
    }),
  }),
});

console.log(result.output);
// { sentiment: 'positive', score: 9, summary: '...' }

Agent with Tool Approval

For WorkflowAgent, tool approval is configured on the tool definition with needsApproval. For generateText, streamText, and ToolLoopAgent, use toolApproval instead.

import { WorkflowAgent } from '@ai-sdk/workflow';
import { tool } from 'ai';
import { z } from 'zod';

const agent = new WorkflowAgent({
  model: 'anthropic/claude-sonnet-5.5',
  experimental_toolApprovalSecret: {
    environmentVariable: 'TOOL_APPROVAL_SECRET',
  },
  tools: {
    bookFlight: tool({
      description: 'Book a flight',
      inputSchema: z.object({
        flightId: z.string(),
        passengerName: z.string(),
      }),
      needsApproval: true, // Pauses the agent until user approves
      execute: bookFlightStep,
    }),
  },
});

When experimental_toolApprovalSecret is configured, each approval request is signed over its approval ID, tool call ID, tool name, and validated input. Replayed approvals with a missing or invalid signature do not execute the tool. The signature is preserved in the durable stream and UI message history, while only the environment variable name crosses workflow boundaries. Signing and verification steps read the raw secret from their local environment and do not serialize it. A stream-level reference overrides the constructor value.

Agent with Lifecycle Callbacks

import { WorkflowAgent } from '@ai-sdk/workflow';

const agent = new WorkflowAgent({
  model: 'anthropic/claude-sonnet-5.5',
  tools: { weather: weatherTool },

  // Agent-wide callbacks
  onStepEnd({ usage }) {
    console.log('Tokens used:', usage.totalTokens);
  },
});

const result = await agent.stream({
  messages,

  // Per-call callbacks (both fire)
  async onStepEnd({ usage }) {
    await trackUsage(usage);
  },

  onEnd({ steps, totalUsage }) {
    console.log(
      `Done in ${steps.length} steps, ${totalUsage.totalTokens} tokens`,
    );
  },
});