OpenAI Agents SDK — это production-фреймворк для сборки ИИ-агентов на питоне и TypeScript. Он обёртывает Responses API в удобный рунтайм с agent loop, handoffs, guardrails, sandbox и MCP — и избавляет от необходимости писать эту инфраструктуру руками. Разбираем, когда он реально нужен, а когда хватит простого цикла вызовов API.
OpenAI Agents SDK — официальный фреймворк OpenAI для построения multi-agent рабочих процессов. Родился в 2025 году как production-версия экспериментального Swarm и с тех пор вырос в полноценный «агентный харнесс». Доступны две реализации:
openai-agents).SDK provider-agnostic: поддерживает не только Responses/Chat Completions, но и 100+ сторонних LLM через совместимые эндпоинты.
| Примитив | Что делает |
| Agent | LLM + instructions + tools + опционально structured output, handoffs, guardrails |
| Handoffs | Передача управления одного агента другому специалисту |
| Guardrails | Валидация входов и выходов агента |
| Tracing | Встроенная визуализация вызовов и отладка |
| Sessions | Сохранение истории между turn'ами (SQLite, OpenAI Conversations и др.) |
| Sandbox (Python) | Изолированная среда с файлами, shell, пакетами, snapshot и памятью |
| Subagents (Python) | Оркестрация нескольких агентов в изолированных контейнерах |
| MCP | Подключение MCP-серверов как источника инструментов |
В TypeScript-версии доступны все базовые примитивы, но sandbox и subagents пока идут впервые в Python, TypeScript-поддержка анонсирована.
Один запуск SDK = один «ход» приложения. Рунтайм крутит внутри себя цикл, пока не придёт к финальному ответу:
Всё остальное — streaming, approvals, human-in-the-loop, sessions — строится поверх этого цикла.
Для сравнения — вот та же логика, но без SDK, на чистом Responses API:
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}],
)Своё состояние, свои обработчики tool calls, свои повторы при ошибках. Нет 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 |
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="Собираешь финальный текст по фактам от Researcher.",
)
router = Agent(
name="Router",
instructions="Сначала делегируй Researcher, потом Writer.",
handoffs=[researcher, writer],
)
result = Runner.run_sync(router, input="Собери сводку по MCP-серверам")
print(result.final_output)Что вы получаете за эти ~15 строк:
C весны 2026 в Python-версии появилось нативное sandbox-окружение: контейнер с файлами, пакетами, портами, snapshot'ами и долгоживущей памятью. Это превращает SDK в «харнесс для long-running агентов» и закрывает боль. проблему: раньше приходилось самому клеить Docker, Firecracker и бэбиситтер-процессы.
Ключевые возможности sandbox-слоя:
SDK — это слой оркестрации поверх моделей и инфраструктуры. Рядом стоят соседние инструменты OpenAI:
Два-три агента внутри SDK: Researcher, Writer, Reviewer. Handoff'ы между ними, guardrails на стиль и факты. Результат складывается в Notion через MCP-сервер Notion.
Sandbox-агент с файловыми примитивами. Вы даёте ему репозиторий, бриф и тесты — он пишет код, запускает тесты, оставляет PR. Отличается от Codex тем, что это ваш собственный runtime, а не хостимый продукт.
Router-агент по типу вопроса перекидывает на специализированные: «биллинг», «техничка», «продажи». Каждый с отдельным набором инструментов и guardrails.
web_search hosted-tool + свои function tools для внутренних баз. SDK оркестрирует цикл «поиск → синтез → проверка → ответ» без ручных перепрыжек.
Agents SDK — хороший выбор для всех, кто строит «взрослые» агенты на OpenAI: инфраструктуру вы не пишете с нуля, но полный контроль над логикой остаётся в руках. Если хочется разобрать, где в вашем пайплайне хватит Responses API, а где пора брать SDK или выносить в sandbox — напишите, обсудим.
📢 Telegram-канал: t.me/pimenov_ru · ✉️ Личка: t.me/pimenov