Lifecycle Hooks
Observe step boundaries (start/end) to add lightweight instrumentation: logging, metrics, and UI progress updates.
Hooks are meant to be cheap and side-effect free: record what happened, don’t change what happens.
Hooks give you step-level observability with almost zero coupling.
Use hooks to emit metrics, attach logs to your trace pipeline, or update a UI—without modifying the agent loop.
Table of Contents
Hook signatures
Hooks receive a small context object (step id/index, goal, attempt, URL, and outcome).
| Field | Meaning |
|---|---|
stepId / step_id | Stable identifier for the step. |
stepIndex / step_index | 0-based step counter. |
goal | Natural language goal for the step. |
attempt | Retry attempt index within the step. |
success / outcome / error | Present on step end (best-effort), describing the step result. |
When hooks run
- Step start runs once per
agent.act(...)call, before the first snapshot/attempt is executed. - Step end runs once when the step finishes (success, failure, or exhausting retries).
Hooks are invoked even when tracing is disabled, so you can attach your own telemetry.
Examples
def on_start(ctx):
print("start", ctx.get("goal"), "step", ctx.get("step_index"))
def on_end(ctxBest practices
- Do not call browser actions inside hooks (avoid re-entrancy).
- Keep hooks fast (emit logs/metrics, enqueue work elsewhere).
- Treat hooks as an observability interface, not a control plane.
Related topics
- Agent Runtime — verification loop
- Tracing — step events and replay