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

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

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

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

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

• Застосунки для споживачів: Помічники, такі як Apple’s Siri або Amazon’s Alexa, були розроблені для спрощення повсякденних завдань, таких як керування розумними пристроями та бронювання.
• Підприємські робочі процеси: Підприємства розгорнули агентів 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, отримання відповіді та подальша генерація цієї інформації у вигляді зрозумілої відповіді або виконання подальших дій.

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

Для запиту “Привіт, Сірі, який сьогодні погода?” приклад виклику 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.