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:

The dynamicToolSchemas option enables MCP tool support for workers executed via the SDK. Pass tool schemas from @octavus/computer (or any ToolProvider) so the worker can use MCP tools like browser, filesystem, and shell. Schemas are sent on the first request and cached for continuation rounds.

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