OpenAI Agents SDK по частям: как устроены цикл, инструменты, передачи, проверки и подтверждения

OpenAI Agents SDK пользуются 23,8% разработчиков, ответивших на вопрос об агентных фреймворках в опросе Stack Overflow 2026, — второе место после LangChain. При этом за 19 месяцев библиотека так и не дошла до версии 1.0, а модель, которую она выбирает по умолчанию, с мая по август сменилась дважды. Ниже каждая часть SDK объяснена сначала простыми словами, потом — названиями из кода. Всё сверено с документацией и исходниками версии 0.24.0 от 15 октября 2026 года.

Коротко

• Агент — это модель с инструкциями и инструментами. Цикл Runner спрашивает её «что дальше?», пока не придёт финальный ответ, не понадобится подтверждение человека или не кончится лимит в 10 ходов.
• В SDK восемь частей: Agent, Runner, Tools, Handoffs, Context, Guardrails, Sessions с RunState и Tracing.
• Проверки (guardrails) ловят меньше, чем обещает название: проверка входа стоит только у первого агента, а проверки инструментов не видят передачи разговора и встроенный shell.
• У версии 0.x есть цена: модель по умолчанию менялась дважды за три месяца. Задавайте модель явно и закрепляйте версию.
• С моделями не от OpenAI SDK работает через совместимые API, но теряет серверные инструменты, а трассировку придётся отключить или заменить.

01 · Простыми словами

Источник: документация OpenAI Agents SDK, разделы Agents и Running agents.

Представьте помощника службы поддержки. У него есть должностная инструкция («помогай с заказами»), «мозг» — языковая модель — и несколько разрешённых действий, например найти заказ по номеру. В SDK такая связка называется Agent.

Сама модель ничего не делает. Её нужно спросить, прочитать ответ, выполнить действие, которое она попросила, и вернуть ей результат. Этим занимается Runner — цикл. Он спрашивает модель, смотрит, что вернулось, действует и спрашивает снова. Цикл заканчивается финальным ответом, паузой на подтверждение человека или лимитом ходов.

Всё остальное в SDK либо добавляет этому циклу память, либо ставит вокруг него проверки, либо записывает, что произошло.

02 · Восемь частей на одной схеме

Источник: документация OpenAI Agents SDK, версия 0.24.0.

Часть	Простыми словами	В коде
Agent	Инструкция, модель и разрешённые действия	Agent(name, instructions, model, tools, handoffs, output_type, ...)
Runner	Цикл, который ведёт разговор	Runner.run(), run_sync(), run_streamed()
Tools	Что агент умеет делать	@function_tool, инструменты OpenAI, agent.as_tool()
Handoffs	Передать разговор специалисту	handoffs=[...], handoff()
Context	Объекты вашего приложения для инструментов	RunContextWrapper[T]
Guardrails	Проверки, которые могут остановить прогон	проверки входа, ответа и инструментов
Sessions и RunState	Память разговора и сохранённый прогон на паузе	SQLiteSession, RunState
Tracing	Запись каждого шага	трассы и спаны (spans), включено по умолчанию

instructions — это строка или функция, которая собирает промпт из контекста. output_type определяет, что считать «готово». Без него финальный ответ — обычный текст. С ним модель обязана вернуть объект нужного типа; подходит любой тип, который понимает Pydantic.

03 · Один прогон, шаг за шагом

Источник: раздел Running agents; DEFAULT_MAX_TURNS в src/agents/run_config.py.

Документация описывает цикл четырьмя шагами:

1. Вызвать модель текущего агента с текущим входом.
2. Если вернулся текст нужного типа и нет вызовов инструментов — это финальный ответ, прогон окончен.
3. Если модель просит передачу — сменить текущего агента и пойти на следующий круг.
4. Если модель просит инструменты — выполнить их все, добавить результаты ко входу и пойти на следующий круг.

Ход — это один вызов модели. По умолчанию их 10 (DEFAULT_MAX_TURNS в коде), после лимита Runner выбрасывает MaxTurnsExceeded. max_turns=None снимает лимит, а error_handlers позволяют вернуть запасной ответ вместо исключения.

В результате прогона есть не только ответ. final_output показывают человеку. new_items — список всех шагов с агентом, инструментом и передачей. to_input_list() даёт готовый вход для следующего хода, если историю вы храните сами.

04 · Четыре вида инструментов

Источник: раздел Tools, версия 0.24.0.

