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.

Table of Contents

1. Hook signatures
2. When hooks run
3. Examples
4. Best practices

Hook signatures

Hooks receive a small context object (step id/index, goal, attempt, URL, and outcome).

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(ctx):
    print("end", ctx.get("success"), "outcome", ctx.get("outcome"))

result = agent.act(
    "Click Sign In",
    on_step_start=on_start,
    on_step_end=on_end,
)

Best 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