Events

In plain terms

The event bus is a mailbox. When something happens (“run started”, “tool used”, “run finished”), Agentium drops a note in the mailbox. You can listen. You watch with the bus. You steer with hooks.

I want to…	Use
Log, metrics, traces, webhooks	`eventBus` / `onAny`
Skip a tool, stop the loop, change messages	`hooks` / `loopHooks`

Trying to “approve a tool” by emitting on the bus will not work. Approval has its own API. See Approval.

The smallest example

const agent = new Agent({
  name: "assistant",
  model: openai(process.env.OPENAI_MODEL ?? "gpt-6.1-sol"),
});

agent.eventBus.on("run.start", ({ input }) => {
  console.log("User asked:", input);
});

agent.eventBus.on("run.complete", ({ output }) => {
  console.log("Answer:", output.text);
});

await agent.run("Hello");

agent.events is the same object as agent.eventBus.

Listen to everything — `onAny`

Best attachment point for tracers. You don’t have to list every event name.

agent.eventBus.onAny((event, data) => {
  console.log(event, data);
});

One bus for the whole process

By default each agent/team/workflow gets its own bus. A tracer on agent A will not see agent B. Share one:

// Option A
new Agent({ name: "a", model, sharedEventBus: true });
new Agent({ name: "b", model, sharedEventBus: true });

// Option B
new Agent({ name: "a", model, eventBus: EventBus.shared });

import { EventBus } from "@agentium/core";

EventBus.shared.onAny((event, data) => {
  // every entity in this Node process
});

EventBus.resetShared() exists for tests.

Events that actually fire

Prefer this short list (LIFECYCLE_EVENTS):

Event	When
`run.start`	A run begins
`run.complete`	A run finished
`run.error`	A run threw
`run.cancelled`	`AbortSignal` fired
`run.stream.chunk`	A stream piece
`tool.call` / `tool.result`	A tool ran
`tool.approval.request` / `tool.approval.response`	Human gate
`team.delegate`	Team handed work to a member
`handoff.transfer` / `handoff.complete`	Agent handoff
`workflow.step`	Workflow step start/done/error
`memory.extract` / `memory.error`	Memory job
`memory.correction.recorded`	Human correction saved
`memory.learning.invalidated`	A lesson was superseded
`usage.recorded`	Usage committed for an attempt
`cost.assessed`	A cost assessment was created
`budget.checked`	Admission decision before dispatch
`accounting.error`	Accounting needs attention
`cost.tracked`	Legacy replacement total for a run
`cache.hit` / `cache.miss`	Semantic cache
`subagent.start` / `subagent.complete` / `subagent.error`	Helper agent
`context.compacted`	Context window was trimmed/summarized
`reflection.critique`	Self-critique pass finished

AgentEventMap only lists events that actually fire. A typo in an event name is a type error. Voice and browser events live on the same map but are not in LIFECYCLE_EVENTS.

Payloads

Event	Payload fields
`run.start`	`runId: string`, `agentName: string`, `input: string`
`run.complete`	`runId: string`, `output: RunOutput`
`run.error`	`runId: string`, `error: Error`
`run.cancelled`	`runId: string`, `agentName: string`
`run.stream.chunk`	`runId: string`, `chunk: string`
`tool.call`	`runId: string`, `toolName: string`, `args: unknown`
`tool.result`	`runId: string`, `toolName: string`, `result: unknown`
`tool.approval.request`	`requestId`, `toolName`, `args`, `agentName`, `runId`
`tool.approval.response`	`requestId`, `approved: boolean`, `reason?: string`
`team.delegate`	`runId`, `memberId`, `task`
`handoff.transfer`	`runId`, `fromAgent`, `toAgent`, `reason`
`handoff.complete`	`runId`, `chain: string[]`, `finalAgent`
`workflow.step`	`runId`, `stepName`, `status: "start" \| "done" \| "error"`
`memory.extract`	`sessionId`, `userId?`, `agentName`
`memory.error`	`store`, `error: Error`, `agentName`
`memory.correction.recorded`	`correctionId`, `agentName`, `field?`, `entityKey?`, `runId?`
`memory.learning.invalidated`	`learningIds: string[]`, `supersededBy`, `agentName`
`usage.recorded`	`runId?`, `attemptId`, `operationId`, `usageRevision`, `usageStatus`
`cost.assessed`	`runId?`, `assessment: CostAssessment`
`budget.checked`	`runId?`, `attemptId`, `decision: BudgetDecision`
`accounting.error`	`runId?`, `attemptId`, `error: unknown`
`cost.tracked`	`runId`, `agentName`, `modelId`, `usage: TokenUsage`, `cost?: number`
`cache.hit`	`agentName`, `input`, `cachedId`
`cache.miss`	`agentName`, `input`
`subagent.start`	`runId`, `parentRunId`, `agentName`, `task`
`subagent.complete`	`runId`, `parentRunId`, `agentName`, `text`
`subagent.error`	`runId`, `parentRunId`, `agentName`, `error: Error`
`context.compacted`	`runId`, `beforeTokens`, `afterTokens`, `strategy`
`reflection.critique`	`runId`, `pass: boolean`, `score: number`, `feedback`

cost.tracked is a replacement run total. Do not sum successive events. For durable totals and incomplete prices, query the accounting store. See cost tracking. Voice: voice.connected, voice.audio, voice.transcript, voice.tool.call, voice.tool.result, voice.error, voice.disconnected. Browser: browser.screenshot, browser.action, browser.step, browser.done, browser.error. Import the list:

import { LIFECYCLE_EVENTS } from "@agentium/core";

Methods

Every method is chainable except emit (returns whether anyone heard it).

Method	Signature	Meaning
`on`	`on<K extends keyof AgentEventMap>(event: K, handler: (data: AgentEventMap[K]) => void): this`	Subscribe. Called every time.
`once`	same as `on`	Subscribe for one firing, then auto-remove.
`off`	`off(event, handler): this`	Unsubscribe that exact function.
`onAny`	`onAny((event: string, data: unknown) => void): this`	Every event. Best for tracers.
`offAny`	`offAny(handler): this`	Remove a catch-all.
`emit`	`emit<K>(event: K, data: AgentEventMap[K]): boolean`	Internal. You rarely call this.
`removeAllListeners`	`(event?: K): this`	Clear one event, or all.
`EventBus.shared`	getter	Process-wide singleton.
`EventBus.resetShared`	`(): void`	Tests only — drop the singleton.

Observability

@agentium/observability already listens to the bus. You usually just call instrument(agent). See Observability.

Observer failures

Named and onAny listeners are observers: their thrown errors or rejected promises do not alter Agent/tool results or skip later observers. Configure onObserverError and maxObserverDiagnostics on EventBus for bounded diagnostics. Use getObserverDiagnostics() to inspect total, reported, and suppressed failures. Control hooks, policy, and approval retain their deliberate control semantics.

Build

Agent applications

Harness runtime

Teams and workflows

Data and capabilities

Interfaces and jobs

Voice and telephony

Verify and manage

In plain terms

The smallest example

Listen to everything — `onAny`

One bus for the whole process

Events that actually fire

Payloads

Methods

Observability

Observer failures

​In plain terms

​The smallest example

​Listen to everything — onAny

​One bus for the whole process

​Events that actually fire

​Payloads

​Methods

​Observability

​Observer failures

In plain terms

The smallest example

Listen to everything — `onAny`

One bus for the whole process

Events that actually fire

Payloads

Methods

Observability

Observer failures