Lifecycle hooks

Use onEvent to update product interfaces, write audit records, or connect agent activity to your existing telemetry.

Listen to a run

const result = await agent.run({
  input,
  client,
  onEvent(event) {
    console.log(event.type, event.runId);
  },
});

Keep event handlers small. Move slow network or storage work onto your application’s queue when it should not delay the run.

Event families

Family	Events
Run	`run.started`, `run.resumed`, `run.waiting_for_human`, `run.cancelled`, `run.completed`, `run.failed`
Step	`step.started`, `step.completed`, `step.failed`, `step.cancelled`
Model	`model.requested`, `model.completed`, `model.failed`
Tool	`tool.started`, `tool.preliminary_result`, `tool.completed`, `tool.failed`
State	`checkpoint.saved`

step.completed is emitted after the completed step has been checkpointed. This lets a persistence or telemetry consumer treat it as a stable boundary.

Choose events for a product interface

Use model deltas from Streaming for live answer text.
Use tool events for tool-call cards and progress indicators.
Use run.waiting_for_human to show approval or input controls.
Use terminal run events to close loading states and record outcomes.

Start Here

Build

Observe

Reference

Listen to a run

Event families

Choose events for a product interface

​Listen to a run

​Event families

​Choose events for a product interface

​Related guides

Listen to a run

Event families

Choose events for a product interface

Related guides