Getting Started with OpenAI Agents SDK

July 10, 2026 · 12 min read

Introduction

The OpenAI Agents SDK is a lightweight Python framework for building agentic AI applications. It replaces the earlier Swarm experiment with a production-ready design that has very few abstractions — just agents, tools, handoffs, and guardrails.

In this tutorial, we'll build working agents step by step, from a simple chatbot to a multi-agent system with handoffs.

Installation

pip install --upgrade openai-agents

You also need an OpenAI API key set as OPENAI_API_KEY. Or point it at 9Router for free models.

Your First Agent

from agents import Agent, Runner

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant."
)

result = Runner.run_sync(agent, "What is the capital of France?")
print(result.final_output)

That's it. The agent takes your instructions and handles the rest. By default it uses GPT-5.6, but you can switch models:

agent = Agent(
    name="Assistant",
    instructions="...",
    model="gpt-4o-mini"
)

Adding Tools

Tools are Python functions that the agent can call. Use the function_tool decorator:

import random
from agents import Agent, Runner, function_tool

@function_tool
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    temps = {"london": 15, "tokyo": 22, "paris": 18, "new york": 20}
    temp = temps.get(city.lower(), random.randint(10, 30))
    return f"The temperature in {city} is {temp}°C"

agent = Agent(
    name="Weather Agent",
    instructions="Use the weather tool to answer questions.",
    tools=[get_weather]
)

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

The agent automatically discovers the tool from its type hints and docstring, and calls it when needed.

Agent Handoffs

Agents can delegate work to other agents. This is how you build specialized sub-agents:

from agents import Agent, Runner

spanish_agent = Agent(
    name="Spanish Agent",
    instructions="You translate text to Spanish.",
)

french_agent = Agent(
    name="French Agent",
    instructions="You translate text to French.",
)

triage_agent = Agent(
    name="Triage Agent",
    instructions="Route the user to the right language agent.",
    tools=[spanish_agent.as_tool(), french_agent.as_tool()]
)

result = Runner.run_sync(triage_agent, "Say 'hello' in Spanish")
print(result.final_output)

The triage agent examines the request and hands off to the Spanish agent automatically.

Guardrails

Guardrails validate inputs and outputs. They can reject harmful or off-topic requests:

from agents import Agent, Runner, InputGuardrail, GuardrailFunctionOutput

def check_safety(ctx, agent, input_data):
    messages = input_data.get("messages", [])
    text = " ".join(m.get("content", "") for m in messages)
    if "bomb" in text.lower() or "weapon" in text.lower():
        return GuardrailFunctionOutput(
            output_info={"reason": "Blocked: unsafe content"},
            tripwire_triggered=True
        )
    return GuardrailFunctionOutput(tripwire_triggered=False)

guardrail = InputGuardrail(guardrail_function=check_safety)
agent = Agent(
    name="Safe Assistant",
    instructions="You are a helpful assistant.",
    input_guardrails=[guardrail]
)

MCP Integration

The Agents SDK natively supports MCP servers. This is where it gets really powerful:

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async def main():
    fs_server = MCPServerStdio(
        name="Filesystem",
        params={"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]}
    )
    async with fs_server as server:
        agent = Agent(
            name="File Assistant",
            instructions="Use filesystem tools to read and manage files.",
            mcp_servers=[server]
        )
        result = await Runner.run(agent, "List all Python files in the current directory")
        print(result.final_output)

See our MCP + OpenAI Agents guide for more details on MCP integration patterns.

Tracing

The SDK includes OpenTelemetry-based tracing. Wrap your runs in a trace to see exactly what the agent did:

from agents import gen_trace_id, trace

trace_id = gen_trace_id()
with trace(workflow_name="My Agent", trace_id=trace_id):
    result = await Runner.run(agent, "Do something complex")
print(f"View trace: https://platform.openai.com/traces/{trace_id}")

Next Steps

The OpenAI Agents SDK is designed to grow with your needs. Start with a single agent and one tool, then add handoffs, guardrails, and MCP servers as your system gets more complex. For MCP-specific patterns, check our complete MCP integration guide.