Workers

Workers are agents designed for task-based execution. Unlike interactive agents that handle multi-turn conversations, workers execute a sequence of steps and return an output value.

When to Use Workers

Workers are ideal for:

• Background processing — Long-running tasks that don't need conversation
• Composable tasks — Reusable units of work called by other agents
• Pipelines — Multi-step processing with structured output
• Parallel execution — Tasks that can run independently

Use interactive agents instead when:

• Conversation is needed — Multi-turn dialogue with users
• Persistence matters — State should survive across interactions
• Session context — User context needs to persist

Worker vs Interactive

Protocol Structure

Workers use a simpler protocol structure than interactive agents:

settings.json

Workers are identified by the format field:

Key Differences

No Global Agent Config

Interactive agents have a global agent: section that configures a main thread. Workers don't have this — every thread must be explicitly created via start-thread:

This gives workers flexibility to use different models, tools, and settings at different stages.

Steps Instead of Handlers

Workers use steps: instead of handlers:. Steps execute sequentially, like handler blocks:

Output Value

Workers can return an output value to the caller:

The output field references a variable declared in variables:. If omitted, the worker completes without returning a value.

Available Blocks

Workers support the same blocks as handlers:

start-thread (Required for LLM)

Every thread must be initialized with start-thread before using next-message:

All LLM configuration goes here:

Simple Example

A worker that generates a title from a summary:

Advanced Example

A worker with multiple threads, tools, and agentic behavior:

Tool Handling

Workers support the same tool handling as interactive agents:

• Server tools — Handled by tool handlers you provide
• Client tools — Pause execution, return tool request to caller

See Server SDK Workers for tool handling details.

Stream Events

Workers emit the same events as interactive agents, plus worker-specific events:

All standard events (text-delta, tool calls, etc.) are also emitted.

Calling Workers from Interactive Agents

Interactive agents can call workers in two ways:

1. Deterministically — Using the run-worker block
2. Agentically — LLM calls worker as a tool

Worker Declaration

First, declare workers in your interactive agent's protocol:

run-worker Block

Call a worker deterministically from a handler:

LLM Tool Invocation

Make workers available to the LLM:

The LLM can then call workers as tools during conversation.

Display Modes

Control how worker execution appears to users:

Tool Mapping

Map parent tools to worker tools when the worker needs access to your tool handlers:

When the worker calls its search tool, your web-search handler executes.

Next Steps

• Server SDK Workers — Executing workers from code
• Handlers — Block reference for steps
• Agent Config — Model and settings