InkdownInkdown
Start writing

OpenAI Agents Python

21 filesยท0 subfolders

Shared Workspace

OpenAI Agents Python
00_OVERVIEW.md

14_CONFIGURATION

Shared from "OpenAI Agents Python" on Inkdown

Configuration - Comprehensive Deep Dive

Overview

Configuration in the OpenAI Agents SDK controls how agents and runs behave. Think of Configuration as "settings" or "preferences" that you can set at different levels - globally, per-run, or per-agent. These settings control everything from which model to use to how many turns are allowed, from tracing behavior to sandbox configuration.

Core Concepts

Configuration Hierarchy

Configuration flows from most specific to most general:

  1. Agent-level - Settings on the Agent instance (highest priority)
  2. RunConfig-level - Settings for a specific run
  3. Global defaults - Default settings for the SDK (lowest priority)

This means:

  • Agent settings override RunConfig settings
  • RunConfig settings override global defaults
  • If not set, the next level down is used
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
Why Configuration Matters
  1. Flexibility - Adjust behavior without code changes
  2. Environment Differences - Different settings for dev/staging/prod
  3. A/B Testing - Test different configurations
  4. Cost Control - Manage token usage and costs
  5. Safety - Configure guardrails and approvals
  6. Performance - Optimize for speed or quality

RunConfig

RunConfig Overview

RunConfig is the main configuration class for agent runs:

Python
from agents import RunConfig

config = RunConfig(
    model="gpt-4o",
    model_settings=ModelSettings(temperature=0.7),
    max_turns=20,
    tracing_disabled=False,
    workflow_name="My workflow",
)
Model Configuration
Model Selection
Python
config = RunConfig(
    model="gpt-4o",  # Override all agents' models
)

When to use:

  • Force a specific model for all agents
  • Test different models without changing agent code
  • A/B test models
Model Provider
Python
from agents import MultiProvider, OpenAIProvider

config = RunConfig(
    model_provider=MultiProvider([
        OpenAIProvider(),
        AnthropicProvider(),
    ]),
)

When to use:

  • Use multiple model providers
  • Provide fallback providers
  • Test different providers
Model Settings
Python
from agents import ModelSettings

config = RunConfig(
    model_settings=ModelSettings(
        temperature=0.7,
        top_p=0.9,
        max_tokens=1000,
    ),
)

When to use:

  • Set global model parameters
  • Override agent-specific settings
  • Tune model behavior
Handoff Configuration
Handoff Input Filter
Python
def filter_handoff_input(data: HandoffInputData) -> HandoffInputData:
    """Filter input passed to next agent."""
    return data.clone(new_items=data.new_items[-5:])

config = RunConfig(
    handoff_input_filter=filter_handoff_input,
)

When to use:

  • Control what information is passed between agents
  • Reduce token usage in handoffs
  • Filter sensitive information
Nested Handoff History
Python
config = RunConfig(
    nest_handoff_history=True,  # Collapse history
)

When to use:

  • Reduce token usage in deep handoff chains
  • Simplify context for nested agents
  • Optimize for long conversations
Handoff History Mapper
Python
def custom_mapper(history: list) -> list:
    """Custom history transformation."""
    return [item for item in history if item["role"] in ["user", "assistant"]]

config = RunConfig(
    handoff_history_mapper=custom_mapper,
)

When to use:

  • Custom history transformation
  • Filter specific message types
  • Add summary messages
Guardrail Configuration
Input Guardrails
Python
from agents import input_guardrail

@input_guardrail
def global_input_check(context, agent, input):
    """Global input guardrail."""
    return GuardrailFunctionOutput(
        output_info="Valid",
        tripwire_triggered=False,
    )

config = RunConfig(
    input_guardrails=[global_input_check],
)

When to use:

  • Apply guardrails to all agents
  • Global safety checks
  • Global validation rules
Output Guardrails
Python
from agents import output_guardrail

@output_guardrail
def global_output_check(context, agent, output):
    """Global output guardrail."""
    return GuardrailFunctionOutput(
        output_info="Valid",
        tripwire_triggered=False,
    )

config = RunConfig(
    output_guardrails=[global_output_check],
)

When to use:

  • Apply output validation to all agents
  • Global safety checks
  • Global formatting rules
Tracing Configuration
Disable Tracing
Python
config = RunConfig(
    tracing_disabled=True,  # Disable tracing
)

When to use:

  • Improve performance
  • Reduce overhead
  • Privacy requirements
Tracing Config
Python
from agents import TracingConfig

