# OpenAI Agents SDK

> The fastest path from zero to a working agent. Seriously, you can have something running in five minutes, with
> handoffs between agents, guardrails, and tracing. The SDK evolved from the Swarm experiment and it shows; the
> abstractions are minimal and stay out of your way. The handoff pattern for multi-agent is elegant in its simplicity. The
> catch is that "minimal" also means "you're building the rest yourself." No built-in memory, no graph orchestration,
> limited context management. It also supports 100+ providers now, which is good because the early "OpenAI only"
> perception was holding it back. I'd use this for prototypes and for production systems where the agent logic is
> straightforward. Once you need complex workflows or persistent memory, you'll graduate to something heavier.

**Repository:** https://github.com/openai/openai-agents-python
**Stars:** ~19K
**Language:** Python (JavaScript/TypeScript version also available)
**License:** MIT
**Last Release:** v0.9.0 (February 13, 2026)
**Backing:** OpenAI

---

## Overview

The OpenAI Agents SDK is a lightweight but powerful framework for building multi-agent workflows. It evolved from the experimental Swarm project into a production-ready SDK maintained by OpenAI. The SDK represents OpenAI's official approach to agent development, designed to showcase best practices while remaining flexible enough for real-world applications.

The framework is intentionally minimal compared to alternatives like LangChain or CrewAI. It provides just enough structure to handle common agent patterns while staying out of the way when you need custom behavior. This philosophy makes it an excellent choice for developers who want agent capabilities without the complexity of heavier frameworks.

### From Swarm to Production

The Agents SDK evolved from OpenAI's Swarm experiment, which explored multi-agent patterns. The SDK retains Swarm's core concepts - agents, handoffs, and tool use - but adds production features like:

- Robust error handling and retry logic
- Comprehensive tracing and observability
- Session management for conversation persistence
- Guardrails for input/output validation
- Support for 100+ model providers beyond OpenAI

### Design Philosophy

The SDK follows a few key principles:

1. **Minimal abstraction** - Don't hide the underlying LLM calls
2. **Explicit control** - Developers control the agent loop, not the framework
3. **Provider agnostic** - Works with any LLM supporting tool use
4. **Production ready** - Built-in observability and error handling

---

## Architecture

The OpenAI Agents SDK uses a clean, layered architecture that separates concerns while maintaining simplicity.

### Core Components

```
┌─────────────────────────────────────────────────────────────────┐
│               OpenAI Agents SDK Architecture                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                       Runner Layer                         │   │
│  │  ┌───────────────────────────────────────────────────┐  │   │
│  │  │  Runner                                            │  │   │
│  │  │  - run_async() / run_sync()                       │  │   │
│  │  │  - run_stream() for streaming                     │  │   │
│  │  │  - Manages agent execution loop                   │  │   │
│  │  └───────────────────────────────────────────────────┘  │   │
│  └─────────────────────────────────────────────────────────┘   │
│                              │                                   │
│  ┌───────────────────────────▼─────────────────────────────┐   │
│  │                     Agents Layer                            │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │   │
│  │  │ Instructions │  │   Tools      │  │  Handoffs   │  │   │
│  │  │  (System     │  │  (Functions  │  │  (Agent     │  │   │
│  │  │   Prompt)    │  │   agent can  │  │   transfer) │  │   │
│  │  └──────────────┘  │   call)      │  └──────────────┘  │   │
│  │  ┌──────────────┐  └──────────────┘                    │   │
│  │  │  Guardrails  │  ┌──────────────┐                    │   │
│  │  │  (Input/     │  │ Output Type  │                    │   │
│  │  │   Output     │  │ (Structured  │                    │   │
│  │  │   validation)│  │  output)     │                    │   │
│  │  └──────────────┘  └──────────────┘                    │   │
│  └───────────────────────────────────────────────────────────┘   │
│                              │                                   │
│  ┌───────────────────────────▼─────────────────────────────┐   │
│  │                    Sessions Layer                           │   │
│  │  - SQLiteSession (file-based persistence)                │   │
│  │  - RedisSession (distributed sessions)                   │   │
│  │  - Custom session implementations                        │   │
│  └───────────────────────────────────────────────────────────┘   │
│                              │                                   │
│  ┌───────────────────────────▼─────────────────────────────┐   │
│  │                  Provider Layer                            │   │
│  │  OpenAI Responses API + 100+ other LLMs                 │   │
│  │  (via OpenAI-compatible APIs)                           │   │
│  └───────────────────────────────────────────────────────────┘   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

### The Runner

The `Runner` is the execution engine that manages agent loops:

```python
from agents import Agent, Runner

agent = Agent(name="assistant", instructions="Helpful assistant")

# Synchronous execution
result = Runner.run_sync(agent, "Hello!")

# Asynchronous execution
result = await Runner.run(agent, "Hello!")

# Streaming
async for event in Runner.run_stream(agent, "Hello!"):
    print(event)
```

The Runner handles:
- Tool call loops (agent → tool → agent → ...)
- Context window management (basic truncation)
- Error handling and retries
- Tracing and observability

### Agent Definition

Agents are lightweight objects with configuration:

```python
from agents import Agent

agent = Agent(
    name="research_assistant",
    instructions="""You are a research assistant. 
    Help users find information and answer questions.
    Be thorough and cite your sources.""",
    tools=[search_web, calculate],
    handoffs=[specialist_agent],
    output_type=ResearchOutput,
    input_guardrails=[validate_input],
    output_guardrails=[validate_output]
)
```

Key agent properties:
- **name** - Identifier for the agent
- **instructions** - System prompt defining behavior
- **tools** - List of callable functions
- **handoffs** - Other agents this one can transfer to
- **output_type** - Pydantic model for structured output
- **guardrails** - Validation functions for inputs/outputs

---

## Architectural Tradeoffs and Design Decisions

### Why This Architecture?

OpenAI built the Agents SDK from their experience running millions of agent conversations. They saw what patterns worked at scale and codified them.

**The insight**: The best agent abstractions come from seeing millions of real-world agent runs, not from theoretical design. What works in production trumps elegant theory.

This explains the handoffs, guardrails, and tool patterns - they're battle-tested, not theoretical.

### The Guardrails Tradeoff

OpenAI includes guardrails for input/output validation:

**The benefit**:
```python
from agents import Agent, guardrails
from pydantic import BaseModel

class OutputFormat(BaseModel):
    summary: str
    confidence: float

agent = Agent(
    name="assistant",
    output_type=OutputFormat,
    guardrails=[
        guardrails.input_validator(my_input_check),
    ]
)
```

**The cost**:
- Guardrails add latency
- Validation logic must be carefully designed
- Can block valid inputs incorrectly
- Not all validation fits their model

**When guardrails help**:
- Production systems requiring quality control
- Structured output needs
- Input safety requirements

**When they're overhead**:
- Prototyping
- Simple use cases
- When LLM alone is sufficient

### The Handoffs Tradeoff

Handoffs allow agents to transfer to other agents:

**The benefit**:
```python
triage_agent = Agent(name="triage", ...)
billing_agent = Agent(name="billing", ...)
support_agent = Agent(name="support", ...)

triage_agent.handoffs = [billing_agent, support_agent]
```

**The cost**:
- Can create complex control flow
- Harder to debug than linear flows
- Need to design agent boundaries carefully
- Potential for infinite handoff loops

### The "Works Best with OpenAI" Tradeoff

The SDK is optimized for OpenAI models:

**The benefit**:
- Best tool calling performance
- Native structured output
- Seamless model upgrades
- Best-in-class reasoning

**The cost**:
- Other models work but less optimized
- Can feel like a "tax" to use OpenAI
- Migration path unclear for other providers

### When to Choose OpenAI Agents SDK

**Use it when**:
- Using OpenAI models
- Want battle-tested patterns
- Production systems
- Need guardrails

**Avoid it when**:
- Using other model providers
- Quick prototyping (simpler alternatives exist)
- Need maximum flexibility
- Minimal overhead requirement

**Migration warning**: While the SDK can use other models, it's optimized for OpenAI. Non-OpenAI usage may feel like using a round peg in a square hole.

---

## Context Management

The OpenAI Agents SDK provides several mechanisms for managing context, though it requires more manual handling than some frameworks.

### Instructions (System Prompts)

Instructions are the primary way to provide context to agents:

```python
# Static instructions
agent = Agent(
    name="assistant",
    instructions="You are a helpful coding assistant."
)

