Agent Lifecycle Hooks
Description: Learn how to track agent lifecycle events with custom hooks - see agents start, end, hand off, and use tools
Difficulty: beginner
Category: getting-started
Python Code Example
import asyncio
import random
from typing import Any
from pydantic import BaseModel
from agents import Agent, AgentHooks, RunContextWrapper, Runner, Tool, function_tool
class CustomAgentHooks(AgentHooks):
def __init__(self, display_name: str):
self.event_counter = 0
self.display_name = display_name
async def on_start(self, context: RunContextWrapper, agent: Agent) -> None:
self.event_counter += 1
print(f"### ({self.display_name}) {self.event_counter}: Agent {agent.name} started")
async def on_end(self, context: RunContextWrapper, agent: Agent, output: Any) -> None:
self.event_counter += 1
print(
f"### ({self.display_name}) {self.event_counter}: Agent {agent.name} ended with output {output}"
)
async def on_handoff(self, context: RunContextWrapper, agent: Agent, source: Agent) -> None:
self.event_counter += 1
print(
f"### ({self.display_name}) {self.event_counter}: Agent {source.name} handed off to {agent.name}"
)
async def on_tool_start(self, context: RunContextWrapper, agent: Agent, tool: Tool) -> None:
self.event_counter += 1
print(
f"### ({self.display_name}) {self.event_counter}: Agent {agent.name} started tool {tool.name}"
)
async def on_tool_end(
self, context: RunContextWrapper, agent: Agent, tool: Tool, result: str
) -> None:
self.event_counter += 1
print(
f"### ({self.display_name}) {self.event_counter}: Agent {agent.name} ended tool {tool.name} with result {result}"
)
@function_tool
def random_number(max: int) -> int:
"""
Generate a random number from 0 to max (inclusive).
"""
return random.randint(0, max)
@function_tool
def multiply_by_two(x: int) -> int:
"""Simple multiplication by two."""
return x * 2
class FinalResult(BaseModel):
number: int
multiply_agent = Agent(
name="Multiply Agent",
instructions="Multiply the number by 2 and then return the final result.",
tools=[multiply_by_two],
output_type=FinalResult,
hooks=CustomAgentHooks(display_name="Multiply Agent"),
)
start_agent = Agent(
name="Start Agent",
instructions="Generate a random number. If it's even, stop. If it's odd, hand off to the multiply agent.",
tools=[random_number],
output_type=FinalResult,
handoffs=[multiply_agent],
hooks=CustomAgentHooks(display_name="Start Agent"),
)
async def main():
max_number = 250
print(f"Generating a random number between 0 and {max_number}...")
result = await Runner.run(
start_agent,
input=f"Generate a random number between 0 and {max_number}.",
)
print("\nDone!")
print(f"Final result: {result.final_output}")
if __name__ == "__main__":
asyncio.run(main())
Expected Output: Agent lifecycle events tracked through custom hooks
About This Example
This is an interactive Python tutorial for the OpenAI Agents SDK. The code runs directly in your browser using PyOdide (Python in WebAssembly).
Key Features:
- No installation required - runs entirely in your browser
- Interactive code editor with syntax highlighting
- Real-time execution using PyOdide
- Complete OpenAI Agents SDK functionality
- Connect with GitHub Models for AI capabilities
Related Examples:
- Hello World - Your first AI agent - a simple agent that responds in haikus
← Back to all examples
JavaScript is required to run the interactive code editor. Please enable JavaScript in your browser for the full experience.