Tapping into Agent Workflows with RunHooks & AgentHooks

Introduction & Context

In the previous lesson, you learned how to securely inject sensitive data into your agent workflows using the RunContextWrapper . Now it's time to take your agent control skills to the next level by learning how to monitor and control the entire lifecycle of your agent workflows using lifecycle hooks . When you build real-world AI applications, you need visibility into what your agents are doing. You might want to know when agents start and stop, which tools they're using, when handoffs occur between agents, and how long different operations take. This kind of observability is crucial for debugging, performance monitoring, compliance logging, and understanding how your AI system behaves in production. By the end of this lesson, you will be able to create and attach both types of hooks to an agent system, giving you comprehensive control over your agent workflows.

What Are Hooks?

Hooks are callback functions that get triggered automatically when specific events happen during your program's execution. Think of them as "event listeners" that allow you to tap into important moments in your application's lifecycle. In the context of AI agents, hooks let you monitor and control what happens during agent workflows. For example, you might want to know when an agent starts working, when it uses a tool, or when control passes from one agent to another. Instead of manually checking for these events, you can create hook functions that the SDK calls automatically at the right moments. Hooks are particularly valuable for: Logging and monitoring : Track what your agents are doing in real-time Performance measurement : Time how long different operations take Dynamic configuration : Inject data or modify behavior based on runtime conditions Error handling : Detect and respond to issues as they occur Compliance : Maintain detailed audit trails for regulatory requirements Now let's explore how the OpenAI Agents SDK implements this concept with two specialized hook types.

RunHooks & AgentHooks

The OpenAI Agents SDK provides two main types of hooks: RunHooks for monitoring the entire workflow across all agents and AgentHooks for controlling specific agent behaviors. Understanding when and how to use each type is essential for building robust agent systems. Hook Type Scope Attachment Point Best For RunHooks Global (all agents) Runner.run(hooks=...) System-wide monitoring, logging, analytics AgentHooks Per-agent (specific) agent.hooks = ... Agent-specific setup, context injection RunHooks are global lifecycle callbacks that monitor events across your entire agent workflow. When you attach RunHooks to a run, they receive notifications about everything that happens during that run, regardless of which specific agent is active. This makes them perfect for system-wide monitoring and compliance logging. AgentHooks, on the other hand, are per-agent callbacks that focus on events specific to a particular agent. When you attach AgentHooks to an agent, those hooks only receive notifications about events involving that specific agent. This makes them ideal for agent-specific customization and behavior modification. These two hook types work together seamlessly. You might use RunHooks to maintain a global log of all system activities while simultaneously using AgentHooks to perform specialized setup tasks for specific agents.

Hook Type	Scope	Attachment Point	Best For
RunHooks	Global (all agents)	`Runner.run(hooks=...)`	System-wide monitoring, logging, analytics
AgentHooks	Per-agent (specific)	`agent.hooks = ...`	Agent-specific setup, context injection

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Creating RunHooks for Global Workflow Monitoring

Method	Signature	When It Fires
on_agent_start	`async def on_agent_start(context, agent)`	Before any agent is invoked (each time the runner switches agents)
on_agent_end	`async def on_agent_end(context, agent, output)`	After any agent produces its final output
on_handoff	`async def on_handoff(context, from_agent, to_agent)`	When one agent hands off to another
on_tool_start	`async def on_tool_start(context, agent, tool)`	Before any agent calls a tool
on_tool_end	`async def on_tool_end(context, agent, tool, result)`	After any agent receives a tool's result

Method	Signature	When It Fires
on_start	`async def on_start(context, agent)`	Before this agent is invoked
on_end	`async def on_end(context, agent, output)`	After this agent produces its final output
on_handoff	`async def on_handoff(context, agent, source)`	When this agent is the target of a handoff (source is the handing-off agent)
on_tool_start	`async def on_tool_start(context, agent, tool)`	Before this agent calls a tool
on_tool_end	`async def on_tool_end(context, agent, tool, result)`	After this agent receives a tool's result

Let's implement a practical example of RunHooks that provides comprehensive monitoring across your entire agent workflow. You'll create a GlobalHooks class that extends RunHooks and implements several key monitoring methods.

Python

from agents.lifecycle import RunHooks

