Inkdown
Start writing

OpenAI Agents Python

21 filesยท0 subfolders

Shared Workspace

OpenAI Agents Python
00_OVERVIEW.md

13_LIFECYCLE_HOOKS

Shared from "OpenAI Agents Python" on Inkdown

Lifecycle Hooks - Comprehensive Deep Dive

Overview

Lifecycle Hooks in the OpenAI Agents SDK allow you to execute custom code at specific points during an agent run. Think of Lifecycle Hooks as "event listeners" or "callbacks" that let you hook into the execution flow - you can run custom logic when an agent starts, when a tool is called, when the LLM generates a response, and more. This is essential for logging, monitoring, custom business logic, and extending agent behavior.

Core Concepts

What are Lifecycle Hooks?

Lifecycle Hooks are functions that are called at specific points during agent execution:

  • Agent lifecycle - When an agent starts or ends
  • LLM lifecycle - Before and after LLM calls
  • Tool lifecycle - Before and after tool execution
  • Handoff lifecycle - When agents hand off to each other
Why Lifecycle Hooks Matter
01_AGENT_SYSTEM.md
02_RUNNER_SYSTEM.md
03_TOOL_SYSTEM.md
04_ITEMS_SYSTEM.md
05_GUARDRAILS.md
06_HANDOFFS.md
07_MEMORY_SESSIONS.md
08_MODEL_PROVIDERS.md
09_SANDBOX_SYSTEM.md
10_TRACING.md
11_RUN_STATE.md
12_CONTEXT.md
13_LIFECYCLE_HOOKS.md
14_CONFIGURATION.md
15_ERROR_HANDLING.md
16_STREAMING.md
17_EXTENSIONS.md
18_MCP_INTEGRATION.md
19_BEST_PRACTICES.md
20_ARCHITECTURE_PATTERNS.md
  • Logging - Log events for monitoring and debugging
  • Monitoring - Track agent behavior and performance
  • Custom Logic - Implement business rules at specific points
  • Analytics - Collect data on agent usage
  • Validation - Add custom validation at key points
  • Extension - Extend agent behavior without modifying core code

    • Hook Types

    Run Hooks

    RunHooks are called for the entire run, across all agents:

    Python

    When to use:

    • Global logging for all agents
    • Cross-agent monitoring
    • Run-level analytics
    • Global business logic
    Agent Hooks

    AgentHooks are called for a specific agent:

    Python

    When to use:

    • Agent-specific logging
    • Per-agent monitoring
    • Agent-specific business logic
    • Custom agent behavior

    Run Hooks Methods

    on_agent_start

    Called when an agent starts (any agent in the run):

    Python

    Use cases:

    • Log agent starts
    • Initialize agent-specific state
    • Track agent usage
    • Validate agent configuration
    on_agent_end

    Called when an agent produces a final output:

    Python

    Use cases:

    • Log agent outputs
    • Track agent performance
    • Validate output
    • Trigger follow-up actions
    on_handoff

    Called when a handoff occurs:

    Python

    Use cases:

    • Log handoffs
    • Track handoff patterns
    • Validate handoffs
    • Trigger handoff-specific logic
    on_llm_start

    Called just before invoking the LLM:

    Python

    Use cases:

    • Log LLM calls
    • Track prompt usage
    • Validate prompts
    • Modify prompts (with care)
    on_llm_end

    Called immediately after the LLM call returns:

    Python

    Use cases:

    • Log LLM responses
    • Track token usage
    • Validate responses
    • Analyze model behavior
    on_tool_start

    Called immediately before a local tool is invoked:

    Python

    Use cases:

    • Log tool calls
    • Track tool usage
    • Validate tool inputs
    • Modify tool inputs (with care)
    on_tool_end

    Called immediately after a local tool is invoked:

    Python

    Use cases:

    • Log tool results
    • Track tool performance
    • Validate tool outputs
    • Analyze tool behavior

    Agent Hooks Methods

    on_start

    Called when this specific agent starts:

    Python

    Use cases:

    • Agent-specific initialization
    • Agent-specific logging
    • Validate agent state
    • Load agent-specific resources
    on_end

    Called when this specific agent produces a final output:

    Python

    Use cases:

    • Agent-specific cleanup
    • Agent-specific output processing
    • Save agent-specific state
    • Trigger agent-specific follow-ups
    on_handoff

    Called when the agent is being handed off to:

    Python

    Use cases:

    • Log handoff reception
    • Prepare agent for handoff
    • Validate handoff context
    • Initialize agent state
    on_tool_start

    Called immediately before a local tool is invoked:

    Python

    Use cases:

    • Agent-specific tool logging
    • Track tool usage by agent
    • Agent-specific tool validation
    on_tool_end

    Called immediately after a local tool is invoked:

    Python

    Use cases:

    • Agent-specific tool result logging
    • Track tool performance by agent
    • Agent-specific tool result validation
    on_llm_start

    Called immediately before the agent issues an LLM call:

    Python

    Use cases:

    • Agent-specific LLM logging
    • Track LLM usage by agent
    • Agent-specific prompt validation
    on_llm_end

    Called immediately after the agent receives the LLM response:

    Python

    Use cases:

    • Agent-specific LLM response logging
    • Track LLM performance by agent
    • Agent-specific response validation

    Using Run Hooks

    Setting Run Hooks

    Set hooks when running an agent:

    Python
    Run Hooks with Context

    Run hooks have access to context:

    Python
    Run Hooks with RunConfig

    Hooks can be set in RunConfig:

    Python

    Using Agent Hooks

    Setting Agent Hooks

    Set hooks on an agent:

    Python
    Agent Hooks with Context

    Agent hooks have access to context:

    Python

    Hook Context Types

    AgentHookContext

    Context for agent lifecycle hooks:

    Python
    RunContextWrapper

    Context for run-level hooks:

    Python

    Hook Execution Order

    Complete Hook Order

    Hooks execute in this order:

    Plain text

    Hook Best Practices

    1. Keep Hooks Fast

    Hooks should be fast to avoid slowing down execution:

    Python
    2. Handle Errors Gracefully

    Hooks should handle errors without breaking execution:

    Python
    3. Use Hooks for Cross-Cutting Concerns

    Use hooks for cross-cutting concerns:

    Python
    4. Don't Modify Critical State

    Avoid modifying critical state in hooks:

    Python
    5. Document Hook Behavior

    Document what hooks do:

    Python

    Common Hook Patterns

    1. Logging Hook

    Comprehensive logging:

    Python
    2. Monitoring Hook

    Performance monitoring:

    Python
    3. Analytics Hook

    Usage analytics:

    Python
    4. Validation Hook

    Custom validation:

    Python
    5. State Tracking Hook

    Track state across execution:

    Python

    Hooks and Tracing

    Hooks Create Trace Spans

    Hooks automatically create trace spans:

    Python
    Custom Spans in Hooks

    Create custom spans in hooks:

    Python

    Hooks and Context

    Accessing Context in Hooks

    Hooks have access to context:

    Python
    Modifying Context in Hooks

    Context can be modified in hooks (with caution):

    Python

    Hooks and Errors

    Error Handling in Hooks

    Errors in hooks are logged but don't break execution:

    Python
    Hook Error Propagation

    Some errors might propagate:

    Python

    Hooks and Testing

    Testing Hooks

    Test hooks independently:

    Python
    Mock Hooks for Testing

    Use mock hooks in tests:

    Python

    Hooks Performance

    Hook Overhead

    Hooks add minimal overhead:

    Python
    Optimizing Hooks

    Optimize hooks for performance:

    Python

    Summary

    Lifecycle Hooks enable custom logic at execution points. Key takeaways:

    1. RunHooks apply to the entire run
    2. AgentHooks apply to specific agents
    3. on_agent_start/end track agent lifecycle
    4. on_handoff tracks agent delegation
    5. on_llm_start/end track LLM calls
    6. on_tool_start/end track tool execution
    7. Hook context provides execution information
    8. AgentHookContext for agent-level hooks
    9. RunContextWrapper for run-level hooks
    10. Execution order is predictable
    11. Keep hooks fast to avoid slowdowns
    12. Handle errors gracefully in hooks
    13. Use hooks for cross-cutting concerns
    14. Don't modify critical state in hooks
    15. Document hook behavior clearly
    16. Logging hooks for observability
    17. Monitoring hooks for performance
    18. Analytics hooks for usage tracking
    19. Validation hooks for custom checks
    20. State tracking hooks for execution tracking

    Lifecycle Hooks are essential for extending agent behavior without modifying core code.