Agent

Orchestrates the interaction between a model, a set of tools, and MCP clients. The Agent is responsible for managing the lifecycle of tools and clients and invoking the core decision-making loop.

Implements

InvokableAgent

Constructors

Constructor

new Agent(config?): Agent;

Defined in: src/agent/agent.ts:566

Creates an instance of the Agent.

Parameters

Parameter	Type	Description
`config?`	`AgentConfig`	The configuration for the agent.

Returns

Agent

Properties

messages

messages: Message[];

Defined in: src/agent/agent.ts:424

The conversation history of messages between user and assistant.

Implementation of

LocalAgent.messages

appState

readonly appState: StateStore;

Defined in: src/agent/agent.ts:429

App state storage accessible to tools and application logic. State is not passed to the model during inference.

Implementation of

LocalAgent.appState

modelState

readonly modelState: StateStore;

Defined in: src/agent/agent.ts:435

Runtime state for the model provider. Used by stateful models to persist provider-specific data (e.g., response IDs for conversation chaining) across invocations.

Implementation of

LocalAgent.modelState

model

model: Model;

Defined in: src/agent/agent.ts:441

The model provider used by the agent for inference.

Implementation of

LocalAgent.model

systemPrompt?

systemPrompt?: SystemPrompt;

Defined in: src/agent/agent.ts:448

The system prompt to pass to the model provider.

Implementation of

LocalAgent.systemPrompt

name

readonly name: string;

Defined in: src/agent/agent.ts:453

The name of the agent.

Implementation of

InvokableAgent.name

id

readonly id: string;

Defined in: src/agent/agent.ts:458

The unique identifier of the agent instance.

Implementation of

LocalAgent.id

description?

readonly description?: string;

Defined in: src/agent/agent.ts:463

Optional description of what the agent does.

Implementation of

InvokableAgent.description

contextManager?

readonly contextManager?: ContextManager;

Defined in: src/agent/agent.ts:468

The context manager for strategy-driven offloading, if configured.

Implementation of

LocalAgent.contextManager

sessionManager?

readonly sessionManager?: SessionManager;

Defined in: src/agent/agent.ts:472

The session manager for saving and restoring agent sessions, if configured.

memoryManager?

readonly memoryManager?: MemoryManager;

Defined in: src/agent/agent.ts:478

The memory manager for cross-session memory retrieval and storage, if configured.

storage?

readonly storage?: Storage<string, string>;

Defined in: src/agent/agent.ts:483

Default storage backend for agent subsystems.

Implementation of

LocalAgent.storage

baggageAttributes

readonly baggageAttributes: Readonly<Record<string, string>>;

Defined in: src/agent/agent.ts:488

OpenTelemetry baggage entries attached to the context for every invocation.

_interruptState

_interruptState: InterruptState;

Defined in: src/agent/agent.ts:553

Interrupt state for human-in-the-loop workflows.

Accessors

sandbox

Get Signature

get sandbox(): Sandbox;

Defined in: src/agent/agent.ts:498

Execution environment for running commands, code, and file operations.

Throws

DefaultNotConfiguredError if no sandbox is configured for this environment (e.g. browsers, where no host default is registered).

Returns

Sandbox

Implementation of

LocalAgent.sandbox

auxModel

Get Signature

get auxModel(): Model;

Defined in: src/agent/agent.ts:512

Model for auxiliary side calls (summarization, memory extraction, classification, steering, web fetch). Resolution order: configured auxModel > model.

Reading always yields a resolved Model. Assigning accepts a Model, a Bedrock model ID string, or undefined to revert to following model. Memory extraction resolves its model when attached to the agent and keeps it; every other side call resolves it at call time.

Throws

Error if assigned a ModelRouter.

Returns

Model

Set Signature

set auxModel(auxModel): void;

Defined in: src/agent/agent.ts:516

Model used for auxiliary side calls; defaults to model. See Agent.auxModel.

Parameters

Parameter	Type
`auxModel`	\| `string` \| `Model`<`BaseModelConfig`>

Returns

void

Implementation of

LocalAgent.auxModel

sessionId

Get Signature

get sessionId(): string;

Defined in: src/agent/agent.ts:526

A stable, unique identifier for the current conversation session.

If a SessionManager is attached, delegates to its sessionId. Otherwise, lazily generates and caches a random 8-character hex string.

Returns

string

Implementation of

LocalAgent.sessionId

tools

Get Signature

get tools(): Tool[];

