# OpenAI Agents SDK или Claude Agent SDK

> Сравниваем OpenAI Agents SDK и Claude Agent SDK: абстракции, инструменты, подтверждения, наблюдаемость, привязку к поставщику и выбор для команды.

OpenAI Agents SDK и Claude Agent SDK запускают циклы с вызовом инструментов, сохраняют контекст диалога, поддерживают MCP и позволяют человеку подтверждать рискованные действия. Из-за этого внешнего сходства компании часто принимают неверные решения. Существенная разница кроется в том, где каждый SDK предполагает выполнять работу и какие свойства среды исполнения становятся частью вашего продукта.

Архитектура OpenAI начинается с агента приложения: инструкции, типизированные инструменты, передача управления, проверки, сессии и исполнитель. Архитектура Claude начинается со среды исполнения Claude Code: модель работает со встроенными инструментами для файлов, командной строки, поиска и редактирования, а вокруг нее действуют хуки, разрешения, настройки проекта, навыки и субагенты. Выбирайте OpenAI, если хотите собрать продуктовый процесс из явных примитивов. Выбирайте Claude, если задача похожа на работу самостоятельного оператора в настоящей рабочей среде. Если не подходит ни одно описание, используйте API модели более низкого уровня и управляйте циклом сами.

## За одинаковыми названиями SDK скрываются разные продукты

Первое сравнение нужно проводить не между OpenAI и Anthropic, а между оркестрацией приложения и встроенной средой для работы с компьютером.

Документация OpenAI Agents SDK называет основной набор намеренно небольшим: агенты, агенты в роли инструментов или передача управления, а также проверки. `Runner.run()` управляет циклом, вызывает инструменты, возвращает результаты модели и останавливается, когда запуск выдает итоговый ответ. Сессии добавляют память. Трассировка фиксирует генерации, вызовы инструментов, проверки и передачу управления. Это фреймворк общего назначения для приложений, хотя по умолчанию модели OpenAI работают через Responses API.

В обзоре Claude Agent SDK сказано, что приложение получает те же инструменты, агентный цикл и управление контекстом, на которых работает Claude Code. Этой фразе стоит уделить больше внимания, чем обычно уделяют таблицам функций. SDK не похож на обычный клиент Anthropic API с удобным циклом. Он оборачивает готового оператора, который умеет читать и менять файлы, выполнять команды, искать данные, управлять контекстом и использовать конфигурацию Claude Code.

Сама Anthropic отделяет Agent SDK от Client SDK и Managed Agents. Client SDK предназначен для прямых вызовов Messages API, когда цикл реализуете вы. Managed Agents рассчитан на длительные задачи, при которых Anthropic управляет сессиями и песочницами. Agent SDK работает в вашем процессе, а хостинг и изоляция остаются вашей обязанностью. Если смешать эти три продукта в одной оценке, выводы о развертывании и привязке к поставщику потеряют смысл.

Практическая проверка проста. Опишите единицу работы, не упоминая модель. «Распределить обращение в поддержку, вызвать нашу функцию возврата и вернуть типизированное решение» похоже на агента приложения. «Изучить репозиторий, запустить тесты, исправить сломанные файлы и описать изменения» похоже на оператора рабочей среды. Оба SDK можно заставить работать в чужой для них роли, но объем связующего кода покажет, с какой абстракцией вы боретесь.

Для большинства команд поддержка языков не решит спор. Оба проекта выпускают библиотеки для Python и TypeScript. Важнее понять, какая среда будет владеть длительной работой. Серверный запрос может выдержать асинхронного исполнителя, но не дочерний процесс с доступом к репозиторию. Очередь задач может хорошо подойти агенту рабочей среды, однако потребует явной отмены, очистки и ограничений параллельности. Определите модель процессов до прототипа: поздний перенос агента из обработчика запроса в изолированный воркер одновременно меняет хранение сессий, потоковую выдачу, подтверждения и восстановление после ошибок.

## OpenAI дает явные примитивы рабочего процесса

Абстракции OpenAI показывают поток управления прямо в коде приложения. `Agent` хранит инструкции, инструменты, необязательный структурированный результат, настройки модели, проверки и возможные передачи управления. `Runner` выполняет агента. Специалист может стать инструментом менеджера, либо передача управления сделает его активным участником диалога.

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

