API, готови за ИИ агенти: какво е нужно на вашата система, за да я използва агентът под контрол

Клиент моли ИИ асистента на своята банка да плати сметката за ток от неговата сметка. Асистентът — агент: програма, която при дадена инструкция сама решава кои системи да извика и в какъв ред — извиква API-то за плащания. Отговорът се бави, връзката прекъсва. Агентът не знае дали плащането е минало, затова прави това, което би направила всяка програма: опитва отново. Ако API-то няма начин да разпознае, че това е същото плащане, клиентът остава с двойно таксуване, отворена рекламация и лошо мнение за своята банка.

За този сценарий не е нужен злонамерен агент, нито лош модел. Достатъчно е едно API, проектирано, както повечето, за програмист, който чете документацията, познава бизнеса и знае какво да направи, когато нещо се провали. Агентът може да няма този контекст и тогава всяка неяснота в контракта се превръща в погрешно действие.

Заменете плащането с издаване на полица, с поръчка, която намалява наличността, с превод към дигитален портфейл или с фактура, която се заверява с цифров печат (timbrado) пред SAT (данъчната администрация на Мексико), и проблемът е от същото семейство. Тази статия е за онези, които отговарят за такива системи в банка, финтех компания, застраховател, търговска верига или друга регулирана компания.

Все повече API ще имат този нов потребител. В проучването на Postman от 2025 г. — доставчик на инструменти за API, с над 5 700 участници — 24 % от разработчиците са казали, че проектират своите API с мисъл за агенти; 60 % ги проектират основно за хора [1]. Тази статия обяснява какво липсва на едно API, за да го ползва агентът под контрол, кои от тези елементи вече са стандарт и кои не, и как да стигнете дотам, без да пренаписвате системите си.

Свързването не е същото като подготовката

Днес е лесно да «свържете» едно API с агент. Протоколът MCP, който вече обяснихме в този блог, и gateway-ите на няколко доставчици — Microsoft, AWS, Google, Kong и Cloudflare, наред с други — могат да превърнат един контракт OpenAPI в инструменти, които агентът извиква [2]. Договорът в този контекст е формалното, четимо за машина описание на това, което прави всяка операция на едно API и какво приема тя.

Преобразуването на контракта решава свързването, но не и контрола. Един академичен препринт е прегледал 116 официални MCP сървъра и 80 контракта OpenAPI. В тази извадка 92 % от сървърите само са обвивали API-то такова, каквото е, и са излагали медиана от 19 % от неговите операции. Интересното дойде после: когато авторите коригирали контрактите автоматично — описания, параметри, групиране — делът на инструментите, които работят добре, се повишил от 76 % на 94,2 % [3].

Поуката: първото тясно място не е конекторът, а качеството на контракта. Преобразуването на 200 операции в 200 инструмента не му дава 200 способности; дава му 200 възможности да сгреши.

Седемте свойства на едно API, което агентът може да използва

1. Обяснява се само

Един програмист може да попита какво означава параметърът type. Агентът в най-добрия случай го извежда логически; в най-лошия налучква. Затова всяка операция трябва да казва какво прави за бизнеса, а не само какви типове данни получава: «Отменя планираното плащане, ако още не е изпълнено; вече изпълнените плащания се сторнират с друга операция». OpenAPI 3.2, действащата спецификация за описание на API, предоставя местата, където това се пише: стабилен идентификатор на операция, описания, примери и начин да се декларират известията, които API-то изпраща, когато приключи дълъг процес [4]. Цитираният по-горе препринт е точно доказателство, че поправянето на тези описания подобрява работата на агента [3].

Една подробност, която почти никой не споменава: самата спецификация на MCP предупреждава, че описанията и анотациите на един инструмент не са надеждни, освен ако не идват от доверен сървър [6]. Инструмент, който се представя за «само за четене», не става безопасен само защото го твърди. Сигурността се поставя в API-то, а не в описанието.

