#Events

Every run of the kernel yields a single typed stream: AgentEvent, a discriminated union covering everything the loop does — model calls, tool executions, approvals, compaction, errors, and the final result. This is how you build UIs, logs, and telemetry on top of lite-agent: consume the stream and render it. Events are observe only — handling an event never changes agent behavior.

#Usage

Consume the stream with agent.run(...) and discriminate on ev.type:

import { createAgent, nativeCodec, fakeProvider, textBlock } from "@lite-agent/core";

const agent = createAgent({
  model: fakeProvider([
    { text: "hi", message: { role: "assistant", content: [textBlock("hi")] } },
  ]),
  codec: nativeCodec(),
});

for await (const ev of agent.run("hello")) {
  if (ev.type === "text_delta") process.stdout.write(ev.text);
}

Events forwarded from a subagent carry an agentId; the main agent's events don't.

#The AgentEvent union

#Emitting your own events

Middleware and tools can emit through ctx.emit(ev); the kernel buffers those events in a queue and drains it at loop boundaries. Emitting never pauses the loop, and a slow consumer never blocks the kernel — see drain semantics.

#See also

• The kernel — the loop that produces this stream, and drain semantics.
• Middleware — ctx.emit and the layers that observe the loop.
• Context compaction — the compaction and context_status events.
• Persistence — the durable SessionEvent log behind session replay.