---
title: "Understanding the Agent Class: Configuration, Instructions, and Models"
description: "A deep dive into every parameter of the OpenAI Agents SDK Agent class — from instructions and model settings to dynamic instructions, cloning, and advanced configuration patterns."
canonical: https://callsphere.ai/blog/openai-agents-sdk-agent-class-configuration-instructions-models
category: "Learn Agentic AI"
tags: ["OpenAI", "Agent Class", "Configuration", "LLM", "Python"]
author: "CallSphere Team"
published: 2026-03-14T00:00:00.000Z
updated: 2026-06-05T11:06:46.217Z
---

# Understanding the Agent Class: Configuration, Instructions, and Models

> A deep dive into every parameter of the OpenAI Agents SDK Agent class — from instructions and model settings to dynamic instructions, cloning, and advanced configuration patterns.

## The Agent Class Is the Foundation

Every workflow built with the OpenAI Agents SDK starts with the `Agent` class. While creating a basic agent requires only a name and instructions, the class exposes a rich set of parameters that control behavior, model selection, tool usage, output format, and multi-agent handoff logic.

Understanding these parameters is essential for building agents that behave predictably in production. This post covers every major parameter with practical examples.

## Core Parameters

### name

The `name` parameter is a human-readable identifier for the agent. It appears in logs, tracing dashboards, and is used to identify agents in multi-agent handoff scenarios:

```mermaid
flowchart LR
    INPUT(["User input"])
    AGENT["Agent
name plus instructions"]
    HAND{"Handoff to
another agent?"}
    SUB["Sub-agent
specialist"]
    GUARD{"Guardrail
passed?"}
    TOOL["Tool call"]
    SDK[("Tracing
OpenAI dashboard")]
    OUT(["Final output"])
    INPUT --> AGENT --> HAND
    HAND -->|Yes| SUB --> GUARD
    HAND -->|No| GUARD
    GUARD -->|Yes| TOOL --> AGENT
    GUARD -->|Block| OUT
    AGENT --> OUT
    AGENT --> SDK
    style AGENT fill:#4f46e5,stroke:#4338ca,color:#fff
    style GUARD fill:#f59e0b,stroke:#d97706,color:#1f2937
    style SDK fill:#ede9fe,stroke:#7c3aed,color:#1e1b4b
    style OUT fill:#059669,stroke:#047857,color:#fff
```

```python
from agents import Agent

agent = Agent(
    name="Customer Support Specialist",
    instructions="You handle customer support inquiries.",
)
```

Choose descriptive names that make it easy to identify agents in logs and traces. Names do not need to be unique, but using unique names helps with debugging.

### instructions

The `instructions` parameter is the system prompt that defines the agent's persona, behavior rules, and response format. This is the most important parameter for controlling agent behavior:

```python
agent = Agent(
    name="Code Reviewer",
    instructions="""You are a senior code reviewer. Your job is to review Python code for:

1. Correctness - Does the code do what it claims?
2. Security - Are there SQL injection, XSS, or auth bypass risks?
3. Performance - Are there N+1 queries, missing indexes, or memory leaks?
4. Readability - Is the code clear and well-structured?

Format your review as:
- SEVERITY: (critical/warning/info)
- LOCATION: (file and line reference)
- ISSUE: (what is wrong)
- FIX: (how to fix it)

Be direct. Do not pad feedback with unnecessary praise.""",
)
```

Instructions can also be a **callable function** that receives the agent and context, enabling dynamic instructions that change based on runtime state. We cover this below.

### model

The `model` parameter specifies which language model to use. It defaults to `gpt-4o` but can be set to any model your API key has access to:

```python
# Use a specific model
agent = Agent(
    name="Fast Responder",
    instructions="Respond quickly and concisely.",
    model="gpt-4o-mini",  # Faster, cheaper model
)

# Use the latest reasoning model
reasoning_agent = Agent(
    name="Deep Analyst",
    instructions="Analyze complex problems step by step.",
    model="o3-mini",
)
```

