Principle:Openai Openai agents python Lifecycle Hooks
| Knowledge Sources | |
|---|---|
| Domains | Agent_Architecture, Observability |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Mechanism that allows user code to observe and react to events at different stages of an agent execution lifecycle.
Description
Lifecycle Hooks provide a callback-based extension point for instrumenting agent runs. The SDK defines two hook interfaces at different scopes: RunHooks (run-level, applied across all agents in a run) and AgentHooks (agent-level, scoped to a single agent). Each interface declares async callback methods corresponding to well-defined lifecycle events: agent start, LLM start, LLM end, tool start, tool end, agent end, and handoff.
RunHooks are passed via the `hooks=` parameter on `Runner.run()` and apply globally to all agents within that run. AgentHooks are set on individual `Agent` instances via the `hooks=` field and fire only for that specific agent. Both hook types receive context objects that provide access to usage statistics, turn input, and the current agent.
This decoupling of observation from execution follows the Observer pattern, allowing logging, metrics collection, debugging, and custom side-effects without modifying agent or tool logic. Hook callbacks are invoked in-line during the run loop, so they can inspect state but should avoid blocking operations.
Usage
Use this principle when you need to monitor, log, or react to specific stages of agent execution. Common use cases include tracking token usage across LLM calls, logging tool invocations for debugging, implementing custom metrics dashboards, and triggering side-effects on agent handoffs. RunHooks are preferred for cross-cutting concerns that apply to all agents, while AgentHooks are preferred for agent-specific instrumentation.
Theoretical Basis
The Lifecycle Hooks mechanism implements the Observer pattern applied to an agentic execution pipeline:
Pseudo-code Logic:
# Abstract lifecycle event flow
for each turn in run_loop:
fire(on_agent_start, agent, context)
fire(on_llm_start, agent, system_prompt, input_items)
response = call_model(agent, input)
fire(on_llm_end, agent, response)
for each tool_call in response:
fire(on_tool_start, agent, tool)
result = execute_tool(tool_call)
fire(on_tool_end, agent, tool, result)
if handoff:
fire(on_handoff, from_agent, to_agent)
fire(on_agent_end, agent, output)
The key design decisions are:
- Two scopes: Global (RunHooks) vs per-agent (AgentHooks) to balance breadth and specificity.
- Async callbacks: All hooks are async to support non-blocking I/O (e.g., writing to external systems).
- Context propagation: Hook callbacks receive `RunContextWrapper` or `AgentHookContext` which carry cumulative usage data and turn input.