OpenAI Agents SDK: установка и создание AI-агентов на Python

OpenAI выпустила Agents SDK в марте 2025 как production-ready преемник экспериментального Swarm. За год с небольшим репозиторий собрал 27 000+ звёзд на GitHub, а сам SDK стал одним из главных инструментов для построения мульти-агентных систем на Python. В отличие от Assistants API, который требует managed-инфраструктуры OpenAI, Agents SDK — это локальная Python-библиотека с открытым исходным кодом (MIT-лицензия), которую можно ставить куда угодно и подключать к любому LLM-провайдеру.

Агентный ИИ — самая быстрорастущая статья корпоративных ИТ-бюджетов. Gartner прогнозирует, что 40% корпоративных приложений будут включать специализированных ИИ-агентов к концу 2026 года — против менее 5% в 2025-м. Grand View Research оценивает рынок ИИ-агентов в $10,91 млрд в 2026 с прогнозом до $182,97 млрд к 2033 году (CAGR 49,6%). При этом, как отмечает сводка VoxBooster, лишь 17% организаций развернули ИИ-агентов в продакшене — остальные ещё выбирают стек.

OpenAI Agents SDK — один из главных кандидатов в этом выборе. Разберём его архитектуру, установку, ключевые возможности и ограничения, чтобы понять, когда его стоит использовать, а когда — посмотреть в сторону LangGraph или CrewAI.

Архитектура: из каких примитивов собирают агентов

Agents SDK построен на минимальном наборе абстракций — разработчики OpenAI намеренно избегали раздувания API. Вот восемь ключевых концепций, из которых собирается любой workflow.

Agents — базовый строительный блок. Это LLM с инструкциями, набором инструментов и настроенными guardrails. Один агент решает одну задачу: отвечает на вопросы, генерирует код, классифицирует запросы.

Handoffs — механизм делегирования. Когда агент понимает, что запрос выходит за его компетенцию, он передаёт управление другому агенту. Альтернативный режим — agents as tools: центральный оркестратор вызывает специализированных агентов как обычные функции. В официальной документации эту схему называют «Portfolio Manager» — один координатор и несколько экспертов.

Tools — три типа: Python-функции (автоматическая генерация JSON-схемы через Pydantic), hosted tools от OpenAI (Code Interpreter, WebSearch) и MCP-серверы. MCP-интеграция — отдельная сильная сторона SDK: MCP-инструменты работают так же, как обычные функции, без дополнительной обвязки.

Guardrails — валидация на входе и выходе. Если агент получает некорректный запрос или генерирует недопустимый ответ, guardrails могут прервать выполнение до того, как результат попадёт к пользователю.

Sessions — автоматическое управление историей диалога. Из коробки — in-memory, опционально через Redis. Это решает проблему «немого агента», который не помнит, что сделал пять шагов назад.

Tracing — встроенная запись каждого вызова инструмента, перехода между агентами и шагов reasoning. Всё отображается в Agents Tracing UI — визуальном отладчике, где можно проследить полный путь выполнения запроса.

Sandbox Agents — агенты с доступом к изолированной среде (добавлены в версии 0.14.0). Полезны, когда агенту нужно работать с файловой системой, запускать команды или поддерживать состояние workspace через длинные задачи.

Realtime Agents — голосовые агенты на базе gpt-realtime-2 с автоматическим определением пауз, управлением контекстом и guardrails.

Установка в Python-окружение

SDK требует Python 3.10 или новее. Установка через pip — одна команда:

pip install openai-agents

Для голосовых агентов — pip install 'openai-agents[voice]'. Для Redis-сессий — pip install 'openai-agents[redis]'. Если используете uv, альтернатива:

uv add openai-agents

После установки нужно указать API-ключ. Если используете модели OpenAI — через переменную окружения:

export OPENAI_API_KEY=sk-...

Для сторонних провайдеров — переопределить клиент через set_default_openai_client. В обзоре на dudarik.com показан пример с Portkey как gateway для Anthropic и других моделей:

from agents import set_default_openai_client, set_default_openai_api, Agent
from openai import AsyncOpenAI

portkey = AsyncOpenAI(
    base_url="https://api.portkey.ai/v1",
    api_key=os.environ["PORTKEY_API_KEY"],
)
set_default_openai_client(portkey, use_for_tracing=False)
set_default_openai_api("chat_completions")

agent = Agent(name="Assistant", instructions="You are a helpful assistant.",
              model="gpt-4o")

Первый агент: hello world за 3 строки

Минимальный рабочий агент выглядит так:

from agents import Agent, Runner

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

result = Runner.run_sync(agent,
    "Write a haiku about recursion in programming.")
print(result.final_output)
# Code within the code,
# Functions calling themselves,
# Infinite loop's dance.

Runner.run_sync — основной метод запуска. Он принимает агента, строку запроса и опциональные параметры (контекст, конфигурация модели, настройки трейсинга). На выходе — объект RunResult с полями final_output (итоговый ответ), items (список всех шагов) и last_agent (последний выполнявшийся агент — полезно при handoffs).