Different models have different capabilities and cost profiles. Use `gpt-4o-mini` for simple tasks, `gpt-4o` for general-purpose work, and reasoning models like `o3-mini` for complex analysis.

## ModelSettings: Fine-Tuning Model Behavior

The `model_settings` parameter accepts a `ModelSettings` object that controls generation parameters:

```python
from agents import Agent, ModelSettings

agent = Agent(
    name="Creative Writer",
    instructions="Write creative fiction with vivid imagery.",
    model_settings=ModelSettings(
        temperature=0.9,        # Higher = more creative
        top_p=0.95,             # Nucleus sampling threshold
        max_tokens=2000,        # Maximum response length
        frequency_penalty=0.3,  # Reduce repetition
        presence_penalty=0.1,   # Encourage topic diversity
    ),
)
```

Key `ModelSettings` parameters:

| Parameter | Type | Description |
| --- | --- | --- |
| `temperature` | float | Controls randomness (0.0 = deterministic, 2.0 = very random) |
| `top_p` | float | Nucleus sampling — only consider tokens with cumulative probability up to this value |
| `max_tokens` | int | Maximum number of tokens in the response |
| `frequency_penalty` | float | Penalizes tokens based on how often they appear (-2.0 to 2.0) |
| `presence_penalty` | float | Penalizes tokens based on whether they appear at all (-2.0 to 2.0) |
| `parallel_tool_calls` | bool | Whether to allow the model to call multiple tools at once |
| `tool_choice` | str | Controls tool usage: "auto", "required", "none", or a specific tool name |

### Parallel Tool Calls

By default, the model can issue multiple tool calls in a single turn. This speeds up workflows where tools are independent:

```python
agent = Agent(
    name="Research Assistant",
    instructions="Research topics using available tools.",
    model_settings=ModelSettings(
        parallel_tool_calls=True,  # Default behavior
    ),
    tools=[search_web, search_database, search_documents],
)
```

Set `parallel_tool_calls=False` when tools have dependencies or side effects that require sequential execution.

## Dynamic Instructions

Static instructions work for most cases, but sometimes you need instructions that adapt to the current user, time of day, feature flags, or other runtime state. Pass a callable instead of a string:

```python
from agents import Agent, RunContextWrapper

def dynamic_instructions(
    context: RunContextWrapper[UserContext],
    agent: Agent[UserContext],
) -> str:
    user = context.context
    return f"""You are a personalized assistant for {user.name}.

Their account tier is: {user.tier}
Their preferred language is: {user.language}

If they are on the free tier, mention upgrade options naturally.
If they are on the premium tier, provide detailed analysis without upselling."""

agent = Agent(
    name="Personalized Assistant",
    instructions=dynamic_instructions,
)
```

The function receives the `RunContextWrapper` (which holds your custom context) and the agent itself. It must return a string that becomes the system prompt for that run.

This is powerful for multi-tenant applications where each user should experience a different agent persona.

## The tools Parameter

The `tools` parameter accepts a list of tools the agent can call. Tools can be function tools, hosted tools, or agent-as-tool references:

```python
from agents import Agent, function_tool

@function_tool
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"The weather in {city} is 72F and sunny."

@function_tool
def get_time(timezone: str) -> str:
    """Get the current time in a timezone."""
    from datetime import datetime
    return f"Current time: {datetime.now().isoformat()}"

agent = Agent(
    name="Info Agent",
    instructions="Help users with weather and time queries.",
    tools=[get_weather, get_time],
)
```

Tools are covered in depth in Post 5 of this series.

## The handoffs Parameter

Handoffs enable multi-agent workflows where one agent can transfer control to another. The `handoffs` parameter accepts a list of agents or `Handoff` objects:

```python
billing_agent = Agent(
    name="Billing Specialist",
    instructions="Handle billing questions, refunds, and payment issues.",
)

technical_agent = Agent(
    name="Technical Support",
    instructions="Handle technical issues, bugs, and configuration problems.",
)

triage_agent = Agent(
    name="Triage Agent",
    instructions="""You are the first point of contact. Determine the customer's
    issue and hand off to the appropriate specialist:
    - Billing questions -> Billing Specialist
    - Technical issues -> Technical Support""",
    handoffs=[billing_agent, technical_agent],
)
```