Defined in: src/agent/agent.ts:982

The tools this agent can use.

Returns

Tool[]

toolRegistry

Get Signature

get toolRegistry(): ToolRegistry;

Defined in: src/agent/agent.ts:989

The tool registry for managing the agent’s tools.

Returns

ToolRegistry

Implementation of

LocalAgent.toolRegistry

toolExecutor

Get Signature

get toolExecutor():
  | ConcurrentToolExecutor
  | SequentialToolExecutor;

Defined in: src/agent/agent.ts:1002

Executor for tool calls from a single assistant turn.

Reading always yields the resolved executor instance. Assigning accepts an executor instance or a ToolExecutorStrategy string shorthand, which is resolved to the matching instance on write.

Throws

Error if assigned an unrecognized string shorthand.

Returns

| ConcurrentToolExecutor | SequentialToolExecutor

Set Signature

set toolExecutor(toolExecutor): void;

Defined in: src/agent/agent.ts:1006

Parameters

Parameter	Type
`toolExecutor`	\| `ConcurrentToolExecutor` \| `SequentialToolExecutor` \| `ToolExecutorStrategy`

Returns

void

metrics

Get Signature

get metrics(): AgentMetrics;

Defined in: src/agent/agent.ts:1013

Read-only snapshot of accumulated agent metrics (cycles, token usage, tool stats).

Returns

AgentMetrics

Implementation of

LocalAgent.metrics

isInvoking

Get Signature

get isInvoking(): boolean;

Defined in: src/agent/agent.ts:1020

Whether the agent is currently processing an invocation.

Returns

boolean

tool

Get Signature

get tool(): ToolCallerProxy;

Defined in: src/agent/agent.ts:1041

Direct tool calling accessor.

Returns a proxy where each property is a ToolHandle with .invoke() and .stream() methods:

const result = await agent.tool.calculator!.invoke({ a: 5, b: 3 })

for await (const event of agent.tool.calculator!.stream({ a: 5, b: 3 })) {
  console.log('progress:', event)
}

Supports underscore-to-hyphen and case-insensitive name resolution. Results are recorded in message history by default (pass { recordDirectToolCall: false } to skip).

Returns

ToolCallerProxy

cancelSignal

Get Signature

get cancelSignal(): AbortSignal;

Defined in: src/agent/agent.ts:1051

The cancellation signal for the current invocation.

SDK-managed tool contexts receive this as context.cancelSignal for cancellable operations. Hooks can check event.agent.cancelSignal.aborted to detect cancellation.

Returns

AbortSignal

Implementation of

LocalAgent.cancelSignal

Methods

addHook()

addHook<T>(
   eventType,
   callback,
   options?
): HookCleanup;

Defined in: src/agent/agent.ts:749

Type Parameters

Type Parameter
`T` extends `HookableEvent`

Parameters

Parameter	Type	Description
`eventType`	`HookableEventConstructor`<`T`>	The event class constructor to register the callback for
`callback`	`HookCallback`<`T`>	The callback function to invoke when the event occurs
`options?`	`HookCallbackOptions`	Optional configuration including execution order

Returns

HookCleanup

Cleanup function that removes the callback when invoked

Example

const agent = new Agent({ model })

const cleanup = agent.addHook(BeforeInvocationEvent, (event) => {
  console.log('Invocation started')
})

// Later, to remove the hook:
cleanup()

Implementation of

LocalAgent.addHook

addMiddleware()

Call Signature

addMiddleware<TContext, TResult, TEvent>(phase, handler): () => void;

Defined in: src/agent/agent.ts:769

Register an Input phase handler that transforms context before execution. Input handlers run before Wrap and Output handlers.

Type Parameters

Type Parameter
`TContext`
`TResult`
`TEvent`

Parameters

Parameter	Type
`phase`	`MiddlewareInputPhase`<`TContext`, `TResult`, `TEvent`>
`handler`	`MiddlewareInputHandler`<`TContext`>

Returns

() => void

Example

agent.addMiddleware(InvokeModelStage.Input, async (context) => ({
  ...context,
  systemPrompt: injectToSystemPrompt(context),
}))

Implementation of

LocalAgent.addMiddleware

Call Signature

addMiddleware<TContext, TResult, TEvent>(phase, handler): () => void;

Defined in: src/agent/agent.ts:777

Type Parameters

Type Parameter
`TContext`
`TResult`
`TEvent`

Parameters

