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-агент.