config = RunConfig(
    tracing=TracingConfig(
        disabled=False,
        include_sensitive_data=False,
    ),
)

When to use:

  • Fine-grained tracing control
  • Custom tracing behavior
  • Integration with tracing systems
Sensitive Data
Python
config = RunConfig(
    trace_include_sensitive_data=False,  # Exclude sensitive data
)

When to use:

  • Privacy compliance
  • Security requirements
  • Reduce trace size
Workflow Name
Python
config = RunConfig(
    workflow_name="Customer Support Workflow",
)

When to use:

  • Identify runs in traces
  • Organize traces by workflow
  • Analytics and reporting
Trace ID
Python
config = RunConfig(
    trace_id="custom-trace-id-123",
)

When to use:

  • Link to external systems
  • Custom trace identification
  • Distributed tracing
Group ID
Python
config = RunConfig(
    group_id="conversation-123",
)

When to use:

  • Link related traces
  • Group traces by conversation
  • User-level tracking
Trace Metadata
Python
config = RunConfig(
    trace_metadata={
        "user_id": "user-123",
        "environment": "production",
    },
)

When to use:

  • Add custom metadata
  • Filter traces by metadata
  • Analytics integration
Session Configuration
Session Settings
Python
from agents import SessionSettings

config = RunConfig(
    session_settings=SessionSettings(
        max_items=50,
        compaction_enabled=True,
    ),
)

When to use:

  • Control session behavior
  • Manage conversation history
  • Optimize token usage
Session Input Callback
Python
def custom_input_callback(history, new_input):
    """Custom input combination logic."""
    return history[-10:] + [new_input]

config = RunConfig(
    session_input_callback=custom_input_callback,
)

When to use:

  • Custom history combination
  • Special input processing
  • Context window management
Model Input Filter
Call Model Input Filter
Python
from agents import CallModelInputFilter, ModelInputData

def filter_model_input(data: CallModelInputData) -> ModelInputData:
    """Filter input before model call."""
    # Modify input
    return data

config = RunConfig(
    call_model_input_filter=filter_model_input,
)

When to use:

  • Modify input before model call
  • Stay within token limits
  • Add system prompts dynamically
  • Filter sensitive information
Tool Configuration
Tool Error Formatter
Python
from agents import ToolErrorFormatter

def custom_error_formatter(args) -> str:
    """Custom error formatting."""
    return f"Custom error: {args.tool_name} failed"

config = RunConfig(
    tool_error_formatter=custom_error_formatter,
)

When to use:

  • Customize error messages
  • Provide user-friendly errors
  • Translate errors
Reasoning Configuration
Reasoning Item ID Policy
Python
config = RunConfig(
    reasoning_item_id_policy="omit",  # Strip reasoning IDs
)

Options:

  • None or "preserve" - Keep reasoning IDs as-is
  • "omit" - Strip reasoning IDs from model input

When to use:

  • Reduce token usage
  • Privacy for reasoning content
  • Compatibility issues
Sandbox Configuration
SandboxRunConfig
Python
from agents import SandboxRunConfig, SandboxConcurrencyLimits

config = RunConfig(
    sandbox=SandboxRunConfig(
        client=UnixLocalSandboxClient(),
        concurrency_limits=SandboxConcurrencyLimits(
            manifest_entries=4,
            local_dir_files=10,
        ),
    ),
)

When to use:

  • Configure sandbox execution
  • Set concurrency limits
  • Sandbox-specific options

Agent Configuration

Agent-Level Settings

Agents have their own configuration:

Python
from agents import Agent, ModelSettings

agent = Agent(
    name="my_agent",
    instructions="...",
    model="gpt-4o",  # Agent-specific model
    model_settings=ModelSettings(temperature=0.7),  # Agent-specific settings
    input_guardrails=[guardrail1],  # Agent-specific guardrails
    output_guardrails=[guardrail2],
    max_turns=10,  # Note: max_turns is set at run level, not agent
)
Configuration Priority

Agent settings override RunConfig:

Python
# Agent has model="gpt-4o"
agent = Agent(model="gpt-4o", ...)

# RunConfig has model="gpt-4o-mini"
config = RunConfig(model="gpt-4o-mini")

# Agent wins - uses gpt-4o
result = await Runner.run(agent, input, run_config=config)
Model Settings Merging

Model settings are merged:

Python
# Agent has temperature=0.7
agent = Agent(model_settings=ModelSettings(temperature=0.7), ...)

# RunConfig has temperature=0.5, top_p=0.9
config = RunConfig(model_settings=ModelSettings(temperature=0.5, top_p=0.9))

# Result: temperature=0.5 (RunConfig wins), top_p=0.9 (from RunConfig)

Global Configuration

Default OpenAI Key
Python
from agents import set_default_openai_key

set_default_openai_key("your-api-key")
Default OpenAI API
Python
from agents import set_default_openai_api

set_default_openai_api("responses")  # Use Responses API by default
Default Tracing
Python
from agents import set_tracing_disabled

set_tracing_disabled(True)  # Disable tracing globally
Default Agent Registration
Python
from agents import register_agent, get_agent

register_agent("my_agent", my_agent)
retrieved_agent = get_agent("my_agent")
Harness ID
Python
from agents import set_harness_id

set_harness_id("my-harness-123")
Verbose Logging
Python
from agents import enable_verbose_logging

enable_verbose_logging()

Environment Variables

OpenAI API Key
Bash
export OPENAI_API_KEY="your-api-key"
Tracing Settings
Bash
export OPENAI_AGENTS_TRACING_DISABLED="true"
export OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA="false"
Verbose Logging
Bash
export OPENAI_AGENTS_VERBOSE="true"

Configuration Patterns

1. Environment-Based Configuration

Different configs for different environments:

Python
import os

def get_config() -> RunConfig:
    """Get config based on environment."""
    env = os.getenv("ENVIRONMENT", "dev")
    
    if env == "production":
        return RunConfig(
            model="gpt-4o",
            tracing_disabled=False,
        )
    elif env == "staging":
        return RunConfig(
            model="gpt-4o-mini",
            tracing_disabled=False,
        )
    else:  # dev
        return RunConfig(
            model="gpt-4o-mini",
            tracing_disabled=True,
        )
2. User-Based Configuration

Different configs for different users:

Python
def get_config_for_user(user_tier: str) -> RunConfig:
    """Get config based on user tier."""
    if user_tier == "enterprise":
        return RunConfig(
            model="gpt-4-turbo",
            max_turns=50,
        )
    elif user_tier == "premium":
        return RunConfig(
            model="gpt-4o",
            max_turns=20,
        )
    else:  # free
        return RunConfig(
            model="gpt-4o-mini",
            max_turns=10,
        )
3. Task-Based Configuration

Different configs for different tasks:

Python
def get_config_for_task(task_type: str) -> RunConfig:
    """Get config based on task type."""
    if task_type == "complex_reasoning":
        return RunConfig(
            model="gpt-4o",
            model_settings=ModelSettings(temperature=0.1),
        )
    elif task_type == "creative_writing":
        return RunConfig(
            model="gpt-4o",
            model_settings=ModelSettings(temperature=0.9),
        )
    else:  # general
        return RunConfig(
            model="gpt-4o-mini",
            model_settings=ModelSettings(temperature=0.7),
        )
4. Cost-Optimized Configuration

Optimize for cost:

Python
def get_cost_optimized_config() -> RunConfig:
    """Get cost-optimized config."""
    return RunConfig(
        model="gpt-4o-mini",  # Cheaper model
        model_settings=ModelSettings(
            max_tokens=500,  # Limit output length
            temperature=0.3,  # More deterministic
        ),
        session_settings=SessionSettings(
            max_items=20,  # Limit history
        ),
        nest_handoff_history=True,  # Reduce tokens
    )
5. Performance-Optimized Configuration

Optimize for speed:

Python
def get_fast_config() -> RunConfig:
    """Get fast config."""
    return RunConfig(
        model="gpt-4o-mini",  # Faster model
        tracing_disabled=True,  # No tracing overhead
        session_settings=SessionSettings(
            max_items=10,  # Less history
        ),
    )

Configuration Validation

Validating RunConfig

Validate configuration before use:

Python
def validate_config(config: RunConfig) -> bool:
    """Validate RunConfig."""
    # Check model is valid
    if config.model and not is_valid_model(config.model):
        return False
    
    # Check model settings
    if config.model_settings:
        if config.model_settings.temperature < 0 or config.model_settings.temperature > 2:
            return False
    
    # Check max_turns
    if config.max_turns < 1:
        return False
    
    return True
Configuration Errors

Handle configuration errors:

Python
try:
    config = RunConfig(model="invalid-model")
    result = except Runner.run(agent, input, run_config=config)
except InvalidModelError as e:
    print(f"Invalid model: {e}")

Configuration Best Practices

1. Use Configuration Files

Store configuration in files:

Python
# config.yaml
model: "gpt-4o"
temperature: 0.7
max_turns: 20

# Load config
import yaml

with open("config.yaml") as f:
    config_data = yaml.safe_load(f)

