Configuration¶

Configure agent behavior with RunConfig and ModelSettings.

RunConfig¶

Global settings for an agent run:

from agents import Runner, RunConfig, ModelSettings

config = RunConfig(
    model="gpt-4o",
    model_settings=ModelSettings(temperature=0.7),
    max_turns=20,
)

result = await Runner.run(agent, "Hello!", run_config=config)

RunConfig Options¶

Parameter	Type	Default	Description
`model`	`str \\| Model`	None	Override all agent models
`model_provider`	`ModelProvider`	OpenAI	Model provider
`model_settings`	`ModelSettings`	None	Global model settings
`max_turns`	`int`	10	Max conversation turns
`input_guardrails`	`list`	None	Global input guardrails
`output_guardrails`	`list`	None	Global output guardrails
`handoff_input_filter`	`HandoffInputFilter`	None	Global handoff filter
`tracing_disabled`	`bool`	False	Disable tracing

ModelSettings¶

Fine-tune model behavior:

from agents import Agent, ModelSettings

settings = ModelSettings(
    temperature=0.7,
    top_p=0.9,
    max_tokens=1000,
    presence_penalty=0.0,
    frequency_penalty=0.0,
)

agent = Agent(
    name="creative",
    instructions="Be creative.",
    model_settings=settings,
)

ModelSettings Options¶

Parameter	Type	Default	Description
`temperature`	`float`	1.0	Randomness (0-2)
`top_p`	`float`	1.0	Nucleus sampling
`max_tokens`	`int`	None	Max output tokens
`presence_penalty`	`float`	0.0	Presence penalty
`frequency_penalty`	`float`	0.0	Frequency penalty
`stop`	`list[str]`	None	Stop sequences

Model Selection¶

By String¶

agent = Agent(name="gpt4", model="gpt-4o")
agent = Agent(name="claude", model="claude-3-5-sonnet-20241022")

Override at Runtime¶

config = RunConfig(model="gpt-4o-mini")
result = await Runner.run(agent, "Hello!", run_config=config)

Model Providers¶

OpenAI (default)¶

from agents import OpenAIProvider

provider = OpenAIProvider(
    api_key="sk-...",
    base_url="https://api.openai.com/v1",
)

config = RunConfig(model_provider=provider)

Hanzo Node¶

from agents import create_hanzo_node_provider

provider = create_hanzo_node_provider(
    api_key="your-hanzo-key",
    base_url="https://api.hanzo.ai/v1",
)

config = RunConfig(model_provider=provider)

Custom Provider¶

from agents import ModelProvider, Model

class MyProvider(ModelProvider):
    def get_model(self, model_name: str) -> Model:
        return MyCustomModel(model_name)

Environment Variables¶

Variable	Description
`OPENAI_API_KEY`	OpenAI API key
`ANTHROPIC_API_KEY`	Anthropic API key
`HANZO_API_KEY`	Hanzo API key

Default Model¶

Set a default model for all agents:

import agents

# Set default
agents.set_default_model("gpt-4o")

# All agents use gpt-4o unless overridden
agent = Agent(name="default", instructions="...")

Configuration Hierarchy¶

Settings are applied in order (later overrides earlier):

Default settings
Agent-level settings (agent.model_settings)
RunConfig settings (config.model_settings)

# Agent settings
agent = Agent(
    model_settings=ModelSettings(temperature=0.5),
)

# RunConfig overrides
config = RunConfig(
    model_settings=ModelSettings(temperature=0.9),
)

# Result uses temperature=0.9
result = await Runner.run(agent, "Hello!", run_config=config)