• Функции (function tools). Достаточно повесить @function_tool на функцию Python. Имя берётся из названия функции, описание — из docstring, схема параметров — из аргументов.
• Инструменты на серверах OpenAI (hosted tools). Веб- и файловый поиск, интерпретатор кода, hosted MCP, генерация картинок, поиск инструментов и programmatic tool calling. Работают только через Responses API.
• Локальные инструменты. Computer и apply_patch выполняются в вашем окружении, shell — локально или в контейнере OpenAI. Локальные shell и apply_patch по умолчанию не требуют подтверждения. Документация прямо предупреждает: подтверждение — это не песочница («SDK approval does not provide a sandbox»).
• Агент в роли инструмента. agent.as_tool() позволяет одному агенту вызвать другого ради узкой подзадачи.

Если функция-инструмент падает, модели по умолчанию сообщают, что произошла ошибка, и цикл продолжается. С failure_error_function=None ошибка поднимается в ваш код.

05 · Передача разговора или агент-инструмент

Источник: разделы Handoffs и Multi-agent; docstring Agent.as_tool.

Для модели передача (handoff) — просто ещё один инструмент. Передача агенту Refund Agent выглядит как инструмент transfer_to_refund_agent. Когда модель его вызывает, Runner меняет агента, и новый агент видит весь разговор. Фильтр input_filter, например remove_all_tools, урезает то, что он увидит: убирает вызовы инструментов, а текст внутри сообщений оставляет как был. on_handoff запускает ваш код в момент переключения.

Агент в роли инструмента получает только сгенерированный вход, а разговор остаётся у менеджера. Берите его, когда специалист должен ответить на узкий вопрос, а итоговый ответ пишет менеджер. Передача нужна, когда маршрутизация и есть задача и дальше с человеком говорит специалист. Шаблоны сочетаются: сортировщик передаёт разговор специалисту, а тот вызывает других агентов как инструменты.

06 · Два значения слова «контекст»

В SDK это слово означает две разные вещи, и путаница между ними приводит к ошибкам.

• Локальный контекст — любой объект, который вы передаёте в Runner.run(..., context=...): текущий пользователь, подключение к базе, настройки. Его получает каждый инструмент, хук и передача в обёртке RunContextWrapper. Документация однозначна: этот объект в модель не отправляется.
• Контекст модели — то, что модель действительно читает: инструкции, вход и историю, элементы сессии, результаты инструментов. Чтобы модель узнала факт, его нужно положить сюда.

Документация отдельно предупреждает: когда прогон ставят на паузу ради подтверждения и сохраняют RunState, локальный контекст сохраняется вместе с ним. Секреты туда класть не стоит.

07 · Проверки: три вида и что они пропускают

Источник: раздел Guardrails, версия 0.24.0.

Проверка (guardrail) — функция, которая смотрит на что-то и может сработать (tripwire): выбросить исключение и остановить прогон. Видов три.

• Проверка входа смотрит на запрос человека. Работает только у первого агента в цепочке.
• Проверка ответа смотрит на финальный ответ. Работает только у агента, который его дал.
• Проверки инструментов смотрят на вход и выход каждого вызова функции. Могут пропустить вызов, подменить результат или остановить прогон.

Пробелы в покрытии описаны в самой документации по проверкам. Передачи идут своим путём, проверки инструментов на них не действуют. Инструменты на серверах OpenAI и встроенные исполнители (ComputerTool, ShellTool, ApplyPatchTool, LocalShellTool) через проверки инструментов не проходят, а у Agent.as_tool() своих проверок инструментов нет. Для схем с несколькими агентами документация советует ставить проверки на инструменты и не полагаться только на проверки входа и ответа.

Важен и момент запуска. Проверки входа по умолчанию идут параллельно с агентом. Это быстро, но если проверка сработала, агент мог уже потратить токены и вызвать инструменты. Перед инструментами, которые отправляют, платят или удаляют, ставьте run_in_parallel=False: тогда проверка заканчивается раньше, и при срабатывании агент вообще не стартует. Проверки ответа всегда идут после агента.

08 · Память и подтверждения

Источник: разделы Sessions и Human-in-the-loop.

Сессии дают агенту память между прогонами. Перед прогоном сессия подгружает историю, после — сохраняет всё новое. Готовые хранилища: SQLite, Redis, SQLAlchemy, MongoDB, Dapr и Conversations API от OpenAI.

Состояние разговора можно держать четырьмя способами: своим списком, сессией, conversation_id или previous_response_id. Выберите один на разговор: документация предупреждает, что смесь приводит к дублированию контекста.