Для асинхронного запуска — Runner.run() (awaitable). Для потоковой передачи — Runner.run_streamed(), который возвращает RunResultStreaming с генератором событий.

Простой способ добавить инструмент — декоратор @function_tool:

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, sunny."

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

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

Pydantic автоматически генерирует JSON-схему из сигнатуры функции и типов аргументов — никакой ручной спецификации tool-формата.

Multi-agent: handoffs и agents as tools

Главная причина использовать Agents SDK вместо прямого вызова API — координация нескольких агентов. В SDK есть два механизма.

Handoffs — агент A решает, что запрос лучше обработает агент B, и передаёт ему управление вместе с контекстом. Это похоже на эскалацию в поддержке: оператор первого уровня передаёт сложный запрос инженеру.

Agents as tools — центральный оркестратор вызывает специалистов как обычные функции. Каждый специалист получает свой фрагмент контекста и возвращает результат. Такой подход решает проблему переполнения контекстного окна: каждый агент работает в своей «песочнице» и не засоряет общий контекст.

Типичный пример из официального cookbook — инвестиционный анализ:

• Portfolio Manager — центральный оркестратор, вызывает специалистов как инструменты
• Macro Analyst — макроэкономический анализ
• Fundamental Analyst — фундаментальный анализ компаний
• Quantitative Analyst — количественные модели

Portfolio Manager не знает внутреннюю реализацию каждого специалиста. Он вызывает их через интерфейс agents as tools и агрегирует результаты. В одной цепочке задействованы все три типа инструментов: Python-функции, managed tools (Code Interpreter, WebSearch) и MCP-серверы.

Реализация handoff выглядит так:

from agents import Agent, Runner

spanish_agent = Agent(
    name="Spanish Agent",
    instructions="You speak Spanish. Translate to Spanish.",
)

french_agent = Agent(
    name="French Agent",
    instructions="You speak French. Translate to French.",
)

orchestrator = Agent(
    name="Orchestrator",
    instructions="Route the user to the correct language agent.",
    handoffs=[spanish_agent, french_agent],
)

result = Runner.run_sync(
    orchestrator,
    "Say 'Hello, how are you?' in Spanish."
)
print(result.final_output)

Orchestrator сам решает, какому агенту передать управление. Если запрос на испанском — управление получает Spanish Agent, и итоговый ответ возвращается от него. Пользователь видит только финальный результат, а вся маршрутизация остаётся внутри.

Guardrails: фильтры входа и выхода

Guardrails — это асинхронные проверки, которые выполняются параллельно с агентом. Если проверка не проходит, выполнение прерывается с указанием причины. В SDK два типа guardrails: входные (проверяют запрос до начала обработки) и выходные (проверяют ответ перед возвратом).

from agents import Agent, Runner, GuardrailFunctionOutput, input_guardrail
from pydantic import BaseModel

class MessageOutput(BaseModel):
    is_offensive: bool
    reason: str

guardrail_agent = Agent(
    name="Guardrail Agent",
    instructions="Check if the user message is offensive.",
    output_type=MessageOutput,
)

@input_guardrail
async def offensive_content_guardrail(ctx, agent, input_data):
    result = await Runner.run(guardrail_agent, input_data, ctx=ctx)
    final_output = result.final_output_as(MessageOutput)
    if final_output.is_offensive:
        return GuardrailFunctionOutput(
            output_info=final_output,
            tripwire_triggered=True,
        )
    return GuardrailFunctionOutput(
        output_info=final_output,
        tripwire_triggered=False,
    )

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

result = Runner.run_sync(agent, "Tell me about Python.")
print(result.final_output)

При срабатывании tripwire агент не выполняет инструменты и не генерирует ответ — управление сразу возвращается с сообщением о блокировке. Это эффективнее, чем пост-обработка, потому что не тратятся токены на сгенерированный и сразу отклонённый ответ.

Sandbox Agents: работа в изолированном окружении

Sandbox Agents — фича, появившаяся в версии 0.14.0. Агент получает доступ к контейнерной или локальной файловой системе, может клонировать репозитории, запускать команды, читать и писать файлы. Полезно для code review, генерации отчётов, любых задач, где агенту нужно «потрогать» файлы руками.

Вот как выглядит sandbox-агент, который клонирует репозиторий и читает README:

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import GitRepo
from agents.sandbox.sandboxes import UnixLocalSandboxClient

agent = SandboxAgent(
    name="Workspace Assistant",
    instructions="Inspect the sandbox workspace before answering.",
    default_manifest=Manifest(
        entries={
            "repo": GitRepo(
                repo="openai/openai-agents-python",
                ref="main"
            ),
        }
    ),
)

result = Runner.run_sync(
    agent,
    "Inspect the repo README and summarize what this project does.",
    run_config=RunConfig(
        sandbox=SandboxRunConfig(
            client=UnixLocalSandboxClient()
        )
    ),
)
print(result.final_output)
# This project provides a Python SDK for building
# multi-agent workflows.