Проверки тоже действуют точечно, а не волшебным образом. В документации OpenAI указано, что входные проверки запускаются только у первого агента в цепочке, а выходные только у последнего. Проверки инструментов охватывают каждый вызов пользовательской функции, но не распространяются автоматически на передачу управления и все встроенные инструменты. Команда, которая увидит строку «проверки поддерживаются» и решит, что защищены все границы, оставит брешь. Проверяйте права внутри реализации инструмента, даже если рядом есть ограничитель, видимый модели.

Типизированные инструменты хорошо подходят обычным серверным приложениям. В Python декорированная функция может получить схему из аннотаций и проверять входные данные через Pydantic. В TypeScript параметры описывает Zod или JSON Schema. Агентный слой остается рядом с теми же сервисными функциями, которые вызывает остальное приложение.

SDK не требует, чтобы каждый агент использовал модель OpenAI. В версии для Python есть точки подключения поставщиков моделей и бета-адаптеры для смешанных конфигураций. Официальное руководство по моделям предупреждает, что адаптер не гарантирует одинаковые возможности: на другом сервере могут исчезнуть структурированный вывод, встроенный поиск, мультимодальные данные и поведение, привязанное к Responses API. Я согласен с предупреждением, но формулирую жестче. Адаптер модели снижает зависимость на транспортном уровне, однако не делает семантику поставщиков переносимой.

Выбирайте такую архитектуру, если хотите, чтобы рецензент видел в обычном коде короткий граф именованных агентов и инструментов. Она особенно удобна для продуктов по схеме запрос-ответ, сервисных процессов, голосовых агентов и маршрутизации, где каждое действие с побочным эффектом уже закрыто API приложения.

## Claude дает оператора с рабочей средой

В абстракциях Claude рабочая среда находится в центре запуска. Простая функция `query()` выполняет разовую задачу. `ClaudeSDKClient` поддерживает двустороннюю сессию с дополнительными сообщениями, потоковой выдачей, прерыванием и возобновлением. `ClaudeAgentOptions` задает инструменты, системные инструкции, разрешения, серверы MCP, хуки, субагентов, бюджеты и источники настроек.

Встроенный набор инструментов меняет стоимость первого прототипа. Агенту для репозитория нужны чтение и поиск по файлам, редактирование, команды оболочки и обычно доступ к интернету. Claude дает этот рабочий словарь сразу, поэтому не нужно оборачивать каждую операцию с файлами в бизнес-функцию. Модель и среду также проектировали вместе для задач, где агент должен изучить незнакомое пространство и сам выбрать следующее действие.

За удобство приходится платить операционной сложностью. SDK запускает цикл Claude Code в вашем процессе, а документация пакета Python описывает ошибки отсутствующей CLI, разрыва соединения, сбоя процесса и неверного JSON от CLI. Пакет может включать совместимую CLI, но вы все равно обслуживаете среду, похожую на дочерний процесс, с рабочей директорией, переменными окружения, разрешениями и выполнением команд. Контейнер, который безопасно обслуживает веб-API, может оказаться плохой песочницей для агента с доступом к оболочке.

Субагенты Claude ближе к делегированным работникам в общей среде, чем к передаче управления в OpenAI. Вы задаете специалистам инструкции и доступные инструменты, после чего основной агент поручает им узкие задачи. Навыки, команды со слешем, файлы памяти, конфигурация проекта и плагины тоже могут попасть в среду исполнения. Для внутренней автоматизации разработки это удобно: агент использует те же соглашения, которые разработчики уже применяют в Claude Code.

Здесь же появляется риск скрытых зависимостей. Если поведение в продакшене зависит от навыка в домашней директории, незакрепленной версии плагина или локальных настроек разработчика, тестовый стенд не описывает развернутого агента. Задавайте `setting_sources` явно, упаковывайте обязательную конфигурацию проекта и запускайте продакшен-воркеры с чистой домашней директорией. Считайте каждую загруженную инструкцию, хук и описание инструмента кодом, которому нужна версия.

Claude подходит, когда агент должен исследовать и менять среду: обслуживать код, расследовать инцидент, исправлять файлы данных, проводить миграцию или выполнять многоэтапные операции в контролируемом рабочем пространстве. Для клиентского процесса из трех функций та же среда может оказаться лишним грузом.

## Происхождение инструментов важнее их количества

Оба SDK поддерживают локальные функции и MCP, поэтому таблица, где каждому дают по баллу за «пользовательские инструменты» и «MCP», не помогает выбрать. Нужно знать, где выполняется инструмент, кто проверяет вход, кто подтверждает действие и какие доказательства сохраняются после него.