When the triage agent decides to hand off, the SDK switches execution to the target agent seamlessly.

## The output_type Parameter

By default, agents return plain text. The `output_type` parameter lets you enforce structured outputs using Pydantic models:

```python
from pydantic import BaseModel
from agents import Agent

class SentimentResult(BaseModel):
    sentiment: str  # "positive", "negative", or "neutral"
    confidence: float
    reasoning: str

agent = Agent(
    name="Sentiment Analyzer",
    instructions="Analyze the sentiment of the given text.",
    output_type=SentimentResult,
)
```

Structured outputs are covered in depth in Post 6 of this series.

## Agent Cloning with .clone()

The `clone()` method creates a copy of an agent with optional parameter overrides. This is useful for creating agent variants without repeating configuration:

```python
base_agent = Agent(
    name="Base Assistant",
    instructions="You are a helpful assistant.",
    model="gpt-4o",
    model_settings=ModelSettings(temperature=0.7),
    tools=[search_tool, calculator_tool],
)

# Create a variant with different instructions but same tools and model
formal_agent = base_agent.clone(
    name="Formal Assistant",
    instructions="You are a helpful assistant. Always respond in formal, professional English.",
)

# Create a cheaper variant for simple queries
lite_agent = base_agent.clone(
    name="Lite Assistant",
    model="gpt-4o-mini",
)
```

The cloned agent inherits all parameters from the original, with only the specified parameters overridden. This is especially useful in multi-agent systems where agents share common tools but have different personas.

## Putting It All Together

Here is a complete example that uses most of the parameters discussed:

```python
import asyncio
from pydantic import BaseModel
from agents import Agent, Runner, ModelSettings, function_tool, RunContextWrapper

class AnalysisResult(BaseModel):
    summary: str
    key_points: list[str]
    risk_level: str
    recommendation: str

@function_tool
def lookup_company(ticker: str) -> str:
    """Look up basic company information by stock ticker."""
    data = {
        "AAPL": "Apple Inc. - Technology - Market Cap: $3.4T",
        "GOOGL": "Alphabet Inc. - Technology - Market Cap: $2.1T",
    }
    return data.get(ticker, f"No data found for {ticker}")

analyst = Agent(
    name="Financial Analyst",
    instructions="""You are a senior financial analyst. Analyze companies
based on available data. Be precise and data-driven.
Always structure your analysis as a formal report.""",
    model="gpt-4o",
    model_settings=ModelSettings(
        temperature=0.3,
        max_tokens=1500,
    ),
    tools=[lookup_company],
    output_type=AnalysisResult,
)

async def main():
    result = await Runner.run(analyst, "Analyze Apple's current market position.")
    output: AnalysisResult = result.final_output_as(AnalysisResult)
    print(f"Summary: {output.summary}")
    print(f"Risk Level: {output.risk_level}")
    for point in output.key_points:
        print(f"  - {point}")

asyncio.run(main())
```

## Best Practices

1. **Keep instructions focused.** Each agent should have a clear, single responsibility. If instructions exceed 500 words, consider splitting into multiple agents.
2. **Use ModelSettings deliberately.** Lower temperature (0.1-0.3) for factual tasks, higher (0.7-0.9) for creative tasks. Always set `max_tokens` to avoid runaway responses.
3. **Prefer dynamic instructions** when behavior depends on user context, feature flags, or time-sensitive data.
4. **Use clone() for variants.** Do not copy-paste agent configurations. Clone from a base and override only what changes.
5. **Name agents descriptively.** Good names make traces and logs immediately readable in production.

---

**Source:** [OpenAI Agents SDK — Agent Configuration](https://openai.github.io/openai-agents-python/agents/)

---

Source: https://callsphere.ai/blog/openai-agents-sdk-agent-class-configuration-instructions-models