Inkdown
Start writing

OpenAI Agents Python

21 filesยท0 subfolders

Shared Workspace

OpenAI Agents Python
00_OVERVIEW.md

12_CONTEXT

Shared from "OpenAI Agents Python" on Inkdown

Context - Comprehensive Deep Dive

Overview

Context in the OpenAI Agents SDK is a powerful mechanism for sharing state across tool calls, guardrails, handoffs, and lifecycle hooks. Think of Context as a "shared workspace" or "carrying case" that travels with the agent run, allowing you to pass custom data, configuration, and state to various components without relying on global variables or complex threading mechanisms.

Core Concepts

What is Context?

Context is a user-defined object that:

  • Carries custom data throughout an agent run
  • Is accessible from tools, guardrails, handoffs, and hooks
  • Is mutable - can be modified during execution
  • Is type-safe - uses generics for compile-time checking
  • Is isolated - each run has its own context instance
Why Context Matters
  1. - Share data across tool calls without globals
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
State Sharing
  • Configuration - Pass configuration to tools and guardrails
  • User Data - Track user-specific information
  • Session Data - Maintain session-specific state
  • Business Logic - Implement custom business rules
  • Type Safety - Ensure data consistency with types

    • Context Basics

    Defining Context

    Context is typically a dataclass:

    Python
    Using Context

    Pass context when running an agent:

    Python
    Context in Tools

    Tools can access context:

    Python

    RunContextWrapper

    RunContextWrapper Class

    RunContextWrapper wraps the context and provides additional functionality:

    Python
    Accessing Context
    Python

    ToolContext

    ToolContext Class

    ToolContext extends RunContextWrapper with tool-specific metadata:

    Python
    Using ToolContext
    Python

    Context and Generics

    Generic Context

    Agents are generic over context type:

    Python
    Type Safety

    Generics provide compile-time type checking:

    Python
    Context Inference

    Type inference works in many cases:

    Python

    Context Patterns

    1. User Session Context

    Track user-specific data:

    Python
    2. Database Context

    Pass database connection:

    Python
    3. API Client Context

    Pass API clients:

    Python
    4. Configuration Context

    Pass configuration:

    Python
    5. Accumulator Context

    Accumulate results across tool calls:

    Python

    Context Mutability

    Modifying Context

    Context is mutable:

    Python
    Thread Safety Considerations

    Context is not thread-safe by default:

    Python

    Context and Guardrails

    Input Guardrails with Context
    Python
    Output Guardrails with Context
    Python

    Context and Handoffs

    Handoff Functions with Context
    Python
    Handoff Input Filter with Context
    Python

    Context and Lifecycle Hooks

    Run Hooks with Context
    Python
    Agent Hooks with Context
    Python

    Context and Tool Approvals

    Approval Decisions with Context
    Python
    Custom Approval Logic
    Python

    Context and Usage Tracking

    Accessing Usage
    Python
    Context-Based Usage Limits
    Python

    Context and RunConfig

    Accessing RunConfig
    Python
    Context-Based Configuration
    Python

    Context and RunState

    Context in RunState

    RunState includes context:

    Python
    Context Serialization

    Context requires serializers for RunState:

    Python

    Context Best Practices

    1. Use Dataclasses

    Use dataclasses for context:

    Python
    2. Keep Context Focused

    Keep context focused on relevant data:

    Python
    3. Use Type Hints

    Always use type hints:

    Python
    4. Document Context Fields

    Document context fields:

    Python
    5. Avoid Circular Dependencies

    Avoid circular references in context:

    Python

    Common Context Patterns

    1. Request Context

    Track request-specific data:

    Python
    2. Multi-Tenant Context

    Handle multi-tenant applications:

    Python
    3. Audit Context

    Track audit information:

    Python
    4. Cache Context

    Implement caching:

    Python
    5. State Machine Context

    Implement state machine:

    Python

    Context and Testing

    Mock Context for Testing
    Python
    Context Fixtures

    Use fixtures for common contexts:

    Python

    Summary

    Context enables state sharing across agent runs. Key takeaways:

    1. Context is a user-defined object for state sharing
    2. RunContextWrapper wraps context with additional functionality
    3. ToolContext extends RunContextWrapper with tool metadata
    4. Generics provide type safety
    5. Dataclasses are the recommended context type
    6. Mutability allows context modification during runs
    7. Tools can access context via RunContextWrapper
    8. Guardrails can use context for validation
    9. Handoffs can access context during delegation
    10. Lifecycle hooks receive context in callbacks
    11. Approvals can use context for decisions
    12. Usage tracking is available in context
    13. RunConfig is accessible from context
    14. RunState includes context for serialization
    15. Serialization requires custom serializers for complex context
    16. Type hints ensure type safety
    17. Documentation helps understand context fields
    18. Focused context avoids bloat
    19. Testing with mock contexts
    20. Patterns exist for common use cases

    Context is essential for building stateful, configurable, and type-safe agent workflows.