UnixLocalSandboxClient работает с реальной файловой системой. Для продакшн-сценариев нужна изоляция — SDK предоставляет примитивы, но конфигурацию безопасности вы настраиваете сами. Документация рекомендует использовать Docker-контейнеры через соответствующий sandbox client.

Sessions и Tracing: память и отладка

Sessions — это автоматическое управление историей диалога между запусками. По умолчанию используется in-memory хранилище, но для production рекомендуется Redis. Сессии решают проблему контекста: агент помнит, что он делал пять запусков назад, и может ссылаться на предыдущие результаты.

Настройка Redis-сессий:

pip install 'openai-agents[redis]'

from agents import Agent, Runner, set_default_openai_key
from agents.session import RedisSessionManager

session_mgr = RedisSessionManager(
    redis_url="redis://localhost:6379"
)

result = Runner.run_sync(
    agent,
    "Continue from where we left off.",
    session_id="user-123-session"
)

Tracing — встроенная система записи всех шагов выполнения. Каждый вызов инструмента, каждый handoff, каждый guardrail записываются и отображаются в Agents Tracing UI. Это не просто логи — это визуальная временная шкала, где видно, какой агент что делал, какие инструменты вызывал и сколько времени занял каждый шаг.

Важный нюанс: трейсинг завязан на инфраструктуру OpenAI. При использовании сторонних LLM через set_default_openai_client часть данных теряется — нужно настраивать external tracing отдельно.

Сравнение: LangGraph, CrewAI, OpenAI Agents SDK

Выбор между фреймворками — не религиозный вопрос, а практический: что ближе к вашей задаче. Вот ключевые различия.

LangGraph (от создателей LangChain) — граф состояний. Вы вручную рисуете направленный граф с узлами и переходами, описываете состояние, которое передаётся между узлами, и пишете условную маршрутизацию. Это даёт максимальный контроль, но требует больше кода. LangGraph незаменим, когда у вас сложная бизнес-логика с циклами, human-in-the-loop и строгими требованиями к детерминированности. По данным NxCode, LangGraph предпочитают команды, уже использующие LangChain-экосистему (LangSmith для трейсинга, LangServe для деплоя).

CrewAI — ролевая модель. Вы описываете агентов как членов команды: каждому назначаете роль, цель, инструменты. CrewAI сам собирает pipeline из вашего описания. Прототип — 20-40 строк кода. По сообществу CrewAI, это лучший выбор для стартапов и контент-команд, где скорость важнее детерминизма. Слабое место — сложные графы: механизм Flow даёт меньше контроля, чем ручное построение графа в LangGraph.

OpenAI Agents SDK — прагматичный компромисс. Он проще LangGraph (не нужно описывать граф), но даёт больше контроля, чем CrewAI за счёт ручного определения handoffs и guardrails. Основное преимущество — встроенный трейсинг, сессии и MCP-поддержка «из коробки». SDK особенно силён в сценариях, где агенты должны работать с внешними инструментами через MCP и когда нужна детальная отладка каждого шага.

Характеристика	OpenAI Agents SDK	LangGraph	CrewAI
Метафора	Агенты + handoffs	Граф состояний	Команда с ролями
Порог входа	Низкий	Высокий	Низкий
Контроль над логикой	Средний	Максимальный	Низкий
MCP-поддержка	Встроенная	Через адаптеры	Через адаптеры
Трейсинг	Agents Tracing UI	LangSmith	CrewAI Visualizer
Провайдер-агностичность	100+ LLM	Только OpenAI по умолчанию	Любой LLM
GitHub звёзд	27K+	~100K (LangChain)	~50K
Когда выбирать	MCP-интеграции, прототипы, enterprise с трейсингом	Сложные графы, циклы, human-in-the-loop	Быстрый старт, контент-команды, стартапы

Ограничения и подводные камни

Agents SDK — молодой фреймворк, и у него есть несколько важных ограничений, которые стоит учитывать до того, как строить на нём production-систему.

Human-in-the-loop усложняет автоматизацию. Механизм есть, но требует явного проектирования точек останова. Без этого агенты могут выполнить нежелательные действия в автономном режиме. В LangGraph human-in-the-loop встроен глубже — через прерывание графа в любой точке.

Sandbox Agents — локальная файловая система. UnixLocalSandboxClient работает с реальной ФС сервера. В продакшн-сценариях нужна изоляция через Docker или Kubernetes — SDK предоставляет интерфейс, но не управляет безопасностью за вас.

Трейсинг завязан на OpenAI. При переходе на сторонние LLM встроенный Tracing UI теряет часть данных. Нужно настраивать external tracing отдельно, что добавляет инфраструктурной сложности.

Версионирование. SDK быстро развивается — за год вышли десятки релизов. Версия 0.14.0 кардинально расширила возможности (sandbox agents, realtime agents). Это значит, что код, написанный под версию 0.5, может потребовать адаптации под 0.14. Следите за changelog на GitHub.

Python 3.10+ обязателен. Это может быть ограничением для легаси-окружений на Python 3.8 или 3.9.