Workers API

The WorkersApi enables executing worker agents from your server. Workers are task-based agents that run steps sequentially and return an output value.

Basic Usage

WorkersApi Reference

generate()

Execute a worker and return the output directly.

Runs the worker to completion and returns the output value. This is the simplest way to execute a worker.

Returns:

Throws: WorkerError if the worker fails or completes without producing output.

execute()

Execute a worker and stream the response. Use this when you need to observe intermediate events like text deltas, tool calls, or progress tracking.

continue()

Continue execution after client-side tool handling.

Use this when the worker has tools without server-side handlers. The execution pauses with a client-tool-request event, you execute the tools, then call continue() to resume.

Shared Options

All methods accept the same options:

Parameters:

Tool Handlers

Provide tool handlers to execute tools server-side:

Tools defined in the worker protocol but not provided as handlers become client tools — the execution pauses and emits a client-tool-request event.

Error Handling

WorkerError (generate)

generate() throws a WorkerError on failure. The error includes an optional sessionId for constructing debug URLs:

Stream Errors (execute)

When using execute(), errors appear as stream events:

Error Types

Cancellation

Use an abort signal to cancel execution:

With execute() and a manual controller:

Streaming

When you need real-time visibility into the worker's execution — text generation, tool calls, or progress — use execute() instead of generate().

Basic Streaming

Streaming to HTTP Response

Convert worker events to an SSE stream:

Client Tool Continuation

When workers have tools without handlers, execution pauses:

The client-tool-request event includes:

Stream Events

Workers emit standard stream events plus worker-specific events.

Worker Events

Common Events

Full Examples

generate()

execute()

For full control over streaming events and progress tracking:

Next Steps

• Workers Protocol — Worker protocol reference
• Streaming — Understanding stream events
• Tools — Tool handler patterns