SDK и фреймворки для агентов

Что такое SDK — и что вы покупаете

SDK (software development kit, «набор для разработки») — это коробка готовых деталей для одной конкретной задачи. Ничего экзотического: кто-то один раз сделал скучную работу и передал вам результат в виде библиотеки, которая ставится одной командой.

Урок Инструменты и вызов функций показал, что агент — это цикл while вокруг вызова API, и этот цикл вы можете написать сами за полдня. А вот всё, что вокруг него, за полдня не напишешь. Нужно превратить ваши Python-функции в JSON-описания, которые требуются модели, и проверить, что аргументы модели корректны. Нужно повторить запрос, когда провайдер отвечает «слишком много запросов», логировать каждый шаг, чтобы можно было отладить девятый, и справиться с тем, что модель иногда возвращает чепуху. Вся эта работа вокруг цикла — обвязка (plumbing), и именно на неё уходит время в агентных проектах. SDK — это уже написанная обвязка, проверенная тысячами других людей и поддерживаемая за вас.

Обмен простой: вы отдаёте немного контроля и получаете назад свои выходные.

Что лежит в коробке, можно перечислить коротко и точно:

• Сам цикл — вы задаёте инструменты и цель, а SDK крутит «думать, действовать, наблюдать, повторять», пока модель не скажет, что готово.
• Реестр инструментов — объявите функции один раз (часто по аннотациям типов или докстрингам); SDK сгенерирует схемы (машиночитаемые описания аргументов каждого инструмента), проверит аргументы и направит вызовы.
• Передача управления и структура — готовые примитивы, чтобы один агент мог передать управление другому (handoff, «передача»), или чтобы заставить вывод укладываться в типизированные схемы, а результат был предсказуемым.
• Повторные попытки и обработка ошибок — лимиты запросов (провайдер просит вас притормозить), таймауты, некорректные вызовы инструментов: скучные виды сбоев, которые везде обрабатываются одинаково.
• Трассировка и наблюдаемость — пошаговый журнал каждого промпта, вызова инструмента и числа токенов. Когда агент ведёт себя странно на девятом шаге, именно так вы выясняете почему.

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

Два «родных» SDK

SDK от самих провайдеров моделей тонкие и работают близко к «железу». Вот минимальные агенты бок о бок:

1# pip install openai-agents
2from agents import Agent, Runner, function_tool
3import requests
4 
5@function_tool
6def get_weather(city: str) -> str:
7  #98c379">"""Get current weather for a city."""
8  r = requests.get(#98c379">"https://wttr.in/" + city,
9                   params={#98c379">"format": "3"}, timeout=10)
10  return r.text
11 
12agent = Agent(
13  name=#98c379">"WeatherBot",
14  instructions=#98c379">"Answer weather questions briefly.",
15  tools=[get_weather],
16)
17 
18result = Runner.run_sync(agent, #98c379">"Umbrella in Prague today?")
19print(result.final_output)
20# SDK прогнал весь цикл за вас

У двух SDK разный характер. OpenAI Agents SDK — лёгкая библиотека: вы пишете инструменты, она запускает цикл, а передачу управления и ограничители (guardrails) предлагает как базовые понятия. Claude Agent SDK ближе к «Claude Code в виде библиотеки»: он поставляется со встроенными инструментами (файлы, командная оболочка, поиск) и системой разрешений, поэтому вы настраиваете готового агента, а не собираете его из деталей. Выбирайте по тому, что вам нужно: собственные инструменты и оркестрация или готовый агент для кода и эксплуатации с ограничителями.

Фреймворки

LangChain и LlamaIndex находятся на уровень выше. LangChain — большой набор абстракций: агенты, память, загрузчики документов, интеграции с векторными хранилищами; к нему прилагается экосистема плагинов на сотни сервисов. LlamaIndex начинался как фреймворк для RAG, а потом обзавёлся возможностями агентов; если работа вашего агента в основном состоит в том, чтобы «искать по моим документам и рассуждать над найденным», ему здесь самое место.

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

К тому же API фреймворков постоянно меняются: абстракции переименовывают и переписывают между мажорными версиями, а ваш код вынужден меняться вместе с ними.

Не уверены, в какую сторону идти? Опишите свою ситуацию чат-ассистенту, и пусть он изложит доводы обеих сторон. Скопируйте это, заполните скобки и вставьте в ChatGPT, Claude или любой чат с моделью:

Я создаю AI-агента и не могу решить, нужен ли мне SDK или фреймворк. Вот моя ситуация:

- Что должен делать агент: [одно предложение]
- Какие инструменты ему нужны: [перечислите или напишите «никаких»]
- Сколько шагов: [один шаг / цикл из нескольких шагов]
- Язык программирования: [Python / JavaScript / я не программирую]
- Что для меня важнее всего: [выпустить сегодня / видеть каждый шаг для отладки / возможность позже сменить модель]

Пожалуйста, ответь:
1. Достаточно ли в моём случае вызывать API напрямую или нужен SDK либо фреймворк? Скажи, что именно и почему.
2. Если я откажусь от SDK, перечисли точно, что мне придётся писать и поддерживать самому.
3. Если я возьму SDK, какой подойдёт и сколько контроля я потеряю?
Сначала отвечай простым языком, потом показывай код. Объясняй любой жаргон, который используешь.

Что на самом деле оценивать

Какой бы вариант вы ни выбрали, задайте одни и те же пять вопросов:

• Трассировка: вижу ли я каждый промпт, вызов инструмента и число токенов в интерфейсе?
• Переносимость между моделями: насколько трудно позже сменить провайдера?
• Запасной выход: могу ли я спуститься до «сырых» вызовов API ради одного необычного случая?
• Поведение при сбоях: что происходит при падении инструмента, лимите запросов, неверном JSON-аргументе — ошибка молча проглатывается или выводится наружу?
• Признаки живой поддержки: частота релизов, журнал изменений, то, как проект справился с последним ломающим изменением.

Проверьте себя

Куда идти дальше

Теперь вы знаете, что дают SDK и сколько контроля они забирают. Родственная остановка дальше на дорожной карте — MCP: USB-порт для ИИ, открытый стандарт, который отвязывает ваши инструменты от любого одного SDK. А если термины из этого урока всё ещё кажутся абстрактными, вернитесь к более раннему уроку о том, что такое AI-агент.