AgentStateController

Manages active agent resolution, handoff recording, and agent state. Shared by Runtime and VoiceEngine.

Methods

clearAgent()

clearAgent(session, agentId): void;

Remove per-agent state from session.agentStates. No-op if absent.

Parameters

Parameter	Type
session	Session
agentId	string

Returns

void

---

getActiveAgent()

getActiveAgent(session, fallbackAgentId): string;

Resolve the active agent ID, falling back to the provided default.

Parameters

Parameter	Type
session	Session
fallbackAgentId	string

Returns

string

---

getAgentState()

getAgentState<T>(session, agentId): T | undefined;

Read per-agent state with optional type assertion. Returns undefined if absent or empty.

Type Parameters

Type Parameter	Default type
T	Record<string, unknown>

Parameters

Parameter	Type
session	Session
agentId	string

Returns

T | undefined

---

isCircularHandoff()

isCircularHandoff(
   handoffStack,
   agentId,
   maxVisits?): boolean;

Check whether visiting the given agent would constitute a circular handoff. Returns true if the agent has been visited >= maxVisits times in the handoff stack.

Parameters

Parameter	Type
handoffStack	string[]
agentId	string
maxVisits?	number

Returns

boolean

---

recordHandoff()

recordHandoff(args): void;

Record a handoff in the session’s handoff history.

Parameters

Parameter	Type
args	{ fromAgentId: string; reason: string; session: Session; toAgentId: string; }
args.fromAgentId	string
args.reason	string
args.session	Session
args.toAgentId	string

Returns

void

---

setActiveAgent()

setActiveAgent(session, agentId): void;

Set the active agent on the session.

Parameters

Parameter	Type
session	Session
agentId	string

Returns

void

---

setAgentState()

setAgentState(
   session,
   agentId,
   state): void;

Replace per-agent state fully (no merge). Use when the state is a single opaque blob.

Parameters

Parameter	Type
session	Session
agentId	string
state	Record<string, unknown>

Returns

void

---

updateAgentState()

updateAgentState(
   session,
   agentId,
   state): void;

Update per-agent state stored in session.agentStates. Merges with existing state.

Parameters

Parameter	Type
session	Session
agentId	string
state	Record<string, unknown>

Returns

void