Inkdown
Start writing

Study

70 filesยท12 subfolders

Shared Workspace

Study
AI eng

14_CONFIGURATION

Shared from "Study" 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
Why Configuration Matters
basic-ques
core
Revision w/ Whiteboard
CN Basics - 1
CN Basics - 2
DNS
Event loop
programming-language-concepts.md
zero-language-explanation.md
DB
Quick
databases-deep-dive.md
01-introduction.md
02-relational-databases.md
03-database-design.md
04-indexing.md
05-transactions-acid.md
06-nosql-databases.md
07-query-optimization.md
08-replication-ha.md
09-sharding-partitioning.md
10-caching-strategies.md
11-cap-theorem.md
12-connection-pooling.md
13-backup-recovery.md
14-monitoring.md
15-database-selection.md
README.md
JS
core topics
Event loop
Merlin Backend
01-Orchestration.md
02-DeepResearch.md
03-Search.md
04-Scraping.md
05-Streaming.md
06-MultiProviderLLM.md
07-MemoryAndContext.md
08-ErrorHandling.md
09-RateLimiting.md
10-TaskQueue.md
11-SecurityAndAuth.md
Orchestration-2nd-draft
Mobile
Build Alternative
Bundling
metro-bundler-deep-dive.md
OpenAI Agents Python
00_OVERVIEW.md
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
opencode-study
context-handling
core
Python
Alembic
Basics
sqlalchemy - fastapi
SQLAlchemy overview
tweets
system_design_for_agentic_apps.md
Agent Loop
  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
Model Configuration
Model Selection
Python

When to use:

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

When to use:

  • Use multiple model providers
  • Provide fallback providers
  • Test different providers
Model Settings
Python

When to use:

  • Set global model parameters
  • Override agent-specific settings
  • Tune model behavior
Handoff Configuration
Handoff Input Filter
Python

When to use:

  • Control what information is passed between agents
  • Reduce token usage in handoffs
  • Filter sensitive information
Nested Handoff History
Python

When to use:

  • Reduce token usage in deep handoff chains
  • Simplify context for nested agents
  • Optimize for long conversations
Handoff History Mapper
Python

When to use:

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

When to use:

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

When to use:

  • Apply output validation to all agents
  • Global safety checks
  • Global formatting rules
Tracing Configuration
Disable Tracing
Python

When to use:

  • Improve performance
  • Reduce overhead
  • Privacy requirements
Tracing Config
Python

When to use:

  • Fine-grained tracing control
  • Custom tracing behavior
  • Integration with tracing systems
Sensitive Data
Python

When to use:

  • Privacy compliance
  • Security requirements
  • Reduce trace size
Workflow Name
Python

When to use:

  • Identify runs in traces
  • Organize traces by workflow
  • Analytics and reporting
Trace ID
Python

When to use:

  • Link to external systems
  • Custom trace identification
  • Distributed tracing
Group ID
Python

When to use:

  • Link related traces
  • Group traces by conversation
  • User-level tracking
Trace Metadata
Python

When to use:

  • Add custom metadata
  • Filter traces by metadata
  • Analytics integration
Session Configuration
Session Settings
Python

When to use:

  • Control session behavior
  • Manage conversation history
  • Optimize token usage
Session Input Callback
Python

When to use:

  • Custom history combination
  • Special input processing
  • Context window management
Model Input Filter
Call Model Input Filter
Python

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

When to use:

  • Customize error messages
  • Provide user-friendly errors
  • Translate errors
Reasoning Configuration
Reasoning Item ID Policy
Python

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

When to use:

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

Agent Configuration

Agent-Level Settings

Agents have their own configuration:

Python
Configuration Priority

Agent settings override RunConfig:

Python
Model Settings Merging

Model settings are merged:

Python

Global Configuration

Default OpenAI Key
Python
Default OpenAI API
Python
Default Tracing
Python
Default Agent Registration
Python
Harness ID
Python
Verbose Logging
Python

Environment Variables

OpenAI API Key
Bash
Tracing Settings
Bash
Verbose Logging
Bash

Configuration Patterns

1. Environment-Based Configuration

Different configs for different environments:

Python
2. User-Based Configuration

Different configs for different users:

Python
3. Task-Based Configuration

Different configs for different tasks:

Python
4. Cost-Optimized Configuration

Optimize for cost:

Python
5. Performance-Optimized Configuration

Optimize for speed:

Python

Configuration Validation

Validating RunConfig

Validate configuration before use:

Python
Configuration Errors

Handle configuration errors:

Python

Configuration Best Practices

1. Use Configuration Files

Store configuration in files:

Python
2. Use Environment Variables

Use environment for sensitive data:

Python
3. Document Configuration

Document configuration options:

Python
4. Use Configuration Validation

Validate configuration early:

Python
5. Keep Configuration Simple

Don't over-engineer configuration:

Python

Configuration and Testing

Test Configuration

Test with different configurations:

Python
Configuration Fixtures

Use fixtures for common configurations:

Python

Configuration and Deployment

Configuration in Production

Use production-specific configuration:

Python
Configuration in Development

Use development-specific configuration:

Python

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.