Посібник з розуміння, побудови та оптимізації агентів, які викликають API API списку завдань version: 1.0.0 paths: /tasks: post: summary: Додати нове завдання requestBody: required: true

Роль штучного інтелекту в технологічних компаніях швидко еволюціонує; випадки використання штучного інтелекту еволюціонували від пасивної обробки інформації до активних агентів, які можуть виконувати завдання. За даними опитування про глобальне впровадження штучного інтелекту, проведеного в березні 2025 року Georgian і NewtonX, 91% технічних керівників компаній на стадії зростання та підприємств заявили, що вони використовують або планують використовувати агентний штучний інтелект.

Агенти, які викликають API, є основним прикладом цього переходу до агентів. Агенти, які викликають API, використовують великі мовні моделі (LLM), щоб взаємодіяти з програмними системами через їхні інтерфейси програмування застосунків (API).

Наприклад, перекладаючи природну мову в точні виклики API, агенти можуть отримувати дані в режимі реального часу, автоматизувати повторювані завдання або навіть керувати іншими програмними системами. Ця здатність перетворює агенти штучного інтелекту на корисних посередників між намірами людини та функціональністю програмного забезпечення.

Компанії зараз використовують агентів, які викликають API, в різних галузях, включаючи:

• Застосунки для споживачів: Помічники, такі як Siri від Apple або Alexa від Amazon, були розроблені для спрощення повсякденних завдань, таких як керування пристроями розумного будинку та бронювання.
• Потоки підприємств: Підприємства розгорнули агентів API для автоматизації повторюваних завдань, таких як отримання даних з CRM, генерація звітів або консолідація інформації з внутрішніх систем.
• Отримання даних та аналіз: Підприємства використовують агентів API для спрощення доступу до власних наборів даних, ресурсів за підпискою та публічних API для генерації інсайтів.

У цій статті я використовуватиму інженерний підхід для розуміння, побудови та оптимізації агентів, які викликають API. Матеріал цієї статті частково заснований на практичних дослідженнях та розробках, проведених лабораторією штучного інтелекту Georgian.

Порушуване питання для багатьох досліджень лабораторії штучного інтелекту в області агентів, які викликають API, було: “Якщо в організації є API, який є найефективнішим способом побудови агента, який може взаємодіяти з цим API за допомогою природної мови?”

Я поясню, як агенти, які викликають API, працюють і як успішно проектувати та інженерно забезпечувати ці агенти для продуктивності. Нарешті, я надам систематичний робочий процес, який інженерні команди можуть використовувати для реалізації агентів, які викликають API.

I. Ключові визначення:

• API або інтерфейс програмування застосунків: Набір правил та протоколів, що дозволяють різним програмним застосункам спілкуватися та обмінюватися інформацією.
• Агент: Система штучного інтелекту, розроблена для сприйняття своєї середовища, прийняття рішень та виконання дій для досягнення конкретних цілей.
• Агент, який викликає API: Спеціалізований агент штучного інтелекту, який перекладає природну мову інструкцій у точні виклики API.
• Агент генерації коду: Система штучного інтелекту, яка допомагає у розробці програмного забезпечення, написанні, модифікації та налагодженні коду. Хоча це пов’язано, моя увага тут в основному зосереджена на агентах, які викликають API, хоча штучний інтелект також може допомогти будувати цих агентів.
• MCP (Протокол контексту моделі): Протокол, розроблений компанією Anthropic, який визначає, як великі мовні моделі можуть підключатися до зовнішніх інструментів та джерел даних.

II. Основне завдання: переклад природної мови у дії API

Фундаментальною функцією агента, який викликає API, є інтерпретація запиту користувача природною мовою та перетворення його у один або кілька точних викликів API. Цей процес зазвичай включає:

1. Розпізнавання намірів: Поняття мети користувача, навіть якщо вона виражена двозначно.
2. Вибір інструменту: Визначення відповідного API-інтерфейсу (або “інструменту”) з набору доступних варіантів, які можуть виконати намір.
3. Вилучення параметрів: Визначення та вилучення необхідних параметрів для вибраного виклику API (або викликів) з запиту користувача.
4. Виконання та генерація відповіді: Виклик API (або викликів), отримання відповіді (або відповідей) та подальша генерація цієї інформації у зрозумілу відповідь або виконання наступної дії.