2. Последователно е

Ако една операция връща датите в един формат, а друга в друг, агентът трябва да научи всяко изключение. А разликата между «не знам кой сте» и «знам кой сте, но нямате разрешение» е по-важна, отколкото изглежда: при първото агентът се опитва да поднови идентификационните си данни; при второто би трябвало да спре или да поиска разрешение. API, което ги бърка, праща агента да подновява идентификационни данни в кръг, като изразходва квоти и препълва дневниците. Тази разлика е дефинирана в стандарта HTTP (кодовете 401 и 403, в RFC 9110) [7], а ръководството на IETF за изграждане върху HTTP призовава да не се преоткриват тези значения [8].

3. Грешките му учат как да се поправи

Когато едно извикване се провали, съобщението за грешка е най-прякото ръководство, което агентът има. «Невалиден вход» го праща да пробва на сляпо; «сумата трябва да е по-голяма от нула и по-малка от дневния лимит на сметката» му позволява да се коригира с един опит.

За това вече има стандарт: RFC 9457 (2023) определя формат на грешка, който една машина може да чете — тип на проблема, заглавие, статус и подробности, плюс полетата, които всяко API има нужда да добави — и замества RFC 7807 [9]. Не е нужно да измисляте собствена схема; нужно е да използвате вече съществуващата, във всички операции, и във всяка грешка да казвате дали си струва да се повтаря. При баланс: грешката трябва да е конкретна, без да разкрива вътрешността на системата.

4. Повторението не дублира

Агентите повтарят; това е част от начина, по който работят. Ако едно извикване прекъсне, те не знаят дали операцията е приложена. При справка не се случва нищо. При плащане, полица или движение на наличности повторението може да изпълни операцията два пъти.

Известното решение е ключът за идемпотентност: клиентът изпраща уникален идентификатор с всяка операция и ако я повтори със същия ключ, API-то връща първоначалния резултат, вместо да я изпълни отново. Преди да го внедрите, е добре да знаете две неща:

• Не е стандарт. Проектът на IETF за заглавието Idempotency-Key достигна версия 07 през октомври 2025 г. и днес фигурира като изтекъл и архивиран, без да е станал RFC [10]. Затова всяко API трябва да публикува собствените си правила: колко време пази ключа, как сравнява повторената заявка и какво отговаря, ако същият ключ пристигне с друго съдържание или докато първата заявка още се обработва. Проектът е разграничавал тези случаи с различни отговори [10].
• Важното е какво става, когато нещо се провали. Stripe, еталонът по темата, запазва резултата от първото изпълнение, дори да е била грешка на сървъра [11]. С прости думи: ако първият опит е останал под съмнение, повторението не таксува отново; отговаря на клиента «това остана така, проверете, преди да опитате друго».

И не всичко трябва да се повтаря. Google в своето ръководство за проектиране на API автоматично повтаря заявките при преходни грешки — недостъпност, изтекли срокове — и приема изчерпаната квота за по принцип неповторяема, освен в документирани случаи [12]. Ако вашето API не казва кое може да се повтаря, агентът ще налучква.

5. Отговаря винаги в една и съща форма

Агентът чете свободен текст без проблем; трудно му е със структура, която се променя: поле, което понякога е текст, понякога обект, а понякога липсва. Празният списък трябва да е празен списък, а не липса на списък. Операциите, които отнемат време, имат нужда от свой собствен модел: да отговорят веднага, че заявката е приета, с място, където да се проверява състоянието ѝ, вместо да оставят агента да чака.

А за една регулирана компания състоянието на една операция би трябвало да разграничава поне пет изхода: отхвърлена, незапочната, в процес, завършена и неизвестен резултат. Последният е най-често забравяният и причинява най-много проблеми, защото е точно онзи, който предизвиква повторението от началния пример.