OpenAI предлагает несколько путей. Функции приложения выполняются в вашем коде. Агенты могут вызывать других агентов как инструменты. Вариант на Responses API открывает встроенные инструменты, а SDK умеет подключаться к серверам MCP через локальные транспорты или поручать Responses API вызвать доступный извне сервер MCP. Выбор полезен, но граница доверия в каждом случае иная. Локальная функция может получить идентификацию из процесса. Встроенный инструмент передает работу инфраструктуре поставщика. Удаленный MCP-сервер приносит собственные правила аутентификации и разделения клиентов.

Claude начинает со встроенных инструментов оператора, а затем добавляет пользовательские инструменты и MCP. Инструменты внутри процесса можно опубликовать через SDK MCP server. Внешние серверы MCP подключаются по стандартным транспортам. Навыки и плагины упаковывают инструкции и возможности вокруг этих инструментов. Поэтому экосистема Claude быстро кажется широкой: операции с рабочей средой доступны еще до того, как вы напишете первую функцию.

MCP делает инструменты переносимее только на границе протокола. Инструмент `create_invoice` со схемой JSON легче переместить между средами, чем декоратор Python или callback TypeScript. Окружающее поведение само не переедет: хранение OAuth, правила подтверждения, повторы, sampling, доступ к ресурсам, запросы пользователю, журналирование и отображение ошибок зависят от клиента и развертывания.

Держите нейтральные к поставщику инструменты в отдельном слое, а адаптер SDK делайте тонким. Достаточно небольшого контракта, который открывает существенную часть:

```python
from dataclasses import dataclass
from typing import Any, Protocol

@dataclass
class ToolCall:
    call_id: str
    name: str
    arguments: dict[str, Any]
    actor_id: str
    tenant_id: str

@dataclass
class ToolResult:
    call_id: str
    content: str
    is_error: bool = False

class ToolExecutor(Protocol):
    async def execute(self, call: ToolCall) -> ToolResult: ...
```

Поместите проверку прав, идемпотентность, тайм-ауты и аудит за `ToolExecutor`. Затем преобразуйте вызовы функций OpenAI или события пользовательских инструментов Claude в `ToolCall`. Не позволяйте SDK получать идентификатор клиента из текста беседы. Аутентифицированное приложение передает `actor_id` и `tenant_id`, а исполнитель отвергает несоответствие до любого действия с побочным эффектом.

## Подтверждение требует надежно хранить состояние

Подтверждение человеком безопасно только тогда, когда запуск умеет остановиться, пережить перезапуск процесса, связать решение с точным действием и продолжить работу без повтора уже выполненного эффекта. Окно с кнопками «Разрешить» и «Запретить» покрывает лишь видимую часть.

Инструменты OpenAI могут указывать, что требуют подтверждения. Тогда запуск возвращает прерывания, а сериализованный `RunState` сохраняет ожидающую работу для последующего продолжения. Официальное руководство по участию человека отмечает, что состояние включает вход инструмента, расход, вложенное состояние агентов, метаданные трассировки и контекст приложения. Это удобно для эксплуатации и одновременно требует осторожной работы с данными. Не кладите секреты в контекст, если правила хранения явно их не защищают.

Claude предлагает режимы разрешений, списки разрешенных и запрещенных инструментов, callback `can_use_tool` для решений приложения и хуки жизненного цикла вокруг вызовов. Интерактивные клиенты могут получить запрос разрешения, спросить пользователя и продолжить сессию. Хуки умеют проверять, блокировать или менять поведение в именованных событиях. Такой подход естественен для рабочей среды, где чтение файла, его изменение и запуск команды требуют разных политик.

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

Запись о подтверждении в продакшене должна содержать как минимум такие поля:

```json
{"run_id":"run_123","call_id":"call_456","tool":"deploy_release","args_sha256":"...","actor_id":"user_789","decision":"approved","decided_at":"2026-08-09T12:00:00Z","policy_version":"deploy-v4"}
```

Вычисляйте хеш канонических аргументов и требуйте тот же хеш во время исполнения. Для действий с побочным эффектом создавайте токен идемпотентности из постоянного ID вызова. Если процесс завершится после развертывания, но до записи результата в SDK, при повторе исполнитель должен вернуть прежний результат, а не развернуть релиз второй раз. В демонстрациях фреймворков эту часть часто пропускают, хотя именно она приводит к ночным инцидентам.