# Dynamic instructions based on context
async def get_instructions(context: RunContext[MyContext]) -> str:
    return f"You are assisting user {context.user_id}." + \
           f"Current project: {context.project_name}"

dynamic_agent = Agent(
    name="contextual_assistant",
    instructions=get_instructions
)
```

Dynamic instructions are evaluated at runtime, allowing you to inject contextual information based on the execution context.

### Session Management

Sessions provide conversation persistence:

```python
from agents import Runner
from agents.sessions import SQLiteSession

# Create a persistent session
session = SQLiteSession("conversations.db")

# Run with session context
result = await Runner.run(
    agent,
    "Hello!",
    session=session,
    session_id="user_123_thread_456"
)

# Subsequent runs maintain context
result2 = await Runner.run(
    agent,
    "What did I just say?",  # Agent has access to previous message
    session=session,
    session_id="user_123_thread_456"
)
```

Session types:
- **SQLiteSession** - File-based SQLite storage
- **RedisSession** - Distributed Redis storage
- **InMemorySession** - Non-persistent (default)
- **Custom Session** - Implement the Session protocol

### Context Engineering Assessment

The SDK provides basic building blocks but leaves advanced context management to developers:

**contextpatterns.com mapping:**

- ⚠️ **Context Rot awareness**: No automatic handling - developers must monitor and manage context quality themselves. The SDK passes messages but doesn't assess quality degradation. For production systems, you'd implement token counting and potentially trigger summarization. The simplicity is intentional: the SDK does the basics well, advanced patterns are your responsibility.

- ✅ **The Pyramid**: Instructions can be structured hierarchically via careful prompt engineering. You have full control over system prompts, so you can order information from general to specific. The SDK doesn't enforce structure, but it doesn't prevent it either. Works well if you design prompts carefully.

- ⚠️ **Select, Don't Dump**: Manual implementation required - no built-in retrieval. The SDK passes what you give it. If you want intelligent selection, you implement retrieval tools and inject relevant context. This gives control but requires more code. Compare to LangChain's built-in retrievers.

- ⚠️ **Compress & Restart**: Manual implementation - no automatic summarization. Long conversations grow without bound. You'd implement compression by periodically calling the LLM to summarize older messages. The SDK makes it possible but doesn't automate it.

- ⚠️ **Write Outside the Window**: Via custom session storage, but must be implemented. The SDK supports handoffs and tool use, so you can store context externally. But there's no built-in memory abstraction. You decide how to persist state. Works but requires custom code.

- ⚠️ **Isolate**: Handoffs transfer context - no built-in sandboxing between agents. When an agent hands off to another, context flows. For isolation, you'd need separate agent instances and careful handoff design. The default is shared context, not isolation.

- ⚠️ **Progressive Disclosure**: Manual implementation required. You control what goes into instructions, but there's no automatic "reveal on demand." You'd implement this by dynamically adjusting prompts based on conversation state. The SDK gives you control; you handle the pattern.

- ✅ **Recursive Delegation**: Handoffs enable agent-to-agent delegation naturally. This is a first-class pattern in the SDK. An agent can hand off to another agent, which can hand off further. The handoff mechanism is designed for this. Good support for delegation chains.

---

## Tool System

The OpenAI Agents SDK provides a clean, decorator-based tool system.

### Tool Definition

Tools are defined using the `@function_tool` decorator:

```python
from agents import function_tool
from pydantic import BaseModel

# Simple tool
@function_tool
def get_weather(city: str) -> str:
    """Get the weather for a city."""
    return f"Weather in {city}: sunny, 75°F"

