Events

Events stream what happens during a run as it happens. Every event has a type and a timestamp. Most apps only handle a small subset.

Consuming Events

Streaming

Use stream.events to iterate over events as they arrive.

const stream = await app.stream("assistant", {
  input: "What's the weather in Tokyo?",
});

for await (const event of stream.events) {
  switch (event.type) {
    case "TEXT_MESSAGE_CONTENT":
      process.stdout.write(event.delta);
      break;
    case "TOOL_CALL_RESULT":
      console.log("Tool result:", event.result);
      break;
    case "RUN_FINISHED":
      console.log("Done");
      break;
  }
}

The stream object also exposes runId and a result promise for the final run result.

onEvent callback

Use onEvent on run options when you don't need the full stream handle.

await app.run("assistant", {
  input: "Summarize this document...",
  onEvent: (event) => {
    if (event.type === "STEP_FINISH") {
      console.log(`Step ${event.stepIndex + 1} done (${event.terminationReason ?? "continuing"})`);
    }
  },
});

Run Lifecycle

These events mark the boundaries of a run.

Steps

The agent loop emits events at the start and end of each step.

When STEP_FINISH also ends the run, terminationReason is set to one of:

• "no_tool_calls": model finished naturally without requesting tools
• "stop_when": the agent's stopWhen condition returned true
• "max_steps": step limit reached

Tool Calls

These events cover the full lifecycle of a tool call, from streamed arguments to the final result.

Every tool event includes runId, agentName, parentMessageId, and toolTarget ("server", "client", or "hosted").

for await (const event of stream.events) {
  if (event.type === "TOOL_CALL_START") {
    console.log(`Calling ${event.toolCallName} (${event.toolTarget})`);
  }

  if (event.type === "TOOL_CALL_RESULT" && event.isError) {
    console.warn(`Tool error (${event.errorKind}):`, event.result);
  }
}

Tool Approvals

When a tool requires human approval, two event types track the flow.

TOOL_APPROVAL_UPDATED carries a state field with one of four values:

• "requested": waiting for a decision
• "approved": human approved, tool will execute
• "denied": human denied, tool call is skipped
• "expired": approval timed out

for await (const event of stream.events) {
  if (event.type === "TOOL_APPROVAL_REQUIRED") {
    showApprovalUI(event.toolCallName, event.meta);
  }

  if (event.type === "TOOL_APPROVAL_UPDATED" && event.state !== "requested") {
    closeApprovalUI(event.toolCallId, event.state);
  }
}

See Human in the Loop for the full approval lifecycle and how to submit decisions.

Message Content

Model output streams incrementally as START → CONTENT → END events. Build your UI to append chunks as they arrive.

Text

for await (const event of stream.events) {
  if (event.type === "TEXT_MESSAGE_CONTENT") {
    process.stdout.write(event.delta);
  }
}

Image

Audio

Video

Transcript

Transcript has an extra SEGMENT event with a finalized segment object including timing and optional speaker identification.

Reasoning

visibility is "summary" or "full", depending on what the model exposes.

Embedding

Custom Data

Use DATA_PART to emit your own structured data during a run. This is useful for progress updates, status changes, or any app-specific payload.

const analyzeTool = analyze.server(async ({ query }, { emit }) => {
  await emit({ type: "DATA_PART", data: { stage: "searching" }, timestamp: Date.now() });
  const results = await search(query);
  await emit({ type: "DATA_PART", data: { stage: "analyzing" }, timestamp: Date.now() });
  return summarize(results);
});

DATA_PART events have an optional id field for grouping related updates, and a data field with any serializable value.

Plugin Events

Plugins can observe events via onEvent and transform them via event middleware. See Plugins for details.