## Наблюдаемость должна отвечать на вопросы бизнеса

У OpenAI более явная встроенная модель трассировки для процессов приложения. По умолчанию SDK создает спаны для запусков, вызовов агентов, генераций, функций, проверок и передачи управления. Стандартный обработчик отправляет данные в OpenAI, однако Python SDK позволяет добавить обработчик или полностью заменить набор, поэтому трассы можно направить в другое место. Обращение с конфиденциальными входными и выходными данными все равно требует осознанной настройки.

Claude отдает подробный поток сообщений и сообщает в результате стоимость и расход. Хуки позволяют вмешиваться в события жизненного цикла. Документация также описывает поддержку OpenTelemetry для метрик и событий. Для агента рабочей среды необработанные события инструментов и измененные файлы часто важнее красивой трассы диалога, поэтому сохраняйте снимок рабочей директории или коммит, коды возврата команд, stderr и хеши артефактов рядом с телеметрией модели.

Не оценивайте систему по привлекательности окна трассировки в демонстрации. Проверьте, сможет ли дежурный инженер получить из экспортированных данных ответы на такие вопросы:

- Какой аутентифицированный пользователь вызвал действие с побочным эффектом?
- Какие версии промпта, схемы инструмента, политики и модели работали?
- Что получил и вернул каждый инструмент после удаления секретов?
- На каком участке появились задержка, расход токенов и денег?
- Можно ли повторить принятие решения, не повторяя запись?

Создайте собственную оболочку запуска до обращения к любому SDK. Сгенерируйте нейтральный `run_id`, добавьте версии развертывания и политики, затем передавайте его в трассы, события хуков, метаданные MCP, вызовы инструментов и журналы приложения. Идентификаторы поставщика храните во вторичных полях. Тогда будущая миграция не разорвет связь между продуктовой аналитикой и телеметрией агента.

Сравнение стоимости тоже относится сюда. Нельзя сопоставить одну цену токена и объявить победителя. Возьмите одинаковый набор задач и записывайте стоимость успешно принятого результата, полное время, количество вызовов инструментов, ожидание подтверждений, повторы и минуты ручного исправления. Агент с дешевыми токенами, который делает вдвое больше неверных шагов, не обходится дешевле.

## Привязка к поставщику состоит из пяти слоев

Команды часто называют «привязкой» любой импортируемый тип поставщика и не замечают данные с эксплуатацией, которые перенести гораздо труднее. До оценки риска разделите пять слоев.

1. Привязка модели охватывает промпты и поведение, настроенные под семейство моделей. OpenAI умеет направлять запросы другим поставщикам, но собственная документация предупреждает о различиях возможностей. Claude Agent SDK построен вокруг Claude и среды Claude Code, поэтому замена модели не относится к его основным целям.
2. Привязка инструментов включает декораторы, схемы, встроенные инструменты, поведение оболочки и файлов, расширения MCP и форматы ошибок. MCP снижает риск только для возможностей, которые чисто укладываются в этот протокол.
3. Привязка состояния включает элементы беседы, ID сессий, сжатие контекста, ожидающие подтверждения и форматы возобновляемых запусков. При миграции этот слой обычно болит сильнее схем инструментов.
4. Привязка наблюдаемости охватывает ID трасс, форматы спанов, сохраненные данные, панели и наборы для оценки. Создавайте собственный формат событий, даже если продолжаете пользоваться окном поставщика.
5. Операционная привязка включает песочницы, бинарные файлы CLI, секреты, жизненный цикл воркеров, региональные требования и порядок действий при инцидентах. Замена фреймворка может вообще не затронуть этот слой или потребовать полной перестройки.

Оценивайте каждый слой по цене выхода, а не по наличию проприетарного типа. На замену конструктора `Agent` конкретного поставщика может уйти день. Воспроизведение многолетней истории сессий, доказательств подтверждения и эталонов оценки может занять месяцы. И наоборот, отказ от удобного встроенного файлового инструмента ради одного импорта способен зря потратить время инженеров, не снизив дорогие риски.

Я не советую строить универсальную абстракцию агента до первого продакшен-пилота. Идея популярна, потому что интерфейс с именем `AgentProvider` выглядит страховкой. На практике интерфейс либо оставляет только текст и вызовы функций, убирая причины выбрать один из SDK, либо обрастает ветками для каждой функции поставщика. Создавайте переносимые границы вокруг инструментов, идентификации, экспорта состояния, телеметрии и оценок. Пусть код оркестрации остается конкретным, пока вторая реализация не покажет, что у систем действительно общее.

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