# Tool with complex parameters
class SearchParams(BaseModel):
    query: str
    max_results: int = 10
    filters: list[str] = []

@function_tool
def search_web(params: SearchParams) -> dict:
    """Search the web for information."""
    results = perform_search(params.query, params.max_results, params.filters)
    return {"results": results, "count": len(results)}
```

The decorator:
1. Extracts the function signature for the LLM
2. Generates JSON schema from type hints
3. Validates arguments using Pydantic
4. Handles errors gracefully

### Tool Features

**Timeouts**: Configure maximum execution time
```python
@function_tool(timeout_seconds=30)
def slow_operation() -> str:
    """This tool has 30 seconds to complete."""
    pass
```

**Async Tools**: Full async support
```python
@function_tool
async def fetch_data(url: str) -> str:
    """Fetch data from URL asynchronously."""
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as response:
            return await response.text()
```

**Context Access**: Tools can access run context
```python
@function_tool
async def get_user_data(context: RunContext[UserContext]) -> dict:
    """Get data for the current user."""
    user_id = context.user_id
    return await database.get_user(user_id)
```

### MCP Support

The SDK supports MCP (Model Context Protocol) through extensions:

```python
from agents.extensions import MCPClient

# Connect to an MCP server
mcp_client = MCPClient("https://mcp.example.com")

# Use MCP tools in agent
agent = Agent(
    name="mcp_agent",
    tools=mcp_client.get_tools()
)
```

---

## Multi-Agent Support

Multi-agent orchestration is a core strength of the OpenAI Agents SDK, centered around the handoff mechanism.

### Handoffs

Handoffs enable clean agent-to-agent transfers:

```python
from agents import Agent, handoff

# Define specialized agents
spanish_agent = Agent(
    name="Spanish",
    instructions="You speak only Spanish."
)

english_agent = Agent(
    name="English",
    instructions="You speak only English."
)

# Create triage agent with handoffs
triage = Agent(
    name="Triage",
    instructions="""You are a language router.
    If the user speaks Spanish, transfer to the Spanish agent.
    If the user speaks English, transfer to the English agent.""",
    handoffs=[spanish_agent, english_agent]
)
```

When `triage` decides to handoff, control transfers completely to the target agent along with conversation context.

### Handoff Context Transfer

Context can be passed during handoff:

```python
from agents import handoff

researcher_to_writer = handoff(
    agent=writer_agent,
    tool_name="transfer_to_writer",
    on_handoff=lambda context, writer: {
        # Pass additional context
        "research_summary": context.last_message,
        "tone": context.user_preferences.get("tone", "professional")
    }
)

researcher = Agent(
    name="Researcher",
    handoffs=[researcher_to_writer]
)
```

### Multi-Agent Patterns

**Router Pattern**:
```python
router = Agent(
    name="Router",
    instructions="Route to the appropriate specialist based on topic.",
    handoffs=[sales_agent, support_agent, technical_agent]
)
```

**Supervisor Pattern**:
```python
supervisor = Agent(
    name="Supervisor",
    instructions="""You are a project manager.
    Delegate tasks to your team members and synthesize their results.""",
    handoffs=[researcher, coder, designer]
)
```

**Sequential Handoffs**:
```python
researcher = Agent(name="Researcher", handoffs=[writer])
writer = Agent(name="Writer", handoffs=[editor])
editor = Agent(name="Editor")
```

### Context Isolation

The SDK provides limited context isolation:

- **No built-in sandboxing** - Context transfers with handoffs
- **Shared session** - All agents in a session share conversation history
- **Manual isolation** - Must create separate sessions for true isolation

---

## Memory

The OpenAI Agents SDK provides basic memory through sessions but lacks sophisticated memory management.

### Short-term Memory

Conversation history is maintained automatically within sessions:

```python
from agents.sessions import SQLiteSession

session = SQLiteSession("chat.db")

# First interaction
result1 = await Runner.run(agent, "Hello, I'm John", session=session, session_id="123")

# Agent remembers
result2 = await Runner.run(agent, "What's my name?", session=session, session_id="123")
# Agent responds: "Your name is John."
```

### Long-term Memory

The SDK does not provide built-in long-term memory. Developers must implement:

```python
# Custom memory implementation
async def get_enhanced_context(session_id: str, user_input: str) -> str:
    # Retrieve from vector store
    memories = await vector_store.search(user_input, top_k=5)
    
    # Get recent conversation
    recent = await session.get_recent(session_id, limit=10)
    
    # Build enhanced context
    context = f"""Relevant memories:
{format_memories(memories)}

Recent conversation:
{format_messages(recent)}

User: {user_input}"""
    
    return context
```

### Memory Limitations

- No automatic summarization
- No semantic memory retrieval
- No working memory abstraction
- Manual management of context window

---

## Streaming & UX

The SDK provides excellent streaming support for building responsive applications.

### Token Streaming

Stream tokens as they're generated:

```python
async for event in Runner.run_stream(agent, "Write a story"):
    if event.type == "raw_response":
        print(event.data.delta, end="")  # Print token
    elif event.type == "tool_call":
        print(f"\n[Tool: {event.data.tool_name}]")
    elif event.type == "agent_switch":
        print(f"\n[Handoff to: {event.data.agent_name}]")
```

Event types include:
- `raw_response` - LLM tokens
- `tool_call` - Tool execution start
- `tool_result` - Tool execution complete
- `agent_switch` - Handoff between agents
- `complete` - Execution finished

### Structured Streaming

Stream structured output progressively:

```python
class Analysis(BaseModel):
    summary: str
    key_points: list[str]
    recommendation: str

agent = Agent(
    name="analyzer",
    output_type=Analysis
)

async for event in Runner.run_stream(agent, "Analyze this data"):
    if event.type == "output":
        # Partial structured data
        partial = event.data.partial
        print(f"Summary so far: {partial.summary}")
```

---

## Developer Experience

### Setup Complexity

**Time to first agent**: Under 5 minutes.

```bash
pip install openai-agents
```

```python
from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="Helpful assistant")
result = Runner.run_sync(agent, "Hello!")
print(result.final_output)
```

### Documentation

Documentation is available at [openai.github.io/openai-agents-python](https://openai.github.io/openai-agents-python):

- Getting started guide
- API reference
- Examples directory
- Migration guide from Swarm

### Type Safety

Full type hints throughout:

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

class Output(BaseModel):
    answer: str
    confidence: float

agent: Agent[Output] = Agent(
    name="typed",
    output_type=Output
)

result: RunResult[Output] = Runner.run_sync(agent, "Question")
# result.final_output is typed as Output
```

### Debugging

Built-in tracing integrates with popular observability platforms:

```python
import agents

# Enable tracing
agents.set_tracing_backend("logfire")  # or "braintrust", "agentops"

# All runs are automatically traced
result = await Runner.run(agent, "Task")
```

Supported tracing backends:
- Logfire
- Braintrust
- AgentOps
- Custom backends via TracingProcessor protocol

---

## Model Provider Support

### Supported Providers

The SDK is provider-agnostic and works with:

- **OpenAI** - GPT-4, GPT-4o, o1 (native)
- **Anthropic** - Claude (via OpenAI-compatible API)
- **Google** - Gemini (via OpenAI-compatible API)
- **100+ providers** via OpenAI-compatible endpoints
- **Local models** via Ollama, vLLM, etc.

### Adding Custom Providers

```python
from agents import Agent
from openai import AsyncOpenAI

# Create client for any OpenAI-compatible API
client = AsyncOpenAI(
    base_url="https://api.custom.com/v1",
    api_key="your-key"
)

agent = Agent(
    name="custom",
    model_client=client,
    model="custom-model-name"
)
```

---

## Lock-in & Escape Hatches

### Coupling Level

**Low**. The SDK is designed for minimal coupling:

- Agent definitions are lightweight
- Tools are standard Python functions
- No heavy abstractions over LLM calls
- Standard interfaces throughout

### Escape Difficulty

**Low**. Easy to migrate away:

**Tools**: Tools are plain Python functions with optional decorators:
```python
@function_tool
def my_tool(arg: str) -> str:
    return result

# Can be used without the framework
def my_tool_plain(arg: str) -> str:
    return result
```

**Model Access**: Direct access to underlying API calls
```python
# Can extract and use the client directly
client = agent.model_client
response = await client.chat.completions.create(...)
```

**Prompts**: Instructions are plain strings, easily portable

### Dependency Weight

**Light**. Minimal dependencies:

- `openai` - Core OpenAI client
- `pydantic` - Validation
- Optional tracing backends

Much lighter than LangChain or even CrewAI.

---

## Production Readiness

### Error Handling

Robust error handling with automatic retries:

```python
result = await Runner.run(
    agent,
    "Task",
    max_turns=10,  # Limit tool call iterations
    max_retries=3  # Retry on transient failures
)
```

### Retry and Fallback

```python
# Configure retry per agent
agent = Agent(
    name="reliable",
    model_settings={
        "max_retries": 3,
        "timeout": 30.0
    }
)
```

### Cost Tracking

Via tracing integrations:

```python
import agents

agents.set_tracing_backend("logfire")

# Cost tracking available in tracing dashboard
result = await Runner.run(agent, "Task")
```

### Logging and Tracing

Comprehensive observability:

```python
# Every run generates a trace
trace = await Runner.run(agent, "Task")

# Access trace data
print(f"Duration: {trace.duration_ms}ms")
print(f"Tokens: {trace.token_usage.total}")
print(f"Tool calls: {[t.name for t in trace.tool_calls]}")
```

### Deployment

The SDK works anywhere Python runs:

- **Web frameworks** - FastAPI, Flask, Django
- **Serverless** - AWS Lambda, Vercel Functions, Cloudflare Workers
- **Containers** - Docker, Kubernetes
- **Edge** - Python edge runtimes

---

## Strengths

1. **Lightweight and fast** - Minimal overhead compared to direct API calls. No heavy framework abstractions slowing you down.

2. **Elegant handoffs** - The handoff mechanism is clean and intuitive. Multi-agent orchestration feels natural.

3. **Provider agnostic** - Works with 100+ LLMs through OpenAI-compatible APIs. Not locked into OpenAI models.

4. **Built-in sessions** - Conversation persistence works out of the box with SQLite or Redis.

5. **Excellent observability** - Tracing integrations with Logfire, Braintrust, and AgentOps provide production visibility.

6. **Guardrails** - Input and output validation helps catch issues early and ensure quality.

7. **Official OpenAI support** - Backed by OpenAI, ensuring alignment with best practices and future API developments.

8. **Streaming first** - Streaming is a first-class citizen, not an afterthought.

---

## Weaknesses

1. **Less mature ecosystem** - Smaller community and fewer third-party resources compared to LangChain.

2. **Limited orchestration** - No complex graph support like LangGraph. Handoffs are powerful but simpler.

3. **Memory gaps** - No advanced memory patterns. Basic session storage only; no semantic memory or automatic summarization.

4. **Context engineering** - Requires manual implementation of advanced context management patterns.

5. **JavaScript/TypeScript version less mature** - The Python SDK is the primary focus; JS/TS version has fewer features.

6. **Rapid evolution** - As a relatively new framework (evolved from Swarm in late 2025), APIs may change.

---

## Best For

- **Multi-agent handoffs** - Applications needing clean agent transfer mechanisms
- **Lightweight agents** - When you want agent capabilities without framework heaviness
- **Provider flexibility** - Need to switch between models or use non-OpenAI providers
- **Production tracing** - Need observability from day one
- **Rapid prototyping** - Quick agent builds without learning complex abstractions
- **OpenAI ecosystem** - Already using OpenAI APIs and want official tooling

---

## Avoid When

- **Complex graph workflows** - Need LangGraph-style complex orchestration with cycles and conditional branching
- **Advanced memory requirements** - Need Letta-style sophisticated memory management
- **Maximum ecosystem breadth** - Need the largest selection of pre-built integrations
- **TypeScript/JavaScript priority** - Python SDK is more mature and feature-complete
- **Complex RAG** - Need advanced retrieval pipelines; consider Haystack or LangChain