Когато една процедура засяга няколко операции — например регистрация на клиент, която минава през три системи — спецификацията Arazzo позволява да се опише целият поток стъпка по стъпка, така че агентът да не трябва да отгатва реда [18].

6. Известява колко му остава

Агент с грешка в логиката си може да направи хиляди извиквания за една нощ, а всяко от тях използва капацитет на API-то и често също токени на модела, който го плаща. Ако API-то му казва във всеки отговор колко му остава от квотата и кога се подновява, агентът може да намали темпото, преди да се блъсне. Когато се блъсне, API-то може да отговори с код 429 («твърде много заявки», RFC 6585) и да включи заглавието Retry-After, за да укаже кога да се опита отново [5][7]. GitHub например изисква да се изчака това време и, ако го няма, да се удължава изчакването постепенно; настояването може да блокира интеграцията [14].

Стандартът за заглавията, които съобщават квотата, все още е проект в IETF, във версия 11 от май 2026 г., и формата му се е променяла между версиите [15]. Разумното е да изберете една конвенция, да я документирате и да я прилагате еднакво във всички операции.

7. Предупреждава, преди да се оттегли

API-тата се променят. Програмистът чете имейла, който обявява оттеглянето на една версия; агентът не. Днес за това вече има стандарт: заглавието Deprecation е публикувано като RFC 9745 през 2025 г., а заглавието Sunset, което показва кога API-то ще спре да отговаря, като RFC 8594 [16][17]. С тях агентът може да открие навреме, че трябва да премине към новата версия.

Кое вече е стандарт и кое не

Тази таблица е най-полезното нещо, което да имате под ръка, преди да проектирате. Смесването на проект със стандарт е най-бързият начин да построите нещо, което по-късно ще трябва да се променя.

Стандарт: RFC, публикуван от IETF по пътя на стандартите. Проект: работа в ход, която може да се промени или да бъде изоставена. Информативен RFC: ръководство, което не е задължително. Нито един от тях сам по себе си не е правно задължение.

Редовете, отбелязани като стандарт, не търпят много спорове: те са препратката, която е добре да следвате. Редовете с проект са проектантски решения, които всяка компания трябва да вземе и документира, и именно те се различават най-много от една организация до друга.

Как изглежда във вашия отрасъл

Седемте свойства са едни и същи навсякъде; променя се това, което се чупи, когато липсват. Пет сценария, по един за отрасъл, илюстративни и без клиент:

Във всички случаи се повтаря един и същ модел: API с изрични състояния намалява риска едно повторение да навреди и работи заедно с контролите за самоличност, упълномощаване и съгласуване, които ще видим след малко.

Сигурността не може да се остави на модела

Тук е точката, която тежи най-много за банка, финтех компания, застраховател, търговска верига с данни на милиони клиенти или всяка друга регулирана компания: един агент може да бъде заблуден от данните, които чете. Един имейл, един документ или отговорът на друг инструмент могат да носят скрити инструкции, а агентът може да ги последва. Това се нарича индиректно инжектиране на инструкции и OWASP го поставя като първия риск на приложенията с езикови модели [22].

Неудобното е, че няма безгрешен детектор, и самата OWASP го признава [22]. Група изследователи атакувала дванадесет публикувани защити, няколко от тях с отчетен успех, близък до нула, и надвишила 90 % успех срещу повечето, когато адаптирала атаките си [23]. Институтът за безопасност на ИИ към NIST открил нещо подобно в симулирана офис среда: при същия модел най-добрата позната атака успяла в 11 % от случаите, а нова атака — в 81 % [24]. Поуката не е обща степен на уязвимост: тя е, че защита, изпитана само срещу познати атаки, не е доказана. А случаят EchoLeak, в масово използван корпоративен асистент, показа, че един-единствен имейл, без никой да щракне, е могъл да изтегли вътрешни данни [25][34].