## Взвешенная оценка делает компромиссы видимыми

Правила оценки должны соответствовать оплачиваемой работе. Для каждого критерия ставьте от 1 до 5, умножайте на вес и требуйте письменное доказательство для любой оценки 4 или 5. Демонстрация поставщика не считается доказательством.

Для продуктового процесса возьмите такие веса: типизированные инструменты и результаты приложения 20, надежность подтверждения и возобновления 15, экспорт наблюдаемости 15, соответствие развертыванию и изоляции 15, управление несколькими агентами 10, переносимость моделей 10, сопровождение командой 10, работа с файловой системой 5. Подтвердите высокие баллы контрактными тестами реальных сервисов. Завершите воркер во время ожидания подтверждения, затем проверьте, сможет ли другой воркер восстановить точно тот же вызов.

Для оператора рабочей среды поменяйте веса: файлы, оболочка и редактирование 22; развертывание и изоляция 20; надежность подтверждений 15; управление несколькими агентами 10; экспорт наблюдаемости 10; сопровождение командой 10; типизированные инструменты приложения 8; переносимость моделей 5. Выполните задачи в изолированных репозиториях, проверьте каждый измененный артефакт и попробуйте очевидные способы выйти из песочницы. Если модель хорошо редактирует, но требует учетных данных на весь хост, она должна провалить этот критерий независимо от процента выполненных задач.

Веса каждой задачи должны давать в сумме 100, тогда любое предпочтение расходует ограниченный бюджет. Если заинтересованная сторона поднимает переносимость моделей с 5 до 20, спросите, какое другое требование потеряет 15 баллов. Так утверждение «у нас приоритетно все» вскроется до того, как исказит пилот.

Для обычного процесса SaaS OpenAI чаще начинает с преимуществом в явной композиции, типизированных результатах и структуре трассировки. Для работы с репозиториями и операциями Claude чаще впереди, потому что встроенные инструменты рабочей среды, управление контекстом и конфигурация проекта экономят месяцы разработки собственной оболочки. Это исходные предположения, а не готовые оценки.

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

Не подменяйте этот выбор громкими цифрами из контекста сайта. На oleg.is я включил бы решение в Team & AI Audit только после разбора настоящей работы, ограничений и расходов на персонал: оценка SDK дает один из входных параметров, а не обещанную экономию.

## Проверяйте сбои раньше успешного пути

Двухнедельный пилот должен использовать для обоих SDK одинаковый набор задач, контракты инструментов, идентификаторы и критерии успеха. Если есть материал, выберите от 20 до 30 типичных задач, но десять настоящих лучше сотни синтетических промптов. Добавьте работу, которая требует уточнения, недоступную зависимость, запрещенное действие, устаревшее состояние и инструмент с неверными данными.

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

Проведите как минимум такие испытания с отказами:

- Завершите воркер после побочного эффекта, но до возврата результата инструмента.
- Измените схему инструмента, пока сессия ждет подтверждения.
- Запретите рискованный вызов и проверьте, не найдет ли агент опасный обходной путь.
- Отключите сеть или зависимость MCP в середине задачи.
- Верните из инструмента инструкции, которые противоречат системной политике.

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

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

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

## Правило выбора должно быть операционно скучным

Выбирайте OpenAI Agents SDK, когда агент работает внутри приложения, большинство инструментов уже оформлены как сервисные функции, важен типизированный результат и нужны явные менеджеры или передача управления. Это также хорошая отправная точка, когда реальный вес имеют встроенная трассировка процесса и возможность проверить других поставщиков моделей, но каждый планируемый путь вне OpenAI нужно протестировать.

Выбирайте Claude Agent SDK, когда агент должен работать в пространстве, особенно в кодовой базе, и вам нужны через библиотеку файлы, оболочка, редактирование, контекст, хуки, разрешения, навыки, плагины и субагенты Claude Code. Примите, что такой выбор сильнее связывает опыт с Claude и превращает проектирование песочницы в часть архитектуры приложения.

Не выбирайте ни один SDK для короткого вызова модели, при обязательном контроле команды над каждым переходом цикла или когда тонкая прямая интеграция с API уже проходит приемочные проверки. Фреймворк создает состояние и политики, которые затем придется обслуживать. Если потребности нет, его добавление ухудшит систему.

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

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