Source: Lifecycle hooks reference (OpenAI Agents SDK, Python)
API reference for RunHooks and AgentHooks in the OpenAI Agents SDK: observational callbacks for agent, LLM, tool and handoff events that return None.
Contents
- What: official API reference page (Python SDK)
- Author: OpenAI
- Date: undated living docs (read 2026-11-14)
- Original: https://openai.github.io/openai-agents-python/ref/lifecycle/
Summary
The SDK has two lifecycle hook classes. RunHooks receives callbacks for every agent in a run; AgentHooks is attached to one agent. Every method is async and returns None, and the reference documents no mechanism for a hook to change or cancel what happens. Control in this SDK lives in guardrails instead.
Key claims
RunHooksmethods:on_agent_start,on_agent_end,on_llm_start,on_llm_end,on_tool_start,on_tool_end,on_handoff(from_agent, to_agent).AgentHooksmethods:on_start,on_end,on_llm_start,on_llm_end,on_tool_start,on_tool_end,on_handoff(agent, source).on_llm_startreceives the system prompt and input items;on_tool_endreceives the tool result;on_agent_endreceives the output.- All methods return
None; descriptions are observational (“called before/after”), with no documented return value for blocking or rewriting.