Розгляньте запит, такий як “Привіт, Siri, яка погода сьогодні?” Агент повинен визначити необхідність виклику API погоди, визначити поточне місце розташування користувача (або дозволити вказати місце розташування) та сформулювати виклик API для отримання інформації про погоду.

Для запиту “Привіт, Siri, яка погода сьогодні?” зразковий виклик API може виглядати наступним чином:

GET /v1/weather?location=New%20York&units=metric

Початкові високорівневі виклики є вбудованими в цей процес перекладу, включаючи двозначність природної мови та необхідність для агента підтримувати контекст під час багатокрокових взаємодій.

Наприклад, агент часто повинен “запам’ятати” попередні частини розмови або попередні результати виклику API, щоб інформувати поточні дії.

Втрата контексту є поширеним режимом відмови, якщо його не явно керувати.

III. Проектування рішення: ключові компоненти та протоколи

Будування ефективних агентів, які викликають API, вимагає структурованого архітектурного підходу.

1. Визначення “інструментів” для агента

Для того щоб велика мовна модель могла використовувати API, його можливості повинні бути описані їй у спосіб, який вона може зрозуміти. Кожний API-інтерфейс або функція часто представляється як “інструмент”. Надійне визначення інструменту включає:

• Чітке, природне мовне опис інструменту та його функціональності.
• Точне визначення його вхідних параметрів (ім’я, тип, чи це обов’язковий або необов’язковий параметр, та опис).
• Опис виходу або даних, які інструмент повертає.

2. Роль протоколу контексту моделі (MCP)

MCP є критичним елементом для більш стандартизованого та надійного використання інструментів великими мовними моделями. Він надає структурований формат для визначення того, як моделі можуть підключатися до зовнішніх інструментів та джерел даних.

Стандартизація MCP є корисною, оскільки вона дозволяє легше інтегрувати різноманітні інструменти, сприяє повторному використанню визначень інструментів у різних агентах або моделях. Крім того, це є рекомендацією для інженерних команд, починаючи з добре структурованих специфікацій API, таких як специфікація OpenAPI. Інструменти, такі як Stainless.ai, розроблені для допоміжної конвертації цих специфікацій OpenAPI у конфігурації MCP, спрощуючи процес надання API “агент-готовності”.

3. Фреймворки агентів та вибір реалізації

Існують кілька фреймворків, які можуть допомогти у побудові самого агента. До них належать:

• Pydantic: Хоча це не виключно фреймворк агента, Pydantic є корисним для визначення структур даних та забезпечення безпеки типу для вхідних та вихідних даних інструменту, що є важливим для надійності. Багато реалізацій агентів використовують Pydantic для цієї структурної цілісності.
• Фреймворк LastMile’s mcp_agent: Цей фреймворк розроблений спеціально для роботи з MCP, пропонуючи більш впорядковану структуру, яка відповідає практикам побудови ефективних агентів, як описано в дослідженнях компаній, таких як Anthropic.
• Внутрішній фреймворк: Це також все частіше використовується для використання агентів генерації коду штучного інтелекту (за допомогою інструментів, таких як Cursor або Cline) для допомоги у написанні шаблонного коду для агента, його інструментів та оточуючої логіки. Досвід лабораторії штучного інтелекту Georgian, який працює з компаніями над агентними реалізаціями, показує, що це може бути корисним для створення мінімальних, спеціалізованих фреймворків.

IV. Інженерія для надійності та продуктивності

Забезпечення того, щоб агент робив виклики API надійно та працював добре, вимагає зосередженого інженерного зусилля. Два способи зробити це – це створення та валідация набору даних та інженерія та оптимізація промптів.

1. Створення та валідация набору даних

Тренування (якщо це застосовується), тестування та оптимізація агента вимагають високоякісного набору даних. Цей набір даних повинен складатися з представницьких запитів природною мовою та відповідних бажаних послідовностей викликів API або результатів.

• Ручне створення: Ручне кураторство набору даних забезпечує високу точність та актуальність, але може бути трудомістким.
• Синтетична генерація: Генерація даних програмно або за допомогою великих мовних моделей може масштабувати створення набору даних, але цей підхід представляє значні виклики. Дослідження лабораторії штучного інтелекту Georgian виявили, що забезпечення правильності та реалістичної складності синтетично згенерованих викликів API та запитів є дуже важким. Часто генеровані питання були або надто тривіальними, або неможливо складними, що робило важким вимірювання нюансів продуктивності агента. Ретельна валідация синтетичних даних є абсолютно критичною.

Для критичної оцінки менший, високоякісний, ручно верифікований набір даних часто забезпечує більш надійні інсайти, ніж великий, шумний синтетичний.

2. Інженерія промптів та оптимізація

Продуктивність агента, заснованого на великих мовних моделях, сильно залежить від промптів, які використовуються для керування його міркуванням та вибором інструменту.

• Ефективна промпт-інженерія включає чітке визначення завдання агента, надання описів доступних інструментів та структуризації промпту для заохочення точної екстракції параметрів.
• Систематична оптимізація за допомогою фреймворків, таких як DSPy, може суттєво підвищити продуктивність. DSPy дозволяє вам визначити компоненти вашого агента (наприклад, модулі для генерації думок, вибору інструменту, форматування параметрів) та потім використовувати підхід компілятора з декількома прикладами з вашого набору даних для пошуку оптимізованих промптів або конфігурацій для цих компонентів.

V. Рекомендований шлях до ефективних агентів API

Розробка надійних агентів, які викликають API штучного інтелекту, є ітеративною інженерною дисципліною. На основі висновків досліджень лабораторії штучного інтелекту Georgian результати можуть бути суттєво покращені за допомогою систематичного робочого процесу, такого як наступний:

1. Почніть з чітких визначень API: Почніть з добре структурованих специфікацій OpenAPI для API, з якими ваш агент буде взаємодіяти.
2. Стандартизуйте доступ до інструменту: Перетворіть свої специфікації OpenAPI у MCP. Інструменти, такі як Stainless.ai, можуть допомогти у цьому, створюючи стандартизований спосіб для вашого агента зрозуміти та використовувати ваші API.
3. Реалізуйте агента: Виберіть відповідний фреймворк або підхід. Це може включати використання Pydantic для моделювання даних у спеціальній структурі агента або використання фреймворку, такого як LastMile’s mcp_agent, який розроблений навколо MCP.
   • Перед тим, як зробити це, розгляньте підключення MCP до інструменту, такого як Claude Desktop або Cline, та ручне використання цього інтерфейсу для отримання відчуття того, як добре загальний агент може використовувати його, скільки ітерацій зазвичай потрібно для використання MCP правильно та будь-яких інших деталей, які можуть зберегти вам час під час реалізації.
4. Кураторство набору даних для оцінки: Створіть або ретельно валідуйте набір даних запитів та очікуваних взаємодій API. Це є критичним для надійного тестування та оптимізації.
5. Оптимізуйте промпти та логіку агента: Використовуйте фреймворки, такі як DSPy, для уточнення промптів вашого агента та внутрішньої логіки, використовуючи ваш набір даних для керування покращеннями точності та надійності.

VI. Ілюстративний приклад робочого процесу

Ось спрощений приклад, що ілюструє рекомендований робочий процес для побудови агента, який викликає API:

Крок 1: Почніть з чітких визначень API

Уявіть API для керування простим списком завдань, визначеним у OpenAPI:

openapi: 3.0.0

info:
application/json:

schema:

type: object

properties:

description:

type: string

responses:

‘201’:

description: Завдання створено успішно

get:

summary: Отримати всі завдання

responses:

‘200’:

description: Список завдань

Крок 2: Стандартизуйте доступ до інструменту

Перетворіть специфікацію OpenAPI у конфігурації протоколу контексту моделі (MCP). Використовуючи інструмент, такий як Stainless.ai, це може дати:

Крок 3: Реалізуйте агента

Використовуючи Pydantic для моделювання даних, створіть функції, що відповідають інструментам MCP. Потім використовуйте велику мовну модель для інтерпретації запитів природною мовою та вибору відповідного інструменту та параметрів.

Крок 4: Кураторство набору даних для оцінки

Створіть набір даних:

Крок 5: Оптимізуйте промпти та логіку агента

Використовуйте DSPy для уточнення промптів, зосереджуючись на чітких інструкціях, виборі інструменту та екстракції параметрів, використовуючи кураторський набір даних для оцінки та покращення.

Інтегруючи ці будівельні блоки – від структурованих визначень API та стандартизованих протоколів інструментів до ретельних практик даних та систематичної оптимізації – інженерні команди можуть побудувати більш здатних, надійних та підтримуваних агентів, які викликають API штучного інтелекту.