Skip to main content
High-level facade over the complete low-level Agent SDK. Each run() or stream() uses a fresh server session. Use createSession() for explicit multi-turn state.

Example

Constructors

Constructor

Validate and create an Agent facade without starting a server.

Parameters

options?
AgentOptions Facade, runtime, and connection options.

Returns

Agent

Throws

When options conflict, a model id is malformed, or runtime config is unsupported.

Example

Methods

client()

Access the full low-level client used by this Agent. Mixing low-level active Session handles with facade resume ownership is unsupported. Injected clients remain borrowed.

Returns

Promise<AgentClient> The current low-level client.

Throws

When the Agent is closed or client creation fails.

Example


close()

Close every stream and Session owned by this Agent. Dedicated clients are closed. The process-global canonical client survives until shutdown(), and injected clients are never closed. Concurrent calls share one teardown promise.

Returns

Promise<void> A promise that settles after all owned resources are handled.

Throws

When teardown fails; multiple failures are combined in an AggregateError.

Example


createSession()

Create a long-lived Session for explicit multi-turn work.

Parameters

options?
AgentSessionOptions Flat session-create overrides. Turn cancellation is not accepted here.

Returns

Promise<Session> A caller-managed Session also owned by this Agent.

Throws

When the Agent is closed or creation fails.

Example


fork()

Fork a session transcript and apply the full facade profile before its dispatcher starts. Forks inherit the source working directory; a constructor cwd or directory is therefore rejected.

Parameters

sessionId
string Source session id.
options?
Optional source message boundary.
messageId?
string

Returns

Promise<Session> The configured fork Session.

Throws

On a cwd override, ownership conflict, or fork/configuration failure.

Example


resume()

Attach to an existing server session. Resume preserves stored runtime config and applies explicit constructor overrides before attaching callbacks and tools. Default facade values do not overwrite the stored configuration. Working directory cannot change.

Parameters

sessionId
string Existing session id on this Agent’s server.

Returns

Promise<Session> A live Session owned by this Agent.

Throws

On unsupported resume fields, ownership conflict, or missing session.

Example


run()

Run a prompt in a fresh session. Error result subtypes resolve with isError:true; setup and transport failures reject.

Parameters

prompt
PromptInput One prompt or an asynchronous sequence of turns.
options?
RunOptions Flat per-run overrides.

Returns

Promise<RunResult> The final turn result with required text and isError.

Throws

When the Agent is closed or setup/transport fails.

Example


stream()

Stream normalized events from a fresh session. Startup is lazy: the session is created by the first next(), sessionId(), or control call. Early loop exit invokes return(); call close() explicitly when abandoning a handle outside a loop.

Parameters

prompt
PromptInput One prompt or an asynchronous sequence of turns.
options?
AgentStreamOptions Stream and per-run overrides.

Returns

AgentStream A synchronous async-iterator handle with session controls.

Throws

Synchronously when the Agent is closed or options are invalid.

Example