Практичното заключение не е «не използвайте агенти». То е да се ограничи вредата в API-то, което вие контролирате, вместо да се обещава, че моделът никога няма да сгреши. Започва с разделянето на това, което един агент може да прави, на три нива:

И върху това разделяне — четири контрола, които живеят в API-то, а не в модела:

• Собствена самоличност за всеки агент. Идентификационни данни на машина, а не на човек. Когато агентът действа от името на клиент или служител, размяната на токени позволява да се представи кой на кого е делегирал [21]; запазването на това доказателство е решение за конфигурация и за дневник, което трябва да се изисква. А идентификационните данни могат да се свържат с този, който ги използва, така че откраднати данни да не вършат работа на друг [19][20]. Инцидентът с интеграцията Salesloft Drift през 2025 г. беше точно това: откраднати идентификационни данни на интеграция, използвани със заявки, които изглеждали валидни [26]. Това е същата дисциплина на достъпа, която е добре да се прилага и към хората, и я обясняваме в Контрол на достъпа.
• Минимални права за всяка операция. Агент, който проверява наличностите, няма нужда да може да изтрива клиенти.
• Суми, лимити и правила за упълномощаване в API-то, извън модела.
• Дневник на всяко действие: кой агент, от чие име, с какво разрешение, какво е поискал, кой е одобрил и какво се е случило.

Спецификацията на MCP върви в същата посока: когато се използва нейното упълномощаване, изисква да се провери, че токенът е издаден за този сървър, и забранява препращането на токена на потребителя към други услуги [6].

В Мексико освен това има закон

Две норми променят разговора. Първата се прилага във всички отрасли; втората — във финансовия сектор. Те не заместват прегледа от вашия юридически отдел, но е добре да са на радара още от проектирането:

• За банки и финтех — Ley Fintech (мексиканският закон за финтех институциите) задължава, в своя член 76, данните да се споделят чрез стандартизирани API, на три равнища: отворени, агрегирани и транзакционни данни. Регулаторното прилагане не е еднородно: зависи от вида на институцията, от данните и от органа. Banxico например издаде през 2020 г. разпоредби, които предвиждат трите равнища за кредитните информационни дружества и клиринговите къщи [13]. А текстът на закона вече съдържа контрол, който е точно това, което един агент изисква: достъпът на трета страна се прекъсва веднага щом клиентът оттегли съгласието си, бъдат открити уязвимости или третата страна наруши изискванията, и прекъсването се съобщава на органа не по-късно от два часа [27]. За интерфейсите, подчинени на този член, да може да се отнеме достъп без сложни ръчни действия не е лукс; за останалите това е контрол, който си струва да се има.
• За всички отрасли — включително застраховането и ритейла — новата Ley Federal de Protección de Datos Personales en Posesión de los Particulares (LFPDPPP, Федерален закон за защита на личните данни у частните лица), публикувана през март 2025 г., дава на титуляря на данните правото да възрази срещу автоматизирана обработка, която, без човешка намеса, оценява аспекти като неговото икономическо положение или поведение и му причинява нежелани правни последици [28]. Ако един поток с агенти прави такава оценка, трябва да се прегледа спрямо това правило. И във всеки случай законът изисква мерки за сигурност, пропорционални на риска: използването на данни от агент е част от обработката и влиза в същия анализ на рисковете и контролите [28].

В повечето случаи системите ви не се пренаписват: поставя им се фасада

Никоя банка няма да пренапише своята основна система, никой застраховател — системата си за полици, и никоя верига — своя ERP или касова система (POS), за да ги използва езиков модел, и в повечето случаи не е нужно. Пътят, който препоръчва литературата за модернизация — и който следват самите производители — е фасада: слой, който излага на агента ясни бизнес операции — проверка на салдо, оферта за полица, регистриране на връщане, започване на плащане, проверка на състоянието на фактура — и който отвътре превежда на езика на съществуващата система [29].

Три решения определят дали тази фасада помага или пречи:

