OpenAI Agents SDK — когда нужен SDK, а когда достаточно API loop

OpenAI Agents SDK: официальный фреймворк для приложений, где модель вызывает инструменты, передаёт работу между агентами и может переносить историю или состояние между запусками. Для простой функции с одним-двумя вызовами инструментов обычно достаточно собственного цикла поверх Responses API.

Содержание

1. Что берёт на себя Agents SDK
2. Интеграция и подключение к API
3. Как работает цикл агента
4. Когда достаточно Responses API
5. Когда выбирать Agents SDK
6. Минимальный пример с передачей управления
7. Sandbox Agents для работы с файлами и shell
8. Полезные сценарии
9. Ограничения и проверка результата

Что берёт на себя Agents SDK

SDK доступен для Python и TypeScript. Его основные примитивы:

Для моделей OpenAI стандартный провайдер SDK работает с Responses API. Другие модели и провайдеры подключаются через совместимые интерфейсы и адаптеры, но их возможности и поведение нужно проверять отдельно.

Интеграция и подключение к API

SDK доступен для Python и TypeScript. В официальном TypeScript quickstart пакет устанавливается командой:

npm install @openai/agents

Для моделей OpenAI SDK использует Responses API. В ручном варианте тот же API вызывается через клиент OpenAI и endpoint v1/responses, как показано ниже. Перед запуском настройте доступ клиента к API; ключи и другие секреты не включайте в исходный код.

Как работает цикл агента

После запуска Runner.run(), Runner.run_sync() или Runner.run_streamed() SDK повторяет следующий цикл:

1. Вызывает модель для текущего агента.
2. Анализирует результат.
3. Возвращает финальный ответ, если модель выдала текст нужного типа и не запросила новые вызовы инструментов.
4. Выполняет запрошенные инструменты, добавляет их результаты и снова вызывает модель.
5. При handoff меняет текущего агента и входные данные, после чего продолжает цикл.

Количество ходов можно ограничить через max_turns. В Python SDK при превышении лимита возникает MaxTurnsExceeded, а в TypeScript публичный API содержит соответствующий тип ошибки MaxTurnsExceededError. Это страховка от зацикливания и неожиданного роста расходов.

Streaming, подтверждение рискованных действий, sessions, обработка ошибок и durable execution подключаются вокруг того же цикла.

Когда достаточно Responses API

Для небольшого сценария цикл можно оставить в коде приложения. Ниже приведён упрощённый пример паттерна с previous_response_id:

from openai import OpenAI

client = OpenAI()
tools = [my_search_tool, my_db_tool]

response = client.responses.create(
    model='gpt-5.5',
    input='Собери отчёт по кварталу',
    tools=tools,
)

while True:
    calls = [item for item in response.output if item.type == 'function_call']
    if not calls:
        break

    outputs = []
    for call in calls:
        result = run_tool(call.name, call.arguments)
        outputs.append({
            'type': 'function_call_output',
            'call_id': call.call_id,
            'output': result,
        })

    response = client.responses.create(
        model='gpt-5.5',
        previous_response_id=response.id,
        input=outputs,
        tools=tools,
    )

print(response.output_text)

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

• сопоставление вызова с нужным инструментом;
• обработку ошибок и повторные попытки;
• ограничение числа проходов;
• подтверждение рискованных действий;
• хранение состояния;
• журналирование и трассировку.

Этот подход удобен, пока логика остаётся короткой и полностью контролируется прикладным кодом.

Когда выбирать Agents SDK

Практическая граница проходит по сложности управления состоянием. Если в собственном цикле появляются маршрутизация, проверки, подтверждения, возобновление и отдельная наблюдаемость, 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],
)

support = Agent(
    name='Support',
    instructions='Решай вопросы по использованию продукта.',
)

router = Agent(
    name='Router',
    instructions='Определи тип запроса и передай его подходящему специалисту.',
    handoffs=[researcher, support],
)

result = Runner.run_sync(
    router,
    input='Найди актуальную информацию о MCP-серверах',
    max_turns=8,
)

print(result.final_output)

Этот пример показывает маршрутизацию через handoff. Handoff передаёт управление выбранному агенту, но сам по себе не задаёт обязательную последовательность нескольких ролей. Если порядок этапов должен быть детерминированным, задайте его в прикладном коде или вызывайте специалистов как инструменты из контролируемого процесса.

Sandbox Agents для работы с файлами и shell

