Агентны асістэнт па API: ад хакатона да беты
Асістэнт на 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.
У рэжыме планавання і выканання запрашуецца пяць водзіў, чыяе імя — Джон, і планавальнік зменшае колькасць фільтраў да аднаго задачы: запрашаецца інфармацыя пра водзіў, фільтраваная па імені. Выканавальнік выбірае адпаведны інструмент 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-пакета, напрыклад, тыяў тысячаў запісаў асэтав, у размову выкарыстоўвае весь бюджэт токенаў, пагаршае точнасць аналізу і паднімае косцы. Таму неапранутыя адказы застаюцца ў ізольаваным хранілішчы артыфактав на бэкендзе, а модэлі паказваецца толькі короткая статыстыка-метаданыя, якая вказывае на ідэны артыфактав. Да дапамогі задаюцца дадатковыя запытанні, якія шукаюць конкрэтныя элементы па ідэнах у слоі прыемлівання дадзеных, чым памяць модэлі застаецца маленькай і сфармаванай.
Адмэткая кантроль
Каб змяніць запрос або мадэль без падэйску якосці, патрэбны автаматызаваныя крэтэрыя. Сістэма команды выкорыстоўвае LLM як суддзю і адпавядае на адна запытанне па кожной змяне: чы рэзультат лепшы чы горшы, чым раней?
Набор дадзеных — гэта ручная група тэстовых кейсаў, разбітых на чатыры катэгорыі: генераванне коду, фактычныя знанні, разумаванне і безпека. Кожны кейс мае чыста апісаную шкалу оцэнкі, а не проста запытанне, таму адпаведальны за оцэнку атрыбутаў адпаведзення, а не проста пашук павінавання з узятым загадзя шаблонам. Адпаведальны за оцэнку завжды ўжо іншы модэль, чым той, які тэстуецца, і дае балы за трывухбальной шкалай: 10 за правільны адпаведзення, 5 за часткова правільнае і 0 за неправільнае. Кожны запуск дадае рэяд у файл з історыяй, які пазначаецца гіт-комітам, тэстуемым модэлем, модэлем-адпаведальным за оцэнку, хэшам OpenAPI, хэшам набора дадзеных і версіяй запытання, тады якія-небудзь балы можна прыследзіць да конкрэтнага коду, спецыфікацыі і запытання, якія сталі падставай для ўзнікнення яго.
Па ўтварэнні команды, асістэнт у сярэжных працоўках паўтарэнняў пасягае у сярэжнай шкале ацэнкі ад 10 гэтых балоў у сярэжнай суме 9,4, і гэты показнік служыць базовым рэгламентам, які трэба захаваць пры выпуску змян. Аднак точнасць — не ўсё, што берацца ў расчыт. Кожна працоўка таксама фіксуе час адпаведзення, каб апыт вядомаў быў рэактыўным, а таксама колькасць токенаў, якая безпасэродна вяснаўаеся з вітратамі на мадэль. Змяны, якія пагоршуюць адна з гэтых характэрыстыкаў, фіксуюцца ўцёмкі пры падготовцы да выпуску.
Захаванне бюджэту і магчымасцей
Асістэнт, які працуе ўсё час і выкарыстоўвае API для працы, патрабуе лімітаў, якія захоўваюць як бюджэт мадэлі, так і сэрвісы, якія яе падтрымліваюць. Існуе тры слоі захоплення:
- Квоты на адного карыстальніка. Акаунты-дэманстрацыі даўаюць 10 паведамленняў на дзень, што дазволяе заінтэрэсаваным партнерам прыступіць да ўжыцця без несканчатных вітатаў на мадэль, і спакушае іх перэйсці на акаунт-партнера, калі яны хочуць асэрйознай працы.
- Выклікі, якія маюць чыткія межы і можна прызначыць ўсё, што з імі сталося. Трафік партнера праходзіць праз яго сабеўласненыя крантэнціі, таму кожны выклік урахоўваецца ў яго квоце і прадстаўляецца ў яго сабеўласненай летапісе. Асістэнт ніколі не выдавае ся за спільны адказвальны акаунт, і самэ гэта дазволяе ведаць, хто выкорыстоўвае сервіс, і выкрываць зловжывання.
- Праказы, якія розумеюць прычыны неудач. Калі запыт не выйшаў, укладаючы ў сябе тымчасавы адказ пра обмежэння, цыкл праказ перадае адказ пра адказ на модэль, падымае лічылкі праказ і пракладывае іх занова да настаўленага максімуму. Калі праказы выкаранаць, сістэма пераходзіць у рэжым радчыка.
Зробленае прыступленне простым
Стварэнне асістэнта было толькі паловай працы. Не менш важлівым было забезпечыць безпечнае і простае прыступленне.
API-яя платформы традыцыйна выкарыстоўвалі стандартныя крантэнцыялі кліента, што значыла неабходнасць ручнага налагаджэння для кожнага новага кліента. Для асістэнта, прызначанага для зовнішніх партнероў, падход «запрашыць і чакаць на затверджэння ад інжынераў» не быў прыйняцым. Прасіць распрацоўшчыкаў прыкласты токены ў чат таксама не было лепшым рашэннем, адтолькі ўсё гэта ускладняла розлічэнне вызоваў, створаных асістэнтам, і вызоваў, атрыбутаваных ручна, а таксама ускладняла контроль за выкарыстоўванням і безпекай. Командзе была неабходна адна стратэгія, якая бы падтрымвала два тыпы корыстувачаў: партнероў, якія хочуць працаваць у сэрвісе без перакантрольных процэсаў, і тых, хто готавы выкарыстоўваць рэальныя даны, без неабходнасці ручнага налагаджэння.
Рашэннем стала двауровневая, самаслужбовая модэль, якая працюе пасля звычайнага заходжэння распрацоўшчыка.
- Рэжым дэмаверыянту ўважаецца стандартным. Новыя корыстувачы можаць адразу ж ведаць дыялог з асістэнтам за дапамогою сінтэтычных даных, без неабходнасці налагаджэння, чакання чы прасункі.
- Рэжым партнера актываецца, калі распрацоўшчык хочаць жывую інтэграцыю. Даныя аб’явлення прыходзяць праз адзінразовы працэс автарызацыі, які адбываецца самастойна і прыяўляеся да сабеўскага акаунта распрацоўшчыка і яго праваў. Пасля падключэння кожны запіт прыналежыць той самой ідэнтычнасці і ўсё абоўязкова фіксуецца, таму ясна, хто выканана запыт і пры якім шляху.
Гэта усунула галоўную пераканальнюю перашкоду. Пераход з стану «Меня цікавіць» у стан «Я інтэгрую» больш не выклікае чакання ў інжынерскай лініі.
Куды далей
Праект пачаўся як внутршняе эксперымент і зараз ў этапы бета-версіі, якая скрацвае час інтэграцыі для корпаратыўных команд распрацоўшчыкаў. Ён працуе ў портале распрацоўшчыкаў і ужо прыjęў свой першы група партнероў.
Аранжавальнік чытае стандартныя схемы OpenAPI, таму архітэктура прызначаная для гораздкага расшырэння. Настаўныя зусіллі сфокусаваны на перакананні ў правільнасці дадзеных у сферэ мобільнасці, але ядро маршрутызацыі спецыяльна зроблена гэнерычным. У планах — перанесенне таго ж слоя для ведчыння дыялога ў іншыя падраздэленні, такія як платэжныя сістэмы і платформы з паўтаральнымі выгодамі, адключэнне болей рэзалютных методаў пераканання ў правільнасці дадзеных за дапамогою OData, каб большае колькасць некорэктных запыткаў была зупіненая ўсерэдзіні асістэнта, а таксама апранаванне механізмаў паўтарнай паўтаркі дзеянняў чалавекам для операцый з змінай дадзеных, каб асістэнт у канцэ насуперак мог у безпечны спосаб разважваць зміны ў рабочых працэсах.
Супаўзеўныя матэрыялы
- Адзін пратэптак да працэйнага стану: Агентныя AI-сістэмы з LangChain, LangGraph і Azure — Гібрыдны пошук, кэшы эмбедынга, маршрутызацыя праз LangGraph, прыстроі за захаванне працы, тэсты на рэгрэсію з «золатым» наборам дадзеных і трэйсінг для агента для обработкі падаткаў, з прадставленымі рэзультатамі.
- Графы знанняя для агентных AI: Чатыры патэрна, якія выходзяць за межы Vector RAG — Вектарны пошук знаходзіць падобны тэкст, а не сувязаныя факты. Чатыры патэрна графаў для агентаў: стварэнне падказак на адной основе, планаванне, перакананне ў выкананні і самаактуалізацыя.