Lifecycle hooks

Pass on_event to receive structured lifecycle events while a run executes.

result = agent.run(
  input: prompt,
  client: client,
  on_event: ->(event) {
    logger.info(
      "agent event",
      type: event[:type],
      run_id: event[:run_id],
      details: event[:details]
    )
  }
)

Useful events cover run start/completion/failure, model attempts, text and reasoning deltas, tool start/progress/completion/failure, and human checkpoints. Keep handlers fast. Queue slow persistence work and redact sensitive tool inputs before forwarding events externally.

Last modified on July 26, 2026

Outputs and retries DevTools

Start Here

Build

Observe

Reference