OpenAI Agents SDK: официальный фреймворк для мультиагентных систем на Python

У OpenAI есть свой ответ на вопрос «как собирать мультиагентные системы» — Agents SDK. Это открытый Python-фреймворк под лицензией MIT: лёгкий, почти без зависимостей, но с полным набором деталей для production. В его основе лежит простая идея: агент — это LLM, настроенная инструкциями, инструментами, проверками входа и выхода (guardrails) и правилами передачи задач другим агентам. SDK поставляется через PyPI, работает с OpenAI Responses и Chat Completions API, а через адаптеры — ещё и с сотней других LLM. Есть и версия для JavaScript/TypeScript — openai-agents-js.

Ключевые концепции

В SDK восемь основных строительных блоков:

Разница между handoff и «агентом как инструментом» простая. Handoff — это полная передача управления: первый агент уходит, второй отвечает пользователю. Agent-as-tool — это вызов подчинённого агента за ответом, после которого управление возвращается.

Установка

Нужен Python 3.10 или новее. Классический способ через venv:

python -m venv .venv
source .venv/bin/activate
pip install openai-agents

Или через uv:

uv init
uv add openai-agents

Есть необязательные группы зависимостей: voice для голосовых агентов и redis для хранения сессий в Redis. Ставятся они так: pip install 'openai-agents[voice]'.

Первый агент

Минимальный рабочий пример занимает четыре строки. Перед запуском задайте переменную окружения OPENAI_API_KEY:

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)

Runner умеет работать синхронно, как в примере, и асинхронно. Тем, кто живёт в Jupyter, проще взять готовый ноутбук с примером.

По README у SDK четыре основных сценария запуска: обычный текстовый агент, агент в песочнице, realtime-агент и голосовой конвейер. Первые два покрывают большинство задач, последние два — отдельные разделы ниже.

Guardrails и человек в цикле

У агентов, работающих с внешним миром, две вечные проблемы: на вход может прийти мусор, а на выход — что-то опасное. Guardrails решают обе: это настраиваемые проверки входных и выходных данных, которые срабатывают до и после вызова модели.

Когда агент получает право действовать — запускать код, менять файлы, тратить деньги, — возникает и другой вопрос: кто подтверждает важные шаги. Для этого в SDK встроены механизмы human in the loop: выполнение можно поставить на паузу, показать человеку, что агент собирается сделать, и дождаться решения.

Песочница, realtime и голос

Помимо обычных текстовых агентов, SDK даёт три специализированных типа.

Sandbox agents — агенты с доступом к контейнеру. Они могут читать файлы, запускать команды и применять патчи, сохраняя состояние рабочей области между шагами. Это делает их подходящими для длинных задач вроде разбора репозитория. На macOS и Linux есть локальный UnixLocalSandboxClient, на Windows — DockerSandboxClient из опциональной группы docker.

Realtime agents — голосовые и мультимодальные агенты с низкой задержкой поверх WebSocket. Они работают на сервере и поддерживают все обычные возможности агентов: инструменты, handoffs, guardrails.

Voice pipelines — конвейер «речь → агент → речь». Сначала speech-to-text, затем обычный агентный workflow, затем text-to-speech. Внутрь конвейера можно положить любой обычный Agent:

from agents import Agent
from agents.voice import AudioInput, SingleAgentVoiceWorkflow, VoicePipeline

agent = Agent(name="Assistant", instructions="You are a helpful voice assistant.")
pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent))

result = await pipeline.run(AudioInput(buffer=audio_bytes))
async for event in result.stream():
    ...

Сессии и трассировка

Две вещи, которые обычно приходится дописывать руками, здесь встроены.

Sessions автоматически хранят историю диалога между запусками агента. Не нужно собирать сообщения в список и передавать их обратно — фреймворк делает это сам. Хранилище подключаемое: от простого файлового до Redis через опциональную группу зависимостей.

Tracing записывает каждый запуск агента: какие вызовы инструментов случились, какие handoffs сработали, сколько это заняло. Без этого отладка мультиагентной системы превращается в угадывание. Трассировки открываются в специальном UI — по ним видно, где workflow тормозит или ломается. Данные можно экспортировать и во внешние системы.

Работа с другими LLM

Название говорит «OpenAI», но SDK провайдер-агностичен. Через интеграции any-llm и LiteLLM фреймворк работает с сотней моделей разных провайдеров. Для MCP-инструментов используется официальный MCP Python SDK, а схемы инструментов строятся на Pydantic.

Такая архитектура позволяет начать на моделях OpenAI и переключить провайдера точечной правкой конфигурации, не переписывая логику агентов.

Что ещё посмотреть

• Документация — подробные руководства по каждой концепции.
• Каталог примеров — рабочие сценарии: от hello world до исследовательских агентов и голосовых приложений.
• Issues на GitHub — сюда принимают баг-репорты и пожелания.

Одно ограничение стоит знать заранее: pull requests от внешних разработчиков проект не принимает — только от коллабораторов репозитория. Это оговорено в CONTRIBUTING.md. Код при этом открыт под MIT, так что форкать и расширять SDK никто не запрещает.