Подтверждения устроены так. Инструмент помечают needs_approval=True. Когда модель его вызывает, прогон встаёт на паузу, а ожидающие вызовы появляются в result.interruptions. Прогон получают через result.to_state(), сериализуют в JSON и кладут в базу или очередь. Человек одобряет или отклоняет, после чего прогон продолжается вызовом Runner.run(agent, state). Если ждать нужно часами или днями и прогон должен пережить перезапуск, документация называет интеграции с Temporal, Restate, DBOS и Dapr.

09 · Стриминг, трассировка и хуки

Стриминг. Runner.run_streamed() отдаёт три вида событий: сырые токены для интерфейса, завершённый шаг (вызван инструмент, запрошена передача) и смену агента после передачи. Прогон закончен, только когда закончился итератор событий.

Трассировка включена по умолчанию. Каждый прогон — трасса, а каждый агент, вызов модели, инструмент, проверка и передача — спан (span) внутри неё. Трассы уходят в панель OpenAI; add_trace_processor добавляет другие системы, в документации их около тридцати. Отправку в OpenAI он при этом оставляет; чтобы трассы туда не уходили, процессоры заменяют через set_trace_processors(). Два умолчания стоит решить сознательно. trace_include_sensitive_data равен True, то есть входы и выходы модели и инструментов сохраняются. При режиме Zero Data Retention трассировка недоступна.

Хуки запускают ваш код, когда агент стартует или заканчивает, вокруг каждого вызова модели и инструмента и при каждой передаче.

10 · Модели и цена версии 0.x

Источник: Breaking change changelog в release notes SDK.

По умолчанию SDK работает с OpenAI через Responses API — он нужен для инструментов на серверах OpenAI и серверного хранения диалога. Модель через Chat Completions работает с совместимыми провайдерами, но поля, которых нет в Chat Completions, молча отбрасывает. Адаптеры LiteLLM и Any-LLM подключают других провайдеров; документация называет их бета-интеграциями без гарантий (best-effort).

Если у агента не указана модель, SDK выбирает её сам, и это значение менялось дважды: на gpt-5.4-mini в 0.16.0 (7 мая) и на gpt-5.6-luna в 0.20.0 (11 августа). По собственному правилу проекта минорные версии могут менять поведение без обратной совместимости, и release notes это подтверждают:

Версия	Дата	Что изменилось
0.7.0	23.01.2026	Вложенная история передач выключена по умолчанию; у gpt-5.1/5.2 reasoning по умолчанию none
0.15.0	01.05.2026	Отказ модели — исключение ModelRefusalError, а раньше пустой ответ или повтор до лимита
0.16.0	07.05.2026	Модель по умолчанию gpt-4.1 → gpt-5.4-mini
0.20.0	11.08.2026	Модель по умолчанию → gpt-5.6-luna
0.21.0	15.08.2026	Нужен openai v3; свои HTTP-клиенты переписываются с httpx на httpx2

Практическое правило: указывайте model= у каждого агента, закрепите SDK на 0.24.* и читайте changelog перед каждым обновлением.

Вокруг SDK тоже всё меняется. OpenAI закрывает Agent Builder, визуальный редактор агентов, 30 ноября 2026 года. Для разработчиков путь миграции — этот SDK, для команд без кода — ChatGPT Workspace Agents; экспорт в код, по словам OpenAI, граф процесса не переносит. Сам SDK растёт за пределы текстового цикла: sandbox-агенты (0.14, апрель 2026) получают рабочее пространство с файлами и shell, а programmatic tool calling (0.19, июль 2026) позволяет модели писать JavaScript, который вызывает разрешённые инструменты в изолированной среде V8.

11 · Что это значит для команд в России

Если модели OpenAI вам не подходят или данные должны оставаться внутри компании, SDK можно использовать с другими провайдерами, с оговорками.

