OpenAI Agents SDK — CLAUDE.md

# OpenAI Agents SDK — CLAUDE.md

## Core Concepts

- **Agent**: An LLM configured with instructions, tools, and handoffs.
- **Tool**: Python function the agent can call. Decorated with `@function_tool`.
- **Handoff**: Transfer control to another specialized agent.
- **Runner**: Executes the agent loop until completion or max turns.
- **Guardrail**: Validate input/output asynchronously.

## Basic Agent

```python
from agents import Agent, Runner, function_tool

@function_tool
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    return f"The weather in {city} is sunny, 22°C."

agent = Agent(
    name="Weather Assistant",
    instructions="Help users check the weather. Always be concise.",
    tools=[get_weather],
)

result = Runner.run_sync(agent, "What's the weather in Tokyo?")
print(result.final_output)
```

## Multi-Agent Handoffs

```python
billing_agent = Agent(
    name="Billing Agent",
    instructions="Handle billing questions.",
)

triage_agent = Agent(
    name="Triage Agent",
    instructions="Route users to the right team.",
    handoffs=[billing_agent],
)
```

## Structured Output

```python
from pydantic import BaseModel

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

extract_agent = Agent(
    name="Extractor",
    instructions="Extract calendar events from text.",
    output_type=CalendarEvent,
)
```

## Guardrails

```python
from agents import input_guardrail, GuardrailFunctionOutput

@input_guardrail
async def check_safe(ctx, agent, input_text) -> GuardrailFunctionOutput:
    is_safe = await safety_check(input_text)
    return GuardrailFunctionOutput(
        output_info={"safe": is_safe},
        tripwire_triggered=not is_safe,
    )
```

## Development

```bash
pip install openai-agents

# With tracing (recommended)
export OPENAI_API_KEY=...
python -m agents.trace my_agent_script.py
```