Parameter	Type
`phase`	`MiddlewareWrapPhase`<`TContext`, `TResult`, `TEvent`>
`handler`	`MiddlewareHandler`<`TContext`, `TResult`, `TEvent`>

Returns

() => void

Implementation of

LocalAgent.addMiddleware

Call Signature

addMiddleware<TContext, TResult, TEvent>(phase, handler): () => void;

Defined in: src/agent/agent.ts:794

Register an Output phase handler that transforms the result after execution. Output handlers see the result after Wrap handlers complete. Execution order: Input → Wrap → Output.

Type Parameters

Type Parameter
`TContext`
`TResult`
`TEvent`

Parameters

Parameter	Type
`phase`	`MiddlewareOutputPhase`<`TContext`, `TResult`, `TEvent`>
`handler`	`MiddlewareOutputHandler`<`TResult`>

Returns

() => void

Example

agent.addMiddleware(InvokeModelStage.Output, async (result) => {
  log(`Model returned stopReason=${result.result.stopReason}`)
  return result
})

Implementation of

LocalAgent.addMiddleware

Call Signature

addMiddleware<TContext, TResult, TEvent>(stage, handler): () => void;

Defined in: src/agent/agent.ts:819

Register a middleware handler for a given stage (Wrap phase). Middleware wraps stage execution and can intercept, transform, or short-circuit operations.

Type Parameters

Type Parameter
`TContext`
`TResult`
`TEvent`

Parameters

Parameter	Type	Description
`stage`	`MiddlewareStage`<`TContext`, `TResult`, `TEvent`>	The stage token identifying the interception point
`handler`	`MiddlewareHandler`<`TContext`, `TResult`, `TEvent`>	The middleware handler function (async generator)

Returns

A cleanup function that removes the middleware when called

() => void

Example

const cleanup = agent.addMiddleware(InvokeModelStage, async function* (context, next) {
  const start = Date.now()
  const result = yield* next(context)
  console.log(`Model call took ${Date.now() - start}ms`)
  return result
})

// Later, remove the middleware:
cleanup()

Implementation of

LocalAgent.addMiddleware

initialize()

initialize(): Promise<void>;

Defined in: src/agent/agent.ts:865

Returns

Promise<void>

cancel()

cancel(options?): void;

Defined in: src/agent/agent.ts:1083

Cancels the current agent invocation cooperatively. Idempotent; no-op when the agent is not invoking. The pending invoke/stream resolves with stopReason: 'cancelled'.

The agent stops at the next cancellation-safe point (model streaming, before tools, between sequential tool calls, or the top of a loop cycle). A tool already executing runs to completion unless it checks context.cancelSignal. Hook callbacks can read event.agent.cancelSignal.aborted for the same.

For cancellation driven from outside the agent, prefer the cancelSignal option on invoke / stream.

Parameters

Parameter	Type	Description
`options?`	`CancelOptions`	See CancelOptions for `message` and `afterCurrentTools`.

Returns

void

Examples

setTimeout(() => agent.cancel(), 5000)
const result = await agent.invoke('Do something')
console.log(result.stopReason) // 'cancelled'

// From inside a tool: let the rest of the batch finish, then stop.
context.agent.cancel({ message: 'Task complete', afterCurrentTools: true })

Implementation of

LocalAgent.cancel

invoke()

invoke(args, options?): Promise<AgentResult>;

Defined in: src/agent/agent.ts:1147

Invokes the agent and returns the final result.

This is a convenience method that consumes the stream() method and returns only the final AgentResult. Use stream() if you need access to intermediate streaming events.

Parameters

Parameter	Type	Description
`args`	`InvokeArgs`	Arguments for invoking the agent
`options?`	`InvokeOptions`	Optional per-invocation options

Returns

Promise<AgentResult>

Promise that resolves to the final AgentResult

Example

const agent = new Agent({ model, tools })
const result = await agent.invoke('What is 2 + 2?')
console.log(result.lastMessage) // Agent's response

Implementation of

InvokableAgent.invoke

shutdown()

shutdown(): Promise<void>;

Defined in: src/agent/agent.ts:1170

Runs the agent’s shutdown procedures at end of life. Safe to call more than once, and a no-op when there is nothing to release.

Call it directly when you own the agent’s lifecycle (e.g. draining on a shutdown signal), or bind the agent with await using to run it automatically on scope exit.

Returns

Promise<void>

Example

await using agent = await createHarness()
await agent.invoke('summarize the repo')
// agent.shutdown() runs here as the scope exits

