AgentState

Defined in: src/agent/state.ts:18

Agent state provides key-value storage outside conversation context. State is not passed to the model during inference but is accessible by tools (via ToolContext) and application logic.

All values are deep copied on get/set operations to prevent reference mutations. Values must be JSON serializable.

Example

const state = new AgentState({ userId: 'user-123' })
state.set('sessionId', 'session-456')
const userId = state.get('userId') // 'user-123'

Methods

get()

Call Signature

get<TState, K>(key): TState[K];

Defined in: src/agent/state.ts:53

Get a state value by key with optional type-safe property lookup. Returns a deep copy to prevent mutations.

Type Parameters

Type Parameter	Default type	Description
`TState`	-	The complete state interface type
`K` extends `string` \| `number` \| `symbol`	keyof `TState`	The property key (inferred from argument)

Parameters

Parameter	Type	Description
`key`	`K`	Key to retrieve specific value

Returns

TState[K]

The value for the key, or undefined if key doesn’t exist

Example

// Typed usage
const user = state.get<AppState>('user')      // { name: string; age: number } | undefined

// Untyped usage
const value = state.get('someKey')            // JSONValue | undefined

Call Signature

get(key): JSONValue;

Defined in: src/agent/state.ts:54

Get a state value by key with optional type-safe property lookup. Returns a deep copy to prevent mutations.

Parameters

Parameter	Type	Description
`key`	`string`	Key to retrieve specific value

Returns

JSONValue

The value for the key, or undefined if key doesn’t exist

Example

// Typed usage
const user = state.get<AppState>('user')      // { name: string; age: number } | undefined

// Untyped usage
const value = state.get('someKey')            // JSONValue | undefined

set()

Call Signature

set<TState, K>(key, value): void;

Defined in: src/agent/state.ts:88

Set a state value with optional type-safe property validation. Validates JSON serializability and stores a deep copy.

Type Parameters

Type Parameter	Default type	Description
`TState`	-	The complete state interface type
`K` extends `string` \| `number` \| `symbol`	keyof `TState`	The property key (inferred from argument)

Parameters

Parameter	Type	Description
`key`	`K`	The key to set
`value`	`TState`[`K`]	The value to store (must be JSON serializable)

Returns

void

Throws

Error if value is not JSON serializable

Example

// Typed usage
state.set<AppState>('user', { name: 'Alice', age: 25 })

// Untyped usage
state.set('someKey', { any: 'value' })

Call Signature

set(key, value): void;

Defined in: src/agent/state.ts:89

Set a state value with optional type-safe property validation. Validates JSON serializability and stores a deep copy.

Parameters

Parameter	Type	Description
`key`	`string`	The key to set
`value`	`unknown`	The value to store (must be JSON serializable)

Returns

void

Throws

Error if value is not JSON serializable

Example

// Typed usage
state.set<AppState>('user', { name: 'Alice', age: 25 })

// Untyped usage
state.set('someKey', { any: 'value' })

delete()

Call Signature

delete<TState, K>(key): void;

Defined in: src/agent/state.ts:110

Delete a state value by key with optional type-safe property validation.

Type Parameters

Type Parameter	Default type	Description
`TState`	-	The complete state interface type
`K` extends `string` \| `number` \| `symbol`	keyof `TState`	The property key (inferred from argument)

Parameters

Parameter	Type	Description
`key`	`K`	The key to delete

Returns

void

Example

// Typed usage
state.delete<AppState>('user')

// Untyped usage
state.delete('someKey')

Call Signature

delete(key): void;

Defined in: src/agent/state.ts:111

Delete a state value by key with optional type-safe property validation.

Parameters

Parameter	Type	Description
`key`	`string`	The key to delete

Returns

void

Example

// Typed usage
state.delete<AppState>('user')

// Untyped usage
state.delete('someKey')

clear()

clear(): void;

Defined in: src/agent/state.ts:119

Clear all state values.

Returns

void

getAll()

getAll(): Record<string, JSONValue>;

Defined in: src/agent/state.ts:128

Get a copy of all state as an object.

Returns

Record<string, JSONValue>

Deep copy of all state

keys()

keys(): string[];

Defined in: src/agent/state.ts:137

Get all state keys.

Returns

string[]

Array of state keys