• Модели. SDK подключается к провайдерам, у которых есть OpenAI-совместимый endpoint: через set_default_openai_client или OpenAIChatCompletionsModel. В документации Yandex AI Studio такие API заявлены. Работают ли через них вызовы инструментов и структурированный ответ вместе с SDK, проверьте на своём сценарии до старта: документация SDK предупреждает, что у других провайдеров часть функций работает иначе.
• Что теряется. Инструменты на серверах OpenAI (веб- и файловый поиск, интерпретатор кода, hosted MCP) и серверное хранение диалога доступны только через Responses API. Историю придётся держать в своей сессии: SQLite, Redis, SQLAlchemy или MongoDB.
• Трассировка. По умолчанию трассы отправляются в OpenAI, а без ключа OpenAI SDK выдаёт ошибки трассировки — документация описывает это прямо. Отключите её (set_tracing_disabled(True)) или замените процессоры через set_trace_processors() и отправляйте трассы в свою систему наблюдаемости: add_trace_processor() оставляет отправку в OpenAI включённой.
• Подтверждения по образцу Т-Инвестиций. Т-Инвестиции открыли клиентам доступ внешних ИИ-агентов к брокерскому счёту через MCP с тремя уровнями прав, от «только просмотр данных» до переводов между своими счетами, и правилом: агент не выполняет операции без подтверждения человека (CNews, сентябрь 2026). В SDK похожий дизайн собирается так: needs_approval на рискованных инструментах, is_enabled прячет инструменты, которые не положены уровню прав, а сумму и счёт в аргументах проверяет ваш код внутри инструмента или проверка инструмента — документация прямо говорит, что is_enabled аргументы не авторизует.
• Контур контроля снаружи модели. По данным ComNews, Яндекс, МТС, Т1 и Сбер строят системы, которые ставят под контроль действия агента и при необходимости подключают человека; в Т1 говорят, что спрос на такие механизмы за год вырос примерно втрое. Проверки SDK — часть такого контура, но не весь: передачи и встроенный shell они не покрывают, поэтому права и изоляцию задаёт ваше окружение.

12 · Когда брать и что настроить сразу

	LangGraph	OpenAI Agents SDK
Форма	Граф, который вы описываете	Цикл с передачами
Состояние	Чекпоинт после каждого шага	Сессия плюс RunState на паузе
Долгое ожидание	Встроено в среду исполнения	Через Temporal, Restate, DBOS или Dapr
Версия	1.x с октября 2025 года	0.x, минорные версии меняют поведение

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

Взять другой фреймворк или заложить лишнюю работу стоит, если большинство моделей не от OpenAI, если вы работаете в режиме Zero Data Retention или если состояние нужно сохранять после каждого шага.

Четыре настройки, которые стоит задать явно до запуска:

1. model= у каждого агента и SDK, закреплённый на 0.24.*.
2. run_in_parallel=False у проверок входа перед инструментами, которые отправляют, платят или удаляют.
3. Проверки инструментов на каждой функции в схемах с несколькими агентами, а для shell, computer и apply_patch — подтверждения или настоящая песочница.
4. workflow_name для трасс и осознанное решение по trace_include_sensitive_data — или своя система трассировки.

Разбор входит в серию об агентных фреймворках в реальной работе; серия начинается с рейтинга десяти фреймворков по доказательствам из реальных внедрений. А прежде чем доверять агенту, проверьте его так же, как проверяете релиз.

FAQ

Что такое OpenAI Agents SDK? Библиотека OpenAI для Python и TypeScript, на которой собирают агентов: модель с инструкциями и инструментами работает в цикле Runner. Сверху — передача разговора между агентами, проверки (guardrails), память сессий, подтверждения человеком и трассировка. По умолчанию работает с моделями OpenAI, другие подключаются через совместимые API и бета-адаптеры.

Чем передача разговора (handoff) отличается от агента в роли инструмента? При передаче новый агент получает всю историю и дальше сам ведёт разговор. Агент в роли инструмента получает только сгенерированный вход, отвечает на один подвопрос, а разговор остаётся у исходного агента.

Проверяют ли guardrails каждого агента и каждый инструмент? Нет. Проверка входа работает только у первого агента в цепочке, проверка ответа — только у агента, который дал финальный ответ, проверки инструментов — только у ваших функций. Передачи, инструменты на серверах OpenAI и встроенные shell, computer и apply_patch через проверки инструментов не проходят.

Сколько ходов агент делает до остановки? По умолчанию 10. Ход — один вызов модели. После лимита Runner выбрасывает MaxTurnsExceeded; лимит снимается параметром max_turns=None, а вместо исключения можно вернуть запасной ответ через error_handlers.

Можно ли использовать OpenAI Agents SDK с российскими моделями? SDK подключается к провайдерам с OpenAI-совместимым endpoint, и в документации Yandex AI Studio такие API заявлены. Работают ли через них вызовы инструментов и структурированный ответ вместе с SDK, проверьте на своём сценарии. При таком подключении теряются инструменты на серверах OpenAI и серверное хранение диалога, а трассировку нужно отключить или заменить процессоры через set_trace_processors(): по умолчанию трассы уходят в OpenAI.