Sandbox Agents доступны в Python и TypeScript в статусе beta. Агент получает рабочее пространство, где может искать и редактировать файлы, запускать команды, создавать артефакты и продолжать работу из сохранённого состояния.

Основные элементы sandbox-слоя:

• Manifest описывает файлы, каталоги, репозитории и другие входы рабочего пространства;
• возможности sandbox (capabilities) включают файловые инструменты, shell, память и compaction;
• sandbox client определяет среду выполнения;
• session, sessionState или snapshot позволяют последующим запускам подключиться к предыдущей работе.

Для локальной разработки документация TypeScript предлагает UnixLocalSandboxClient на macOS и Linux. На Windows нужен DockerSandboxClient или совместимый hosted-клиент. Sandbox API пока может меняться до выхода из beta.

Полезные сценарии

Триаж клиентских обращений

Задача: распределить обращения по категориям. Условие: у Router есть handoffs к агентам биллинга и технической поддержки. Действие: Router выбирает специалиста, а тот использует только назначенные ему инструкции и инструменты. Наблюдаемый результат: выбранный handoff, финальный ответ и трасса соответствуют типу обращения. Ограничение: для двух простых категорий тот же маршрут можно реализовать обычным условием без SDK.

Исследование по внутренним данным

Задача: найти сведения во внутренних источниках и подготовить ответ. Условие: доступны MCP или function tools для поиска. Действие: агент вызывает источник, затем формирует ответ на основе его результата. Наблюдаемый результат: вызовы источников и итоговый ответ можно сопоставить в трассе. Ограничение: если нужен один поиск и одно резюме, собственный API loop обычно проще.

Работа с репозиторием

Задача: изменить проект и проверить исправление. Условие: проект передан Sandbox Agent через Manifest, а у среды есть файловые инструменты и shell. Действие: агент редактирует файлы и запускает целевые тесты. Наблюдаемый результат: видны результаты команд, изменения в рабочем пространстве и сохранённое состояние запуска. Ограничение: для боевого сценария отдельно задайте разрешения, подтверждение рискованных операций и стратегию восстановления.

Ограничения и проверка результата

• Стоимость и задержка. Каждый дополнительный ход агента может вызвать модель ещё раз. Измеряйте число ходов, токены и полное время выполнения.
• Beta-интерфейсы. Sandbox Agents и другие beta-возможности могут меняться. Python SDK использует версии вида 0.Y.Z и продолжает быстро развиваться; фиксируйте проверенную версию зависимости.
• Handoff не равен бизнес-процессу. Для обязательной последовательности этапов используйте явную оркестрацию.
• Трассы могут содержать чувствительные данные. Проверьте настройку trace_include_sensitive_data и политику хранения.
• Стратегии состояния нельзя смешивать без необходимости. Sessions нельзя использовать в одном запуске вместе с conversation_id, previous_response_id или auto_previous_response_id.

Проверка результата

• В API loop успешное завершение видно по финальному response.output_text после обработки вызовов инструментов.
• В SDK результатом служит result.final_output; при превышении max_turns нужно обработать соответствующую ошибку.
• В Sandbox Agent проверьте вывод целевой команды, изменения в рабочем пространстве и возможность продолжить работу из сохранённого состояния.
• Примеры и сценарии в этом материале сверены по официальным источникам, но в рамках редакторского прохода не запускались.

Перед боевым запуском проведите одинаковый набор задач через собственный API loop и SDK. Сравните долю успешных вызовов инструментов, число ходов, задержку, стоимость, качество восстановления после прерывания и удобство диагностики. Выбирайте SDK, если его оркестрация действительно сокращает прикладной код и упрощает эксплуатацию.

Официальные источники

• Running agents — OpenAI Agents SDK for Python
• Sandbox Agents — OpenAI Agents SDK for TypeScript
• Release process and changelog — Python SDK
• GPT-5.5 — OpenAI API
• Introducing AgentKit — уведомление о прекращении Agent Builder и Evals

Следующий шаг

MCP (Model Context Protocol) — стандарт подключения ИИ к внешним системам

Связанные материалы

• Статья: Codex, Саркис и два месяца боли: как я наконец-то собрал рабочую инфраструктуру ИИ-агентов
• Блог: GPT-5.5 вышла — OpenAI снова двигает планку и ставит на агентов
• База знаний: OpenAI — линейка моделей GPT, Realtime и Images

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

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov