Lifecycle hooks are async callback methods that fire at key agent and tool execution points—define them by subclassing RunHooksBase (for run-wide events) or AgentHooksBase (for agent-specific events) and override only the events you need to observe. The SDK distinguishes run-level hooks that track all agent transitions and tool calls from agent-level hooks scoped to a single agent; handoff callbacks are routed to the receiving agent, not the initiator.
src/agents/lifecycle.py defines RunHooksBase and AgentHooksBase as the two base classes for lifecycle event callbacks; RunHooks and AgentHooks are concrete type aliases specialised for Agent.[1]
RunHooksBase is a run-level hook class whose callbacks — on_llm_start, on_llm_end, on_agent_start, on_agent_end, on_handoff, on_tool_start, and on_tool_end — are all async no-ops by default; subclass and override only the methods you need.[1] RunHooksBase.on_agent_start is called each time the current agent changes, not only at the beginning of the overall run.[1]
AgentHooksBase carries the same event set as RunHooksBase but is attached to a specific agent via agent.hooks, scoping its callbacks to that agent only.[1] AgentHooksBase.on_handoff is called on the receiving agent when it is being handed off to; the source parameter is the agent initiating the handoff.[1]
For function-tool invocations, the context argument passed to on_tool_start and on_tool_end is typically a ToolContext instance exposing tool_call_id, tool_name, and tool_arguments; other local tool families may receive a plain RunContextWrapper instead.[1] The result argument delivered to on_tool_end is typically a str for simple tools; function tools may also return structured output objects or any value the SDK can stringify before sending it to the model.[1]
Sources