DurableAgent

Overview

DurableAgent is a class for building AI agents that maintain state across workflow executions. It wraps AI model providers with durable execution capabilities, ensuring that your AI agents can survive interruptions, handle long-running operations, and automatically recover from failures.

Constructor

const agent = new DurableAgent(options)

DurableAgentOptions

required

Configuration for the durable agent

Show properties

string | (() => Promise<LanguageModel>)

required

The AI model to use. Can be:

A string for AI Gateway (e.g., 'anthropic/claude-opus')
A function returning a model instance from a provider

ToolSet

Tools available to the agent. Each tool should have:

description: Human-readable description
inputSchema: Zod schema for validation
execute: Function to run (can be a workflow step)

string

System prompt to guide the agent’s behavior

ToolChoice

Strategy for tool selection. Options: 'auto', 'required', 'none', or { type: 'tool', toolName: string }Default: 'auto'

number

Maximum tokens to generate in responses

number

Sampling temperature (0-1+). Higher values increase randomness.Recommended: Set either temperature or topP, not both

number

Nucleus sampling probability (0-1). Only tokens with top P probability mass are considered.Recommended: Set either temperature or topP, not both

number

Only sample from top K options. Advanced use only.

number

Penalty for repeating information (-1 to 1). 0 means no penalty.

number

Penalty for repeating words/phrases (-1 to 1). 0 means no penalty.

string[]

Stop generation when these sequences are encountered

number

Random seed for deterministic generation (if supported by model)

number

default:"2"

Maximum retry attempts for transient failures

TelemetrySettings

Observability configuration for tracing and metrics

Methods

stream()

Streams AI responses with tool execution and state management.

const result = await agent.stream(options)

DurableAgentStreamOptions

required

Show properties

ModelMessage[]

required

Conversation history in AI SDK format. Each message has:

role: 'user', 'assistant', or 'system'
content: String or array of content parts

WritableStream<UIMessageChunk>

required

Stream to write response chunks. Use getWritable() from workflow package.

string

Override the system prompt for this request

boolean

default:"false"

Keep stream open after completion (useful for multiple writes)

boolean

default:"true"

Send a ‘start’ chunk at the beginning of the stream

boolean

default:"true"

Send a ‘finish’ chunk at the end of the stream

number

Maximum number of sequential LLM calls. Prevents infinite loops.

StopCondition | StopCondition[]

Conditions to stop generation early (e.g., when specific tools are called)

ToolChoice

Override tool selection strategy for this request

string[]

Limit available tools to this subset

OutputSpecification

Parse structured output from the response. Use Output.object({ schema }) or Output.text().

boolean

default:"false"

Accumulate UIMessage[] during streaming. Result will include uiMessages property.

boolean

default:"false"

Include raw provider chunks in the stream for advanced use cases

PrepareStepCallback

Callback before each LLM call. Use for context management or dynamic configuration.

prepareStep: async ({ messages, stepNumber }) => {
  // Inject messages, change model, etc.
  return { messages: [...messages, ...injectedMessages] };
}

StreamTextOnStepFinishCallback

Called after each LLM step completes

StreamTextOnFinishCallback

Called when all steps complete successfully

StreamTextOnErrorCallback

Called when an error occurs during streaming

StreamTextOnAbortCallback

Called when the operation is aborted

unknown

Context passed to tool execution functions

ToolCallRepairFunction

Function to repair failed tool call parsing

StreamTextTransform | StreamTextTransform[]

Custom stream transformations

DownloadFunction

Custom URL download handler

Returns: Promise<DurableAgentStreamResult>

ModelMessage[]

Final conversation messages including all tool calls and results

StepResult[]

Details for each LLM step executed during the stream

OUTPUT

Parsed structured output (only when experimental_output is specified)

UIMessage[]

Accumulated UI messages (only when collectUIMessages: true)

Examples

Basic Usage

import { DurableAgent } from '@workflow/ai';
import { anthropic } from '@workflow/ai/providers/anthropic';
import { getWritable } from 'workflow';

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

  const agent = new DurableAgent({
    model: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY })('claude-3-5-sonnet-20241022'),
    system: 'You are a helpful coding assistant.',
    temperature: 0.7,
  });

  const result = await agent.stream({
    messages: [
      { role: 'user', content: 'Explain how async/await works in JavaScript' },
    ],
    writable: getWritable(),
  });

  console.log('Generated', result.steps.length, 'steps');
}

With Tools

import { DurableAgent } from '@workflow/ai';
import { openai } from '@workflow/ai/providers/openai';
import { getWritable } from 'workflow';
import { z } from 'zod';

