OpenAI Agents SDK

Learning Objectives

• Understand what the OpenAI Agents SDK is and how it differs from LangChain and CrewAI
• Identify the SDK's core concepts: agents, tools, handoffs, guardrails, and tracing
• Evaluate when to use the OpenAI Agents SDK vs. community frameworks

What Is the OpenAI Agents SDK?

The OpenAI Agents SDK (also called the Swarm-successor framework) is OpenAI's official Python library for building production-ready AI agents, released publicly in 2025. While LangChain and CrewAI are community-built frameworks that work with multiple LLM providers, the OpenAI Agents SDK is first-party infrastructure from OpenAI itself — designed specifically for building agents on OpenAI's models with native access to function calling, the Assistants API, and the emerging Model Context Protocol.

The SDK is built around a small set of clean abstractions: an Agent (an LLM with instructions and tools), tools (typed Python functions), handoffs (routing between agents), guardrails (input/output validation), and tracing (native observability in the OpenAI platform).

Core Concepts

Agents

An Agent in the SDK is an LLM configured with specific instructions and tools:

from agents import Agent, Runner

agent = Agent(
    name="Research Agent",
    instructions="You are a helpful research assistant. Research topics thoroughly and cite sources.",
    model="gpt-4o"
)

result = Runner.run_sync(agent, "What are the top AI safety research areas in 2026?")
print(result.final_output)

The Agent is the atomic unit — each agent has a single clear responsibility and a defined set of tools.

Tools — Typed Python Functions

Tools are regular Python functions decorated with @function_tool:

from agents import function_tool
import httpx

@function_tool
def search_web(query: str) -> str:
    """Search the web for current information on any topic."""
    # Implementation using Tavily, SerpAPI, or any search service
    response = httpx.get("https://api.tavily.com/search",
                         json={"query": query, "api_key": "..."})
    return response.json()["results"][0]["content"]

agent = Agent(
    name="Search Agent",
    instructions="Use the search_web tool to find current information.",
    tools=[search_web],
    model="gpt-4o"
)

Python type hints are used to generate the JSON schema that the model uses to call the function — clean and familiar for Python developers.

Handoffs — Multi-Agent Routing

Handoffs allow agents to route tasks to other specialized agents:

from agents import Agent, handoff

specialist_agent = Agent(
    name="Code Agent",
    instructions="You specialize in writing and debugging Python code.",
    model="gpt-4o"
)

orchestrator = Agent(
    name="Orchestrator",
    instructions="Route requests to the appropriate specialist.",
    handoffs=[handoff(specialist_agent)]
)

When the orchestrator determines a coding task should go to the Code Agent, it hands off seamlessly. The handoff mechanism is how multi-agent systems are built — each agent does one thing well, and a router decides who handles what.

Guardrails — Input/Output Validation

Guardrails are validation functions that run before or after agent execution:

from agents import Agent, input_guardrail, GuardrailFunctionOutput

@input_guardrail
async def check_no_pii(ctx, agent, input) -> GuardrailFunctionOutput:
    # Scan input for PII patterns; if found, stop and return safe response
    if has_pii(input):
        return GuardrailFunctionOutput(
            output_info="PII detected",
            tripwire_triggered=True
        )
    return GuardrailFunctionOutput(tripwire_triggered=False)

Built-in and custom guardrails enable:

• Blocking harmful inputs before they reach the model
• Validating outputs before returning to the user
• Ensuring compliance with content policies
• Domain-specific safety checks

Tracing — Native OpenAI Observability

Every agent run is automatically traced in the OpenAI platform:

• View the full execution tree — which tools were called, in what order, with what arguments
• See every LLM call with full prompt and response
• Latency and token consumption per step
• Available in the OpenAI Dashboard under Traces

This first-party tracing is a significant advantage over community frameworks that require a separate observability tool (like LangSmith for LangChain).

MCP Integration

The OpenAI Agents SDK has native support for the Model Context Protocol (MCP):

from agents import MCPServerStdio

# Connect to any MCP server
mcp_server = MCPServerStdio(command="npx", args=["-y", "@modelcontextprotocol/server-filesystem"])
agent = Agent(name="File Agent", mcp_servers=[mcp_server], ...)

This makes it easy to give agents access to any of the 10,000+ MCP-compatible tools and services.

Pricing

The SDK is free and open source. Costs come from OpenAI API usage only — GPT-4o at $2.50/$10 per million tokens (input/output) as of early 2026.

Strengths

• First-party from OpenAI: Official support; stays current with new OpenAI model features
• Native function calling semantics: Cleanest integration with GPT's built-in tool use capability
• Handoffs for multi-agent routing: Clean, explicit mechanism for routing between specialized agents
• Guardrails built in: Input/output validation is a first-class feature
• Native tracing: Built-in observability without a separate tool
• MCP native: First-class Model Context Protocol support for the expanding MCP ecosystem
• Small footprint: Fewer abstractions than LangChain — cleaner, more readable code

Limitations & Considerations

• OpenAI-centric: Works best with OpenAI models; using Claude or Gemini requires workarounds
• Newer and less battle-tested: Released 2025; smaller ecosystem than LangChain's years of community building
• Fewer integrations: LangChain's 800+ data loaders and 50+ vector stores are not matched
• Python only: No JavaScript/TypeScript SDK equivalent (as of early 2026)
• Less flexibility for RAG: LlamaIndex is more purpose-built for complex RAG pipelines

Best Use Cases

When to choose alternatives:

• Multi-LLM provider applications → LangChain
• Role-based multi-agent teams → CrewAI
• Code execution focus → AG2
• Best-in-class RAG → LlamaIndex
• Visual/no-code agents → Relevance AI or n8n

Getting Started

pip install openai-agents

import asyncio
from agents import Agent, Runner, function_tool

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

agent = Agent(
    name="Weather Agent",
    instructions="Help users get weather information. Always be friendly.",
    tools=[get_weather],
    model="gpt-4o"
)

result = Runner.run_sync(agent, "What is the weather like in Tokyo?")
print(result.final_output)

Key Takeaways

• The OpenAI Agents SDK is OpenAI's official Python framework for building production agents — clean abstractions for tools, handoffs, guardrails, and tracing
• Handoffs enable explicit multi-agent routing — route tasks to specialized agents based on what the orchestrator decides
• Guardrails provide first-class input/output validation for safety-critical agent deployments
• Native MCP support connects agents to the growing ecosystem of 10,000+ MCP-compatible tools and services
• Best for developers building primarily on OpenAI's models; LangChain and LlamaIndex are better for multi-provider or complex RAG use cases