Skip to content
AI Agent How-To

Home › Framework how-tos

OpenAI Agents SDK: How to Add Function Tools (Python Quickstart)

Intermediate ~4 min read Last tested October 2026

Updated 2026-10-15

The OpenAI Agents SDK (openai-agents on PyPI) is a lightweight framework for tool-using agents. It runs the tool loop for you, turns Python functions into tools from their type hints, and supports handoffs between agents.

Prerequisites

  • Python 3.10+
  • OPENAI_API_KEY set in your environment

Steps

1. Install

pip install openai-agents

Note the import name is agents, not openai_agents.

2. Define tools with @function_tool

# app.py
from agents import Agent, Runner, function_tool

@function_tool
def get_order_status(order_id: str) -> str:
    """Look up the shipping status of an order by its ID."""
    fake_db = {"A100": "shipped, arriving Friday", "A101": "processing"}
    return fake_db.get(order_id, "order not found")

@function_tool
def refund_policy() -> str:
    """Return the store's refund policy."""
    return "Refunds within 30 days of delivery for unused items."

The docstring becomes the tool description and the type hints become the JSON Schema.

3. Create and run the agent

support = Agent(
    name="Support agent",
    instructions="You help customers with orders. Use tools; never invent order data.",
    tools=[get_order_status, refund_policy],
)

result = Runner.run_sync(support, "Where is order A100, and can I return it?", max_turns=6)
print(result.final_output)

max_turns caps the loop; exceeding it raises MaxTurnsExceeded.

4. Run async (for web servers)

import asyncio
async def main():
    result = await Runner.run(support, "Status of A101?")
    print(result.final_output)
asyncio.run(main())

5. Add a handoff to a specialist agent

billing = Agent(name="Billing agent", instructions="Handle billing and refund questions.",
                tools=[refund_policy])
triage = Agent(name="Triage", instructions="Route billing questions to the Billing agent.",
               handoffs=[billing], tools=[get_order_status])
print(Runner.run_sync(triage, "I was charged twice").final_output)

6. Use MCP servers as tools

from agents.mcp import MCPServerStdio

async def main():
    async with MCPServerStdio(params={"command": "python", "args": ["server.py"]}) as server:
        agent = Agent(name="Weather", instructions="Answer weather questions.", mcp_servers=[server])
        print((await Runner.run(agent, "Weather in Oslo?")).final_output)

See Build an MCP server in Python for server.py.

Common errors

ModuleNotFoundError: No module named 'agents': install openai-agents in the same virtualenv you run from. Also check you don’t have a local folder named agents/ shadowing the package.

MaxTurnsExceeded: the agent looped. See Fix: AI agent stuck in a loop.

RuntimeError: This event loop is already running (Jupyter): use await Runner.run(...) instead of run_sync.

Tracing warnings without an OpenAI key: if you use another provider, disable tracing with set_tracing_disabled(True) from agents.

More in Framework how-tos