---

## Code Example

```python
import asyncio
from pydantic import BaseModel
from agents import Agent, Runner, function_tool, handoff, RunContext

# Define structured output
class ResearchReport(BaseModel):
    summary: str
    key_findings: list[str]
    sources: list[str]
    confidence: float

# Define tools
@function_tool
def search_web(query: str, max_results: int = 5) -> str:
    """Search the web for information."""
    # Implementation would call search API
    return f"Search results for '{query}': [simulated results]"

@function_tool
def fetch_webpage(url: str) -> str:
    """Fetch and extract content from a webpage."""
    # Implementation would fetch URL
    return f"Content from {url}: [simulated content]"

# Define specialized agents
researcher = Agent(
    name="Researcher",
    instructions="""You are a research specialist. Find comprehensive 
    information on topics using web search. Always cite your sources.""",
    tools=[search_web, fetch_webpage],
    model_settings={"max_retries": 3}
)

writer = Agent(
    name="Writer",
    instructions="""You are a technical writer. Create clear, well-structured 
    reports based on research. Use markdown formatting.""",
    output_type=ResearchReport
)

editor = Agent(
    name="Editor",
    instructions="""You are an editor. Review content for accuracy, clarity, 
    and completeness. Provide specific feedback for improvements."""
)

# Create handoffs with context transfer
researcher_to_writer = handoff(
    agent=writer,
    tool_name="transfer_to_writer",
    on_handoff=lambda ctx, writer: {
        "research_notes": ctx.last_message,
        "topic": ctx.metadata.get("topic", "general")
    }
)

writer_to_editor = handoff(
    agent=editor,
    tool_name="transfer_to_editor"
)

# Add handoffs to agents
researcher.handoffs.append(researcher_to_writer)
writer.handoffs.append(writer_to_editor)

# Create triage agent
triage = Agent(
    name="Triage",
    instructions="""You are a request router. Analyze incoming requests and 
    route them appropriately:
    - Research tasks → Researcher
    - Writing tasks → Writer
    - Review tasks → Editor""",
    handoffs=[researcher, writer, editor]
)

# Context for personalized responses
class UserContext:
    def __init__(self, user_id: str, preferences: dict):
        self.user_id = user_id
        self.preferences = preferences

async def main():
    user_context = UserContext(
        user_id="user_123",
        preferences={"tone": "professional", "detail_level": "high"}
    )
    
    # Run with streaming for real-time feedback
    print("Starting research workflow...\n")
    
    stream = Runner.run_stream(
        triage,
        "Research the latest developments in quantum computing and write a summary report",
        context=user_context
    )
    
    async for event in stream:
        if event.type == "raw_response":
            print(event.data.delta, end="", flush=True)
        elif event.type == "agent_switch":
            print(f"\n\n[→ Handoff to {event.data.agent_name}]\n")
        elif event.type == "tool_call":
            print(f"\n[Using tool: {event.data.tool_name}]")
    
    # Get final result
    result = await Runner.run(
        triage,
        "Research the latest developments in quantum computing and write a summary report",
        context=user_context
    )
    
    if isinstance(result.final_output, ResearchReport):
        report = result.final_output
        print(f"\n\n=== Final Report ===")
        print(f"Confidence: {report.confidence}")
        print(f"\nSummary:\n{report.summary}")
        print(f"\nKey Findings:")
        for finding in report.key_findings:
            print(f"  • {finding}")

if __name__ == "__main__":
    asyncio.run(main())
```

---

## Activity Status

**Active** - The OpenAI Agents SDK has recent releases (February 2026) with active development. As OpenAI's official agent framework, it receives regular updates and improvements. The evolution from Swarm to the production SDK shows OpenAI's commitment to providing developer tools beyond just API access.

Recent developments include:
- Guardrails for input/output validation
- Enhanced tracing integrations
- Session management improvements
- JavaScript/TypeScript SDK expansion

---

**Last researched: 2026-02-16**