config = RunConfig(
    model=config_data["model"],
    model_settings=ModelSettings(temperature=config_data["temperature"]),
)
2. Use Environment Variables

Use environment for sensitive data:

Python
import os

config = RunConfig(
    # Don't hardcode API keys
    # Use environment variables instead
)
3. Document Configuration

Document configuration options:

Python
# config.py
"""
Configuration for agent runs.

Environment variables:
- MODEL: Model to use (default: gpt-4o)
- TEMPERATURE: Temperature (default: 0.7)
- MAX_TURNS: Maximum turns (default: 10)
"""

def get_config() -> RunConfig:
    """Get configuration from environment."""
    return RunConfig(
        model=os.getenv("MODEL", "gpt-4o"),
        model_settings=ModelSettings(
            temperature=float(os.getenv("TEMPERATURE", "0.7")),
        ),
        max_turns=int(os.getenv("MAX_TURNS", "10")),
    )
4. Use Configuration Validation

Validate configuration early:

Python
config = get_config()

if not validate_config(config):
    raise ValueError("Invalid configuration")

result = await Runner.run(agent, input, run_config=config)
5. Keep Configuration Simple

Don't over-engineer configuration:

Python
# Good - simple config
config = RunConfig(
    model="gpt-4o",
    max_turns=10,
)

# Avoid - overly complex config
config = RunConfig(
    model="gpt-4o",
    model_settings=ModelSettings(
        temperature=0.7,
        top_p=0.9,
        max_tokens=1000,
        presence_penalty=0.0,
        frequency_penalty=0.0,
    ),
    handoff_input_filter=complex_filter,
    handoff_history_mapper=complex_mapper,
    input_guardrails=[guardrail1, guardrail2, guardrail3],
    output_guardrails=[guardrail4, guardrail5],
    tracing=TracingConfig(...),
    session_settings=SessionSettings(...),
    # ... too many options
)

Configuration and Testing

Test Configuration

Test with different configurations:

Python
@pytest.mark.asyncio
async def test_with_fast_config():
    """Test with fast configuration."""
    config = RunConfig(
        model="gpt-4o-mini",
        max_turns=5,
    )
    result = await Runner.run(agent, input, run_config=config)
    assert result.final_output is not None

@pytest.mark.asyncio
async def test_with_slow_config():
    """Test with slow configuration."""
    config = RunConfig(
        model="gpt-4o",
        max_turns=20,
    )
    result = await Runner.run(agent, input, run_config=config)
    assert result.final_output is not None
Configuration Fixtures

Use fixtures for common configurations:

Python
@pytest.fixture
def fast_config():
    """Fast configuration fixture."""
    return RunConfig(
        model="gpt-4o-mini",
        max_turns=5,
    )

@pytest.mark.asyncio
async def test_with_fixture(fast_config):
    """Test with configuration fixture."""
    result = await Runner.run(agent, input, run_config=fast_config)
    assert result.final_output is not None

Configuration and Deployment

Configuration in Production

Use production-specific configuration:

Python
# production_config.py
def get_production_config() -> RunConfig:
    """Production configuration."""
    return RunConfig(
        model="gpt-4o",
        tracing_disabled=False,
        workflow_name="Production Workflow",
        trace_metadata={"environment": "production"},
    )
Configuration in Development

Use development-specific configuration:

Python
# development_config.py
def get_development_config() -> RunConfig:
    """Development configuration."""
    return RunConfig(
        model="gpt-4o-mini",
        tracing_disabled=True,
        workflow_name="Development Workflow",
    )

Summary

Configuration controls agent and run behavior. Key takeaways:

  1. RunConfig is the main configuration class
  2. Configuration hierarchy - Agent > RunConfig > Global
  3. Model configuration - model, provider, settings
  4. Handoff configuration - filters, history, mappers
  5. Guardrail configuration - input and output guardrails
  6. Tracing configuration - enable/disable, sensitive data
  7. Session configuration - settings, input callbacks
  8. Model input filter - filter before model call
  9. Tool configuration - error formatting
  10. Reasoning configuration - item ID policy
  11. Sandbox configuration - client, concurrency limits
  12. Agent configuration - agent-specific settings
  13. Global configuration - API keys, defaults
  14. Environment variables - external configuration
  15. Configuration patterns - environment, user, task-based
  16. Configuration validation - validate before use
  17. Configuration files - store in files
  18. Documentation - document configuration options
  19. Testing - test with different configs
  20. Deployment - different configs for different environments

Configuration is essential for flexible, maintainable, and environment-aware agent systems.