async function searchDatabase(query: string) {
  'use step';
  // This runs as a durable step with automatic retries
  const results = await db.search(query);
  return results;
}

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

  const agent = new DurableAgent({
    model: openai({ apiKey: process.env.OPENAI_API_KEY })('gpt-4o'),
    tools: {
      searchDatabase: {
        description: 'Search the customer database',
        inputSchema: z.object({
          query: z.string().describe('Search query'),
        }),
        execute: async ({ query }) => searchDatabase(query),
      },
    },
  });

  await agent.stream({
    messages: [
      { role: 'user', content: 'Find customers in San Francisco' },
    ],
    writable: getWritable(),
    maxSteps: 5,
  });
}

Structured Output

import { DurableAgent, Output } from '@workflow/ai';
import { google } from '@workflow/ai/providers/google';
import { getWritable } from 'workflow';
import { z } from 'zod';

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

  const agent = new DurableAgent({
    model: google({ apiKey: process.env.GOOGLE_API_KEY })('gemini-2.0-flash-exp'),
  });

  const result = await agent.stream({
    messages: [
      { role: 'user', content: 'This product is amazing! I love it.' },
    ],
    writable: getWritable(),
    experimental_output: Output.object({
      schema: z.object({
        sentiment: z.enum(['positive', 'negative', 'neutral']),
        confidence: z.number().min(0).max(1),
        reasoning: z.string(),
      }),
    }),
  });

  console.log(result.experimental_output);
  // { sentiment: 'positive', confidence: 0.95, reasoning: '...' }
}

Dynamic Context Management

import { DurableAgent } from '@workflow/ai';
import { anthropic } from '@workflow/ai/providers/anthropic';
import { getWritable } from 'workflow';

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

  const agent = new DurableAgent({
    model: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY })('claude-3-5-sonnet-20241022'),
  });

  await agent.stream({
    messages: [
      { role: 'user', content: 'Help me with my code' },
    ],
    writable: getWritable(),
    prepareStep: async ({ messages, stepNumber }) => {
      // Inject context from external sources before each LLM call
      if (stepNumber === 0) {
        const context = await loadUserContext();
        return {
          messages: [
            { role: 'system', content: `User context: ${context}` },
            ...messages,
          ],
        };
      }
      return {};
    },
  });
}

Type Definitions

ToolSet

type ToolSet = Record<string, {
  description: string;
  inputSchema: ZodSchema;
  execute?: (input: any, context: {
    toolCallId: string;
    messages: ModelMessage[];
    experimental_context?: unknown;
  }) => Promise<any> | any;
}>;

ModelMessage

type ModelMessage = {
  role: 'user' | 'assistant' | 'system';
  content: string | Array<{
    type: 'text' | 'image';
    text?: string;
    image?: string | Uint8Array | URL;
  }>;
};

StepResult

type StepResult = {
  text: string;
  toolCalls: ToolCall[];
  toolResults: ToolResult[];
  finishReason: 'stop' | 'length' | 'content-filter' | 'tool-calls' | 'error' | 'other';
  usage: {
    promptTokens: number;
    completionTokens: number;
    totalTokens: number;
  };
  response: {
    id: string;
    model: string;
    timestamp: Date;
  };
};

Best Practices

Use workflow steps for tools: Mark tool execute functions with 'use step' for automatic retries and durability
Set maxSteps: Always set a reasonable maxSteps limit to prevent infinite loops
Handle errors gracefully: Use onError callback to log and handle errors appropriately
Manage context size: Use prepareStep to inject/remove messages dynamically and manage context window
Stream to the client: Always use getWritable() to stream responses for better UX
Choose the right model: Use prepareStep to switch models based on task complexity

Overview

Core API

AI SDK Integration

Runtime API

Framework Integrations

CLI

Overview

Constructor

Methods

stream()

Examples

Basic Usage

With Tools

Structured Output

Dynamic Context Management

Type Definitions

ToolSet

ModelMessage

StepResult

Best Practices

See Also

​Overview

​Constructor

​Methods

​stream()

​Examples

​Basic Usage

​With Tools

​Structured Output

​Dynamic Context Management

​Type Definitions

​ToolSet

​ModelMessage

​StepResult

​Best Practices

​See Also

Overview

Constructor

Methods

stream()

Examples

Basic Usage

With Tools

Structured Output

Dynamic Context Management

Type Definitions

ToolSet

ModelMessage

StepResult

Best Practices

See Also