Створення асистента API з агентними функціями: від хакатону до версії Beta
Асистент LangGraph, який пояснює API, пише код та виконує тільки читальні запити: два режими, самовідновлювальний цикл OData, пам’ять артефактів, оцінка за допомогою LLM-судді, самостійний доступ.
Джерела: From hackathon spark to production reality: building an agentic API assistant
Команда, яка розробляє API для управління флотом для компанії з платежів, перетворила прототип з хакатону на бета-асистента, який працює в їхньому девелоперському порталі. Ідея полягає у тому, щоб позбавити інтеграторів необхідності читати довідкові сторінки та перекладати їх у код, дозволяючи конверсаційному агенту самостійно здійснювати інтеграцію. Тут розглядається, як створюється такий асистент, що він навмисно не робить, та як оцінюється його якість.
Асистент пояснює ендпоїнти, пише код мовою, яку використовує розробник, планує багатоетапні процеси та виконує запити до даних лише для читання в реальних системах. Він замінює собою статичні документації та індекси пошуку, специфічні для певної мови, які лише вказують на сторінки.
Чому статична документація більше недостатня
Програмне забезпечення для управління флотом та мобільності обробляє великий обсяг даних: активність водіїв, заправки, транзакції картками та телеметрія транспортних засобів. Кожен, хто його інтегрує, змушений вивчати складні REST-кінцеві точки, синтаксис фільтрації, термінологію домену та довгі ланцюги залежних викликів. Усі ці труднощі ускладнювали партнерам розвиток разом із платформою.
Розробники використовували готові інструменти документації для читання визначень кінцевих точок та тестові засоби для ручного тестування викликів. Команда також зберігала „рецепти“ — фіксовані послідовності викликів, які показували, як виконати багатоетапну задачу, наприклад створити обліковий запис, прив’язати водія та додати картку. Це працювало, але постійно проявлялися три слабкості:
- Залежність від мови. Опис кожного процесу в форматах cURL, Python, .NET, Java та Go вимагав постійних ручних зусиль від авторів та інженерів.
- Крихкі краї. Неможливо задокументувати кожну комбінацію кожного робочого процесу, тому інструкції часто не враховують конкретну ситуацію користувача.
- Постійні витрати на підтримку. Як тільки змінювалася схема API, сторінки ставали застарілими, що уповільнювало процес інтеграції та заповнювало чергу підтримки.
Від ідеї хакатону до двох режимів
Концепція виникла під час внутрішнього хакатону у грудні 2025 року через одне запитання: навіщо просити розробників перетворювати документацію на код, якщо модель може безпосередньо розуміти їхні наміри? Результат працює як консультант з інтеграції, який завжди доступний, а не як пошукове поле.
Для забезпечення оперативної безпеки дизайн розділяє асистента на два окремі шляхи обробки.
Режим консультанта забезпечує пояснення для однокрокових операцій, детальну документацію та генерацію коду для будь-якої фреймворк-системи, включаючи операції зі зміною даних такі як POST, PUT та DELETE. Він генерує код, але ніколи не запускає його, тому людина залишається причетною до будь-яких змін даних.
Режим планування та виконання обробляє складні, багатокрокові запити на читання та виконує їх на живій платформі за допомогою інструментів Model Context Protocol (MCP) з обмеженими правами доступу.
Що бачать партнери насправді
Якщо звернутися до режиму консультанта з проханням надати фрагмент коду на Python, який створює драйвер, він поверне виклик функції requests із відповідним кінцевим пунктом, заголовками, схемою тіла та приміткою щодо необхідних діапазонів доступу. Жодні зміни не впливають на продакшн-API.
Режим планування та виконання запитує про п’ять водіїв із ім’ям John, і планувальник скорочує багатофільтровий запит до однієї задачі — отримання водіїв, відфільтрованих за ім’ям. Виконавець обирає відповідний інструмент MCP, формує аргументи OData ($filter=first_name eq 'John', $top=5), виконує лише читальний запит GET та зберігає повну відповідь у сховищі артефактів. Модель бачить лише стислий огляд: ідентифікатор артефакта, кількість — п’ять та короткий перегляд. Потім синтезатор створює охайний список п’ятьох відповідних водіїв.
Архітектура: цикл взаємодіючих агентів
Асистент побудований на LangGraph як циклічна машина станів. Планувальник, виконавці, верифікатори та синтезатор по черзі планують, виконують дії та перевіряють кожен крок, передаючи спільний стан та пам’ять між собою до завершення завдання. Варто зазначити чотири основні архітектурні рішення.
1. Тільки для читання проксі для безпеки
Безпека була ключовим фактором у проектуванні з самого початку. Асистент не може виконувати змінюючі дані запити у своєму власному середовищі виконання. Коли користувач просить «створити нову картку для водія X», маршрутизатор надсилає запит до вузла-консультанта, який повертає структурований фрагмент, який розробник може скопіювати, переглянути та виконати локально. Усе, що виконується насправді, обмежується запитами типу GET. У коді сервера MCP існують інструменти для запису, але вони фільтруються ще до того, як модель їх побачить.
2. Оркестрація у стилі супервізора
Міркування та виконання знаходяться на різних рівнях та координуються єдиним супервізором, який вирішує, який спеціаліст буде діяти далі в межах одного глобального циклу:
- Клас mode router класифікує намір та надсилає кожне повідомлення до консультанта або модуля планування та виконання.
- Планувальник розбиває складне запитання на список завдань, пов’язаних із цільовими параметрами.
- Виконавець обирає інструмент MCP для кожного завдання, збирає аргументи (включаючи фільтри OData) та поступово працює з цим інструментом, поки завдання не буде виконане або не закінчаться спроби.
- Синтезатор об’єднує результати кожного завдання, як справжні дані, так і фрагменти коду на випадок невдач, у одну відповідь.
3. Цикл, який виправляє власні OData
Моделі схильні створювати додаткові опції запитів або спотворювати синтаксис під час роботи зі структурованими мовами фільтрації, такими як OData. Команда обрала OData тому, що він дозволяє виконувати гнучкі запити з частковим збігом для складних об’єктів мобільності без необхідності вручну кодувати кожну комбінацію, але саме ця гнучкість призводить до помилок, тому було додано багатошаровий цикл виправлення.
Якщо парсер попереднього аналізу виявляє проблему синтаксису або ж запит повертає помилку API, система фіксує цю подію, підвищує лічильник спроб повторного виконання для конкретного завдання та передає точне повідомлення про помилку назад у контекст моделі. Виконавець бачить свою невдачу та формує виправлений запит. Коли кількість спроб вичерпується, завдання переходить у режим порадника, щоб користувач все одно отримав щось корисне.
4. Пам’ять, розділена на артефакти
Надсилання великого об’єму даних у форматі JSON, наприклад тисяч записів активів, під час розмови споживає весь бюджет токенів, погіршує точність міркувань та збільшує витрати. Тому первинні відповіді зберігаються у ізольованому сховищі артефактів на серверному рівні, а моделі надається лише короткий оглядовий метадані, який містить ідентифікатори артефактів. Додаткові запитання дозволяють детальніше дослідити конкретні елементи шляхом пошуку цих ідентифікаторів у рівні додатку, що допомагає зберігати контекст моделі компактним та зосередженим.
Вимірювання якості
Щоб змінити запит або модель без погіршення якості, потрібен автоматизований критерій оцінки. У системі команди використовується ШІ як оцінювач, який відповідає на одне запитання щодо кожної зміни: чи є вона кращою чи гіршою, ніж раніше?
Набір даних — це вручну створений набір тестових випадків у чотирьох категоріях: генерація коду, фактичні знання, міркування та безпека. Кожен випадок має чітку шкалу оцінювання, а не просто запитання, тож оцінювач оцінює зміст відповіді, а не просто її збіг із заданим шаблоном. Оцінювач завжди є іншою моделлю, ніж та, яка перевіряється, і оцінюється за трьохбальною шкалою: 10 за правильну відповідь, 5 за часткову та 0 за неправильну. Кожен запуск додає рядок до файлу історії, позначеного git-комітом, моделлю, яка перевіряється, моделлю оцінювача, хешем OpenAPI, хешем набору даних та версією запиту, тож кожна оцінка може бути простежена до конкретного коду, специфікації та запиту, які її породили.
За даними команди, асистент у середньому набирає близько 9,4 з 10 балів за цією шкалою під час кожного запуску, і це значення використовується як базовий показник для захисту перед випуском змін. Однак точність — не єдиний критерій. Кожен запуск також фіксує час відгуку, щоб забезпечити швидку реакцію, та кількість використаних токенів, яка безпосередньо відображає витрати на модель. Зміни, які погіршують хоча б один з цих показників, позначаються ще до релізу.
Захист бюджету та пропускної здатності
Асистент, який постійно працює та взаємодіє з API виробничого середовища, потребує обмежень, які захищають як бюджет моделі, так і сервіси, що знаходяться вище в ієрархії. Для цього встановлено три рівні контролю:
- Квоти на користувача. Демо-акаунти отримують 10 повідомлень на день, що дозволяє зацікавленим партнерам протестувати асистента без необмежених витрат на модель та спонукає їх перейти на партнерський акаунт, коли вони хочуть використовувати його у реальних проектах.
- Дзвінки з чітким визначенням меж та прив’язкою до користувача. Трафік партнерів обробляється за їхніми власними обліковими даними, тому кожен дзвінок враховується у їхньому ліміті та фіксується у їхньому власному журналі аудиту. Асистент ніколи не видає себе за спільний обліковий запис, що дозволяє точно визначати користувачів та виявляти зловживання.
- Повторні спроби, які розуміють причини невдач. Коли запит зазнає невдачі, включаючи тимчасову відповідь про обмеження, цикл виправлення передає помилку назад до моделі, збільшує лічильник повторних спроб та планує їх ще раз до встановленої максимальної кількості. Після вичерпання всіх спроб система переходить у режим порадника.
Забезпечення легкого доступу
Створення асистента — це лише половина роботи. Не менш важливим було забезпечити безпечний та зручний доступ.
API цієї платформи традиційно використовували стандартні облікові дані клієнта, що означало необхідність ручного налаштування кожного нового клієнта. Для асистента, призначеного для зовнішніх партнерів, підхід «надіслати запит та чекати схвалення від інженерів» був неприйнятним. Прохання до розробників вставляти токени в чат також не було кращим рішенням, адже це унеможливлювало відрізнити дзвінки, здійснені асистентом, від ручних, а також ускладнювало відстеження використання та моніторинг безпеки. Команді була потрібна єдина стратегія, яка б підходила для двох типів користувачів: партнерів, які хочуть працювати у середовищі без перешкод, та тих, хто готовий використовувати живі дані, без необхідності створення додаткових заявок на налаштування.
Рішенням стала дворівнева модель самообслуговування позаду звичайного входу для розробників.
- Режим демонстрації є стандартним. Нові користувачі можуть негайно спілкуватися з асистентом за допомогою синтетичних даних, без необхідності налаштувань, очікування чи подання заявок.
- Режим партнера увімкнюється, коли розробник бажає здійснити пряму інтеграцію. Дані автентифікації отримуються через одноразовий процес авторизації, який можна пройти самостійно, і вони пов’язані з власним обліковим записом та правами розробника. Після підключення кожен запит прив’язується до цієї ідентичності та є повністю простежуваним, тож чітко видно, хто здійснює запит та яким шляхом.
Це усунуло основну перешкоду під час інтеграції. Перехід від стану „Мені цікаво“ до стану „Я інтегрую“ більше не вимагає очікування у черзі інженерів.
Яким буде подальший розвиток
Проект починався як внутрішній експеримент, а тепер є бета-версією, яка скорочує час інтеграції для корпоративних команд розробників. Він працює в порталі розробників та вже приєднав першу групу партнерів.
Оркестратор читає стандартні схеми OpenAPI, тому архітектура розроблена для горизонтального масштабування. Наразі зусилля зосереджені на перевірці даних у сфері мобільності, проте ядро маршрутизації свідомо залишається універсальним. У планах — впровадження цього ж шару взаємодії в інші відділи, такі як платіжні та програми льгот для корпорацій, додавання більш ретельної детерміністичної перевірки даних за допомогою OData для блокування більшої кількості некоректних запитів ще до того, як вони надійдуть до асистента, а також використання підтвердження людини під час операцій запису, щоб асистент з часом міг також безпечно допомагати у зміні робочих процесів.
Пов’язана література
- Від прототипу до продакшну: Агентні ШІ з LangChain, LangGraph та Azure — гібридний пошук, кешування ембеддингів, маршрутизація через LangGraph, механізми захисту від збоїв, тести на регресію з використанням „золотих“ наборів даних та трекінг для агента для обробки податкових документів із наведенням результатів.
- Графи знань для агентних ШІ: чотири патерни, які виходять за межі векторного RAG — векторний пошук знаходить схожий текст, а не пов’язані факти. Чотири патерни графів для агентів: стимулювання на основі реальних даних, планування, перевірка виконання та самокорекція.