Каждый, кто пытался собрать агента на чистом API, знает эту боль: ручной цикл вызовов, обработка tool calls, передача состояния между ходами, отладка промежуточных шагов. Двадцать строк кода на каждый if — и в итоге получается половина фреймворка, только хуже тестированная.
OpenAI Agents SDK — это именно тот слой, который закрывает разрыв между «сырым API» и «production-агентом». Он не заменяет Responses API, а строит оркестрацию поверх него: agent loop, handoffs между специалистами, guardrails, sandbox и tracing — всё из коробки.
Ниже — разбор, когда SDK действительно нужен, а когда хватит простого цикла вызовов. Без воды, только проверенные паттерны и рабочий код.
Что такое Agents SDK
OpenAI Agents SDK — официальный production-фреймворк для сборки multi-agent систем на Python и TypeScript. Родился в 2025 году как зрелая версия экспериментального Swarm и за год вырос в полноценный оркестратор.
Доступны две реализации: Python (pip install openai-agents) и TypeScript (npm install openai-agents). SDK provider-agnostic — работает с 100+ сторонних LLM через OpenAI-совместимые эндпоинты.
Ключевое правило: SDK не заменяет Responses API — он строится поверх него. Разница в том, кто владеет циклом работы: разработчик или рунтайм SDK.
Примитивы и что они делают
| Примитив | Что делает |
|---|---|
| Agent | LLM + instructions + tools + опционально structured output, handoffs, guardrails |
| Handoffs | Передача управления одного агента другому специалисту |
| Guardrails | Валидация входов и выходов агента |
| Tracing | Встроенная визуализация вызовов и отладка |
| Sessions | Сохранение истории между turn’ами (SQLite, OpenAI Conversations и др.) |
| Sandbox | Изолированная среда с файлами, shell, пакетами, snapshot и памятью |
| Subagents | Оркестрация нескольких агентов в изолированных контейнерах |
| MCP | Подключение MCP-серверов как источника инструментов |
В TypeScript-версии доступны все базовые примитивы, но sandbox и subagents пока только в Python. Поддержка TypeScript анонсирована.
Agent loop: что происходит внутри
Один запуск SDK равен одному «ходу» приложения. Рунтайм крутит внутри себя цикл, пока не придёт к финальному ответу: вызывается текущий агент, смотрится ответ модели, выполняются tool calls, при необходимости происходит handoff. Всё остальное — streaming, approvals, human-in-the-loop, sessions — строится поверх этого цикла.
Ручной API loop: как выглядит без SDK
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-5.5",
input="Собери отчёт по кварталу",
tools=[my_search_tool, my_db_tool],
)
while not response.is_final:
for call in response.tool_calls:
result = run_tool(call)
response = client.responses.submit_tool_outputs(
response_id=response.id,
tool_outputs=[{"call_id": call.id, "output": result}],
)Свой цикл, свои обработчики, свои повторы при ошибках. Нет handoffs, guardrails и трейсинга из коробки — всё пишется руками.
Когда что выбирать
| Ситуация | Что выбирать |
|---|---|
| Одна простая фича: суммари, быстрый чат с поиском | Responses API напрямую |
| 1–2 tool calls в цикле, состояние в приложении | Responses API, свой мини-луп |
| Несколько ролей агентов, handoff друг другу | Agents SDK |
| Нужны guardrails на вход/выход | Agents SDK |
| Длинные задачи (минуты+), прерывания, возобновления | Agents SDK + sandbox + checkpointing |
| Агент ходит в файлы и терминал | Agents SDK Sandbox (Python) |
| MCP-серверы как источник инструментов | Agents SDK с нативным MCP |
| Реалтайм голос/видео | Realtime API, иногда в связке с SDK |
| Визуальный builder, без кода | Agent Builder + ChatKit |
Правило большого пальца: если цикл оркестрации сложнее двух-трёх if’ов, вы уже пишете половину SDK руками. Лучше взять готовый.
Минимальный пример
from agents import Agent, Runner, function_tool
@function_tool
def search_kb(query: str) -> str:
return run_kb_search(query)
researcher = Agent(
name="Researcher",
instructions="Ищешь факты в базе знаний и приводишь их кратко.",
tools=[search_kb],
)
writer = Agent(
name="Writer",
instructions="Собираешь финальный текст по фактам.",
)
router = Agent(
name="Router",
instructions="Сначала делегируй Researcher, потом Writer.",
handoffs=[researcher, writer],
)
result = Runner.run_sync(router, input="Собери сводку по MCP-серверам")
print(result.final_output)За эти ~15 строк получаем: рутинг между двумя агентами, автоматическое выполнение tool calls, tracing из коробки, сохранение сессий при подключённом backend, подключение любых function tools и MCP-серверов.
Sandbox и долгоживущие агенты
С весны 2026 в Python-версии появилось нативное sandbox-окружение: контейнер с файлами, пакетами, портами, snapshot’ами и памятью. Это превращает SDK в полноценный runtime для long-running агентов — без необходимости самостоятельно клеить Docker и бэбиситтер-процессы.
- Изолированное выполнение кода и shell-команд
- Файловые примитивы read/write/edit в стиле Codex
- Кратко- и долгосрочная память агента как first-class сущность
- Checkpointing и durability — задача переживает перезапуск
- Subagents: распараллеливание по нескольким изолированным контейнерам
Sandbox пока только в Python. Для TypeScript-проектов либо ждём порт, либо используем внешние платформы (E2B, Modal) через tool-calls.
Место в пайплайне
SDK — слой оркестрации поверх моделей и инфраструктуры. Рядом стоят: Codex (cloud coding-агент с собственным sandbox), Responses API (транспорт под капотом SDK), MCP (подключается нативно), Realtime API (голос/видео), Agent Builder (no-code UI поверх той же идеологии).
Практические сценарии
Контент-пайплайн с ролями
Два-три агента: Researcher, Writer, Reviewer. Handoffs между ними, guardrails на стиль и факты. Результат складывается в Notion через MCP-сервер.
Coding агент под проект
Sandbox-агент с файловыми примитивами. Получает репозиторий, бриф и тесты — пишет код, запускает тесты, оставляет PR. Отличается от Codex тем, что это собственный runtime, а не хостимый продукт.
Клиентский суппорт с триажем
Router-агент по типу вопроса перенаправляет на специализированных: биллинг, техподдержка, продажи. Каждый с отдельным набором инструментов и guardrails.
Ресёрч-агент с веб-поиском
web_search hosted-tool + function tools для внутренних баз. SDK оркестрирует цикл «поиск → синтез → проверка → ответ» без ручных перепрыжек.
Ограничения
| Ограничение | Пояснение |
|---|---|
| TypeScript догоняет Python. | Sandbox, subagents и часть новых примитивов приходят в Python раньше. |
| Latency: | каждый проход цикла — вызов API. Для быстрых сценариев лучше Responses API без лишнего слоя. |
| Стоимость: | multi-agent хороводы расходуют токены в несколько раз быстрее одного большого агента. |
| Self-hosted LLM работают только через OpenAI-совместимые endpoints. | |
| Нет визуального конструктора. | Для no-code — Agent Builder + ChatKit. |
| Не заворачивать простой хелпер с поиском за SDK | Responses API проще и быстрее |
| Не строить «свой SDK» поверх LangChain, если уже живёте в экосистеме OpenAI | |
| Не игнорировать guardrails | продакшен без них хорош до первого интересного вызова |
| Не размножать агентов без причины | каждый handoff = лишний вызов, latency и токены |
| Не запускать sandbox-агентов без checkpointing в проде |
Чеклист
| Проверка | Что сделать |
|---|---|
| Разовый промпт с 1–2 tool calls? | Responses API |
| Несколько ролей или явный routing? | Agents SDK |
| Guardrails, tracing и sessions из коробки? | Agents SDK |
| Работа с файлами или shell? | Agents SDK Sandbox (Python) |
| Задача идёт десятки минут или часы? | SDK + checkpointing + sandbox |
| MCP-серверы как источник инструментов? | Agents SDK с нативным MCP |
| Нужен визуальный конструктор без кода? | Agent Builder, а не SDK |