[asyncDispose]()

[asyncDispose](): Promise<void>;

Defined in: src/agent/agent.ts:1178

Runs Agent.shutdown when the agent leaves an await using scope, on normal exit and on throw, so its shutdown procedures run without a manual finally.

Returns

Promise<void>

stream()

stream(args, options?): AsyncGenerator<AgentStreamEvent, AgentResult, undefined>;

Defined in: src/agent/agent.ts:1212

Streams the agent execution, yielding events and returning the final result.

The agent loop manages the conversation flow by:

Streaming model responses and yielding all events
Executing tools when the model requests them
Continuing the loop until the model completes without tool use

Use this method when you need access to intermediate streaming events. For simple request/response without streaming, use invoke() instead.

An explicit goal of this method is to always leave the message array in a way that the agent can be reinvoked with a user prompt after this method completes. To that end assistant messages containing tool uses are only added after tool execution succeeds with valid toolResponses

Parameters

Parameter	Type	Description
`args`	`InvokeArgs`	Arguments for invoking the agent
`options?`	`InvokeOptions`	Optional per-invocation options

Returns

AsyncGenerator<AgentStreamEvent, AgentResult, undefined>

Async generator that yields AgentStreamEvent objects and returns AgentResult

Example

const agent = new Agent({ model, tools })

for await (const event of agent.stream('Hello')) {
  console.log('Event:', event.type)
}
// Messages array is mutated in place and contains the full conversation

Implementation of

InvokableAgent.stream

asTool()

asTool(options?): Tool;

Defined in: src/agent/agent.ts:1535

Returns a Tool that wraps this agent, allowing it to be used as a tool by another agent.

The returned tool accepts a single input string parameter, invokes this agent, and returns the text response as a tool result.

Note: You can also pass an Agent directly in another agent’s tools array — it will be wrapped automatically via this method.

Parameters

Parameter	Type	Description
`options?`	`AgentAsToolOptions`	Optional configuration for the tool name, description, and context preservation

Returns

Tool

A Tool wrapping this agent

Example

const researcher = new Agent({ name: 'researcher', description: 'Finds info', printer: false })

// Explicit wrapping
const writer = new Agent({ tools: [researcher.asTool()] })

// Automatic wrapping (equivalent)
const writer = new Agent({ tools: [researcher] })

takeSnapshot()

takeSnapshot(options): Snapshot;

Defined in: src/agent/agent.ts:1569

Captures a point-in-time snapshot of the agent’s current state.

Use snapshots to checkpoint agent state for later restoration, enabling use cases like undo/redo, branching conversations, and session persistence.

Fields are selected via a preset/include/exclude model:

Start with preset fields (e.g. 'session' captures all fields)
Add any include fields
Remove any exclude fields

Parameters

Parameter	Type	Description
`options`	`TakeSnapshotOptions`	Controls which fields to capture and optional app data to store

Returns

Snapshot

A Snapshot containing the captured agent state

Throws

Error if no fields would be included after applying options

Example

// Capture all session-relevant state
const snapshot = agent.takeSnapshot({ preset: 'session' })

// Capture only messages and state
const partial = agent.takeSnapshot({ include: ['messages', 'state'] })

// Capture session state but exclude interrupts
const noInterrupts = agent.takeSnapshot({ preset: 'session', exclude: ['interrupts'] })

// Attach application-owned metadata
const withMeta = agent.takeSnapshot({ preset: 'session', appData: { userId: 'u-123' } })

Implementation of

LocalAgent.takeSnapshot

loadSnapshot()

loadSnapshot(snapshot): void;

Defined in: src/agent/agent.ts:1598

Restores agent state from a previously captured snapshot.

Only fields present in snapshot.data are restored; absent fields are left unchanged. This allows partial snapshots to update specific aspects of state without affecting others.

Parameters

Parameter	Type	Description
`snapshot`	`Snapshot`	The snapshot to restore from

Returns

void

Throws

Error if snapshot.schemaVersion is incompatible or scope is wrong

Example

// Save and restore a conversation checkpoint
const checkpoint = agent.takeSnapshot({ preset: 'session' })

// ... agent continues processing ...

// Restore to the checkpoint
agent.loadSnapshot(checkpoint)

// Restore from a JSON-serialized snapshot (e.g. from storage)
const stored = JSON.parse(savedSnapshotJson)
agent.loadSnapshot(stored)

Implementation of

LocalAgent.loadSnapshot