class GlobalHooks(RunHooks):
    # Called when any agent starts
    async def on_agent_start(self, context, agent):
        print(f"[GLOBAL] {agent.name} agent starting")

    # Called when any tool finishes execution
    async def on_tool_end(self, context, agent, tool, result):
        print(f"[GLOBAL] {agent.name} -> {tool.name} returned: {result}")

    # Called when a handoff occurs between agents
    async def on_handoff(self, context, from_agent, to_agent):
        print(f"[GLOBAL] {from_agent.name} handed to {to_agent.name}")

from agents.lifecycle import RunHooks

class GlobalHooks(RunHooks):
    # Called when any agent starts
    async def on_agent_start(self, context, agent):
        print(f"[GLOBAL] {agent.name} agent starting")

    # Called when any tool finishes execution
    async def on_tool_end(self, context, agent, tool, result):
        print(f"[GLOBAL] {agent.name} -> {tool.name} returned: {result}")

    # Called when a handoff occurs between agents
    async def on_handoff(self, context, from_agent, to_agent):
        print(f"[GLOBAL] {from_agent.name} handed to {to_agent.name}")

This GlobalHooks class demonstrates three essential monitoring capabilities:

Agent tracking: The on_agent_start method logs whenever any agent in your system becomes active using the agent.name property
Tool monitoring: The on_tool_end method captures tool execution results by accessing the tool.name and the actual result returned by the tool
Handoff visibility: The on_handoff method tracks transitions between agents using both the from_agent.name and to_agent.name properties

Each method receives a context parameter (the same RunContextWrapper you learned about in the previous lesson) plus parameters specific to the event being monitored, giving you complete visibility into your agent system's behavior.

Creating AgentHooks for Per-Agent Control

While RunHooks provide excellent global monitoring, AgentHooks give you fine-grained control over individual agent behavior. Let's implement a TravelGenieHooks class that demonstrates dynamic context injection.

Imagine you have a function that returns up-to-date data:

Python

# Function to simulate fetching latest user data
def fetch_user_data():
    return UserData(name="Alice Smith", passport_number="P123456789")

# Function to simulate fetching latest user data
def fetch_user_data():
    return UserData(name="Alice Smith", passport_number="P123456789")

Now you can create agent hooks that inject this fresh data dynamically:

Python

from agents.lifecycle import AgentHooks

class TravelGenieHooks(AgentHooks):
    # Called when Travel Genie starts
    async def on_start(self, context, agent):
        # Inject user data into context
        context.context = fetch_user_data()
    
    # Called when Travel Genie finishes
    async def on_end(self, context, agent, output):
        print(f"[AGENT] {agent.name} completed with output:\n{output}")

from agents.lifecycle import AgentHooks

class TravelGenieHooks(AgentHooks):
    # Called when Travel Genie starts
    async def on_start(self, context, agent):
        # Inject user data into context
        context.context = fetch_user_data()
    
    # Called when Travel Genie finishes
    async def on_end(self, context, agent, output):
        print(f"[AGENT] {agent.name} completed with output:\n{output}")

This TravelGenieHooks class showcases two key agent-specific capabilities:

Dynamic context injection: The on_start method injects fresh user data into the context just before the agent starts processing, ensuring you always have the most up-to-date data
Agent completion tracking: The on_end method captures and logs what the agent accomplished, providing visibility into the agent's results at the individual agent level

Instead of passing sensitive data to Runner.run(context=your_data), you can inject context dynamically when a specific agent becomes active. The on_start method is called every time the Travel Genie agent becomes active, and by setting context.context = fetch_user_data(), you're providing agent-specific context injection that ensures data freshness and separation of concerns.

Attaching Hooks to Agents and Runs

Now let's see how to properly attach both types of hooks to your workflow. For AgentHooks, you attach them directly to individual agents during creation:

Python

from agents import ModelSettings

# Travel Genie agent with agent hooks
travel_genie = Agent(
    name="Travel Genie",
    instructions=(
        "You are Travel Genie, a friendly and knowledgeable travel assistant. "
        "Always use the available tools to help users plan their trips, such "
        "as booking hotels. Whenever you complete a booking or reservation, "
        "be sure to provide the user with all relevant confirmation details."
    ),
    tools=[book_hotel],
    model="gpt-5.6-terra",
    model_settings=ModelSettings(reasoning={"effort": "none"}),
    hooks=TravelGenieHooks()  # Attach agent hooks  
)

from agents import ModelSettings

# Travel Genie agent with agent hooks
travel_genie = Agent(
    name="Travel Genie",
    instructions=(
        "You are Travel Genie, a friendly and knowledgeable travel assistant. "
        "Always use the available tools to help users plan their trips, such "
        "as booking hotels. Whenever you complete a booking or reservation, "
        "be sure to provide the user with all relevant confirmation details."
    ),
    tools=[book_hotel],
    model="gpt-5.6-terra",
    model_settings=ModelSettings(reasoning={"effort": "none"}),
    hooks=TravelGenieHooks()  # Attach agent hooks  
)

For RunHooks, you attach them to the entire run by passing them to the Runner.run() method:

Python

async def main():
    # Run the agent with global hooks
    result = await Runner.run(
        starting_agent=triage,
        input="Please book me a room at the Grand Plaza Hotel.",
        hooks=GlobalHooks()  # Attach run hooks
    )

async def main():
    # Run the agent with global hooks
    result = await Runner.run(
        starting_agent=triage,
        input="Please book me a room at the Grand Plaza Hotel.",
        hooks=GlobalHooks()  # Attach run hooks
    )

The SDK automatically coordinates both types of hooks during execution, ensuring that your hooks are called at the right times with the right parameters.

Observing Hook Output

When you run a workflow with both types of hooks attached, you'll see comprehensive monitoring output that shows the complete lifecycle of your agent system:

text

[GLOBAL] Travel Triage agent starting
[GLOBAL] Travel Triage handed to Travel Genie
[GLOBAL] Travel Genie agent starting
[GLOBAL] Travel Genie -> book_hotel returned: {'hotel_name': 'Grand Plaza Hotel', 'guest_name': 'Alice Smith', 'confirmation_success': True, 'confirmation_id': '9f806071-df6e-4a42-a184-baaabb93d1ea'}
[AGENT] Travel Genie completed with output:
Your room at the Grand Plaza Hotel has been successfully booked!

Here are your booking details:
- Hotel: Grand Plaza Hotel
- Guest Name: Alice Smith
- Confirmation ID: 9f806071-df6e-4a42-a184-baaabb93d1ea

If you need more details or want to update anything about your reservation, just let me know! Safe travels!
Final output:
Your room at the Grand Plaza Hotel has been successfully booked!

Here are your booking details:
- Hotel: Grand Plaza Hotel
- Guest Name: Alice Smith
- Confirmation ID: 9f806071-df6e-4a42-a184-baaabb93d1ea

If you need more details or want to update anything about your reservation, just let me know! Safe travels!

[GLOBAL] Travel Triage agent starting
[GLOBAL] Travel Triage handed to Travel Genie
[GLOBAL] Travel Genie agent starting
[GLOBAL] Travel Genie -> book_hotel returned: {'hotel_name': 'Grand Plaza Hotel', 'guest_name': 'Alice Smith', 'confirmation_success': True, 'confirmation_id': '9f806071-df6e-4a42-a184-baaabb93d1ea'}
[AGENT] Travel Genie completed with output:
Your room at the Grand Plaza Hotel has been successfully booked!

Here are your booking details:
- Hotel: Grand Plaza Hotel
- Guest Name: Alice Smith
- Confirmation ID: 9f806071-df6e-4a42-a184-baaabb93d1ea

If you need more details or want to update anything about your reservation, just let me know! Safe travels!
Final output:
Your room at the Grand Plaza Hotel has been successfully booked!

Here are your booking details:
- Hotel: Grand Plaza Hotel
- Guest Name: Alice Smith
- Confirmation ID: 9f806071-df6e-4a42-a184-baaabb93d1ea

If you need more details or want to update anything about your reservation, just let me know! Safe travels!

This output demonstrates how the hooks capture the complete flow: the triage agent starting, the handoff to Travel Genie, Travel Genie starting (with context injection happening automatically), the tool execution result, and finally the agent's completion output. This gives you real-time visibility into your agent system's behavior, which is essential for production deployments, debugging complex workflows, and understanding how your agents interact with each other and external tools.

Introduction & Context

What Are Hooks?

RunHooks & AgentHooks

Join the 1M+ learners on CodeSignal

RunHooks: Global Workflow Monitoring

AgentHooks: Per-Agent Control

How Context Works with Hooks

Creating RunHooks for Global Workflow Monitoring

Creating AgentHooks for Per-Agent Control

Attaching Hooks to Agents and Runs

Observing Hook Output

Summary & Next Steps