Agent

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

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:305

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:238

The conversation history of messages between user and assistant.

Implementation of

LocalAgent.messages

---

appState

readonly appState: StateStore;

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

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:249

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:255

The model provider used by the agent for inference.

Implementation of

LocalAgent.model

---

systemPrompt?

optional systemPrompt?: SystemPrompt;

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

The system prompt to pass to the model provider.

Implementation of

LocalAgent.systemPrompt

---

name

readonly name: string;

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

The name of the agent.

Implementation of

InvokableAgent.name

---

id

readonly id: string;

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

The unique identifier of the agent instance.

Implementation of

LocalAgent.id

---

description?

readonly optional description?: string;

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

Optional description of what the agent does.

Implementation of

InvokableAgent.description

---

sessionManager?

readonly optional sessionManager?: SessionManager;

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

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

---

_interruptState

_interruptState: InterruptState;

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

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

Accessors

tools

Get Signature

get tools(): Tool[];

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

The tools this agent can use.

Returns

Tool[]

---

toolRegistry

Get Signature

get toolRegistry(): ToolRegistry;

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

The tool registry for managing the agent’s tools.

Returns

ToolRegistry

Implementation of

LocalAgent.toolRegistry

---

cancelSignal

Get Signature

get cancelSignal(): AbortSignal;

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

The cancellation signal for the current invocation.

Tools can pass this to cancellable operations (e.g., fetch(url, { signal: agent.cancelSignal })). 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:415

Register a hook callback for a specific event type.

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

---

initialize()

initialize(): Promise<void>;

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

Returns

Promise<void>

---

cancel()

cancel(): void;

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

Cancels the current agent invocation cooperatively.

The agent will stop at the next cancellation checkpoint:

• During model response streaming
• Before tool execution
• Between sequential tool executions
• At the top of each agent loop cycle

If a tool is already executing, it will run to completion unless the tool checks LocalAgent.cancelSignal | cancelSignal internally.

Hook callbacks can check event.agent.cancelSignal.aborted to detect cancellation and adjust their behavior accordingly.

The stream/invoke call will return an AgentResult with stopReason: 'cancelled'. If the agent is not currently invoking, this is a no-op.

Returns

void

Example

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

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

---

invoke()

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

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

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

---

stream()

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

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

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

The agent loop manages the conversation flow by:

1. Streaming model responses and yielding all events
2. Executing tools when the model requests them
3. 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:718

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:752

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:

1. Start with preset fields (e.g. 'session' captures all fields)
2. Add any include fields
3. 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:781

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