Bodhi Realtime Agent Framework

Appearance

bodhi-realtime-agent / BackgroundAgent

Interface: BackgroundAgent ​

Defined in: src/agent/background-agent.ts:137

Lifecycle hooks for a user-defined background producer.

Lifecycle:

  1. onStart(ctx) fires exactly ONCE — on the first session.connected envelope (NOT on construction; deferred until the live transport is ready, so the first publish lands on a live wire).
  2. onAgentTransfer(event) fires on every agent.transfer_completed.
  3. onReconnect() fires on every session.reconnected (after the initial onStart). Implement only if you need to resync external state.
  4. onStop(reason) fires on session.close_requested / transport.closed, or on agent.transfer_completed when cancelOnTransfer === true.

Throws inside any hook are caught by the host actor and logged — a misbehaving agent does not bring down the session (per the 'background-agents': resume supervision policy).

Properties ​

cancelOnTransfer? ​

readonly optional cancelOnTransfer?: boolean

Defined in: src/agent/background-agent.ts:147

If true, ctx.signal is aborted and onStop('transfer') is invoked when an agent.transfer_completed envelope is observed. Default false — reminder-style producers usually survive transfer; flow- specific producers opt in.

name ​

readonly name: string

Defined in: src/agent/background-agent.ts:139

Stable name; used for logging and as the publish correlationId prefix.

Methods ​

onAgentTransfer()? ​

optional onAgentTransfer(event): void

Defined in: src/agent/background-agent.ts:161

Called after agent.transfer_completed. Invoked regardless of cancelOnTransfer (so the agent can observe the transition); when cancelOnTransfer === true, onStop('transfer') runs after this hook returns.

Parameters ​

event ​
fromAgent ​

string

toAgent ​

string

Returns ​

void

onReconnect()? ​

optional onReconnect(): void

Defined in: src/agent/background-agent.ts:169

Called on every transport reconnect (after the initial onStart). Optional — most agents don't need it because the host preserves their state across reconnect. Implement only when you need to resync state with external systems.

Returns ​

void

onStart() ​

onStart(ctx): void | Promise<void>

Defined in: src/agent/background-agent.ts:150

Called exactly once, on the first session.connected envelope.

Parameters ​

ctx ​

BackgroundAgentContext

Returns ​

void | Promise<void>

onStop()? ​

optional onStop(reason): void | Promise<void>

Defined in: src/agent/background-agent.ts:153

Called when the agent is removed, the session closes, or cancelOnTransfer triggers.

Parameters ​

reason ​

string

Returns ​

void | Promise<void>

Built with VitePress