• Какво се излага. Тесни бизнес операции, а не таблици или общи вътрешни транзакции. Агент с достъп до «изпълни всяка транзакция» не е агент с възможности: той е риск.
• Какви отговорности остават във фасадата и какви в изходната система. Ръководството на Microsoft за този модел предупреждава, че слоят за превод добавя забавяне и още една услуга за поддържане, и препоръчва да не се превръща в мястото на бизнес правилата [29]; ако започне да решава това, което преди е решавала основната система, става още една наследена система.
• С какво доказателство. Всяка изложена операция трябва да може да покаже това, което обещава нейният контракт: че не дублира, че може да се отнеме, че оставя следа.

Производителите вървят в тази посока: SAP предлага своя слой за управление на API, за да постави удостоверяване, квоти и мониторинг върху съществуващи услуги [30], а IBM излага системи на мейнфрейм като API, описани с OpenAPI [31]. Технологията на фасадата съществува; трудното — и това, в което най-често се греши — е да се реши какво се излага, с какви правила и с какво доказателство.

Какво става, ако не се направи нищо

Бизнес звената няма да чакат. Ако API-то не е готово, някой все пак ще свърже агент: с лични идентификационни данни, без дневник и с повече права, отколкото му трябват. Типичният резултат не е сложна атака; това е двойно таксуване, което стига до рекламация, изчерпана квота посред нощ или изтекли идентификационни данни на интеграция, както в цитираните по-горе инциденти. Подготовката предварително обикновено струва по-малко от обясненията след това.

Как да разберете дали работи

Единичният успех не казва нищо; доверието се мери с последователността. Бенчмаркът τ-bench от 2024 г. предложи да се мери колко пъти един агент решава една и съща задача, ако му я повторят. В неговите тестове водещ модел от онзи момент решаваше по-малко от половината задачи, а в областта на търговията — по-малко от една четвърт, когато се изискваше да успее осем пъти поред [32]. Цифрите от онази година вече са се променили; методът остава правилният: да се мерят цели задачи, няколко пъти, с крайното им състояние, и отделно да се мерят опитите за атака [33].

Бъдете недоверчиви към кръглите цели, които циркулират в материали на доставчици, като «85 % успех от първия опит» или «под 1,5 повторения». Не открихме нито един независим източник, който да ги подкрепя. Целите се определят със собствените ви данни.

Откъде да започнете

1. За диагностиката приоритизирайте по риск. Операциите, които записват или променят данни — плащания, полици, поръчки, наличности, фактури — са тези, които могат да навредят най-много, ако агентът ги използва зле; затова се преглеждат първи.
2. За първия случай на употреба изберете нещо ограничено. Една справка или обратима операция с изрично одобрение. Агентът, който движи пари, идва по-късно, с доказателства.
3. Поправете на място това, което може. Добавянето на описания, стандартни грешки и заглавия за квота обикновено е съвместимо със сегашните клиенти, защото повечето игнорират новите полета; въпреки това първо се тества срещу съществуващите ви интеграции. Ако екипът ви програмира на TypeScript, урокът „Сървърът“ от нашия отворен курс упражнява точно това: кодове за състояние и договори, които не разкриват вътрешни данни.
4. Поставете фасада там, където не може да се пипа, с тесни бизнес операции, идемпотентност и дневник.
5. Изпитайте с реални агенти и мерете последователността, преди да им отворите вратата към продукцията.

Да знаете кой стандарт да използвате е лесната част. Трудното е да знаете кои от вашите операции са готови, кои могат да се поправят на място, кои се нуждаят от фасада и кои контроли не могат да се делегират на агент. Това е, което преглеждаме в една диагностика: предаваме ви картата на вашите критични операции, рисковете за контрола, които открихме, и реда, в който е уместно да се заемете с тях, така че ИТ, сигурността, рискът и бизнесът да вземат решение със същата информация, като винаги се стремим да не пренаписваме вашите системи.