Управление на агентски инструмент чрез AI API Gateway: обхвати, одобрения, бюджети и одитни пътеки

Рискът на агента вече не е ограничен до подканата на модела. Производственият агент може да търси във вътрешни файлове, да прави заявки в записи на клиенти, да се обажда на MCP сървър, да изпълнява код, да отваря браузър, да изпраща имейл, да актуализира CRM или да задейства работен поток за таксуване. Въпросът за управлението става: на кой потребител, ключ, модел, агент и инструмент е разрешено да предприеме какво действие, с какъв бюджет, одитна пътека и път за връщане назад?

Ако всеки екип управлява достъпа до инструмента в собствения си SDK код, правилата се разпръскват между променливи на средата, табла за управление на доставчици, междинен софтуер на приложения и недокументирани MCP сървъри. По-безопасен модел е да се третира изпълнението на инструмента на агента като проблем на контролната равнина и да се наложи чрез AI API шлюз или стандартна обвивка за изпълнение на инструмент, която всеки агент трябва да използва.

Тази статия разделя фактите, препоръките и прогнозите. Фактите са извлечени от настоящите публични насоки: Топ 10 на приложението за LLM на OWASP включва рискове като разкриване на чувствителна информация, уязвимости на веригата за доставки и прекомерна агенция; Генеративният AI профил на NIST за рамката за управление на риска от AI набляга на картографирането, измерването и управлението на генериращите рискове от AI; Указанията на агента на OpenAI препоръчват оценка на риска от инструмента чрез достъп за четене/запис, обратимост, разрешения и финансово въздействие; и MCP ръководството за оторизация използва концепции за оторизация с обхват за чувствителни ресурси и операции. Препоръките по-долу са модели за внедряване, а не универсални изисквания.

Проблемът с четеца: достъпът до модела и достъпът до инструменти се бъркат

В много ранни LLM приложения ключ API отговаряше на един основен въпрос: може ли тази услуга да извика модел? Агентите правят това твърде грубо. Ключ, който може да изпраща завършвания на чат, не трябва да може автоматично да експортира клиентски данни, да изпълнява команди на обвивката, да публикува в Slack, да променя билети, да разглежда произволни уебсайтове или да изпраща промени в плащанията.

Управленският слой трябва да отговори на по-конкретни въпроси:

• Кой наемател, работно пространство, потребител, акаунт за услуга или клиент на дистрибутор е инициирал изпълнението?
• Кой модел, шаблон за подкана, версия на агент и схема на инструмента са използвани?
• Исканият инструмент беше ли само за четене, обратим, необратим, външен, финансов или привилегирован?
• Заявителят имаше ли необходимия обхват?
• Беше ли изисквано, дадено, отказано, изтекло или заобиколено одобрение от правилата за спешни случаи?
• Какво струва инструментът, колко пъти е бил извикван и какъв кумулативен бюджет остава?
• Какви доказателства съществуват за отстраняване на грешки, преглед на съответствието и връщане назад?

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

Референтна архитектура: слой за управление на инструмент на ниво шлюз

Практичната система за управление на агенти има седем компонента:

1. Регистър на инструментите: авторитетният списък с одобрени инструменти, MCP сървъри, хоствани функции, локални инструменти за изпълнение и вътрешни API.
2. Слой за самоличност и ключ: ключове за шлюз, потребители, наематели, акаунти за услуги, екипи и клиенти на дистрибутори.
3. Scope engine: проверки на правилата, които решават дали даден ключ или потребител може да извика конкретна възможност на инструмента.
4. Класификатор на риска: метаданни, които описват радиус на взрив, чувствителност на данните, обратимост, външно въздействие и излагане на разходи.
5. Работен процес на одобрение: одобрение от човек или система за високорискови действия преди изпълнение.
6. Легер за бюджет и лимит на скоростта: лимити за инструмент и за агент, а не само лимити за токени за модел.
7. Съхранение за одит и проследяване: обединени записи за извиквания на модели, извиквания на инструменти, одобрения, грешки и резултати.

Важното дизайнерско решение е шлюзът да бъде точка за вземане на решения, дори ако действителният инструмент работи другаде. Например, инструмент за браузър може да се изпълни в работна среда в пясъчна среда, а CRM запис може да се изпълни във вътрешна услуга. Шлюзът все още оценява дали повикването е разрешено, записва решението, проследява разходите и връща подписано решение за оторизация или отказ.

Стъпка 1: Създайте централен регистър на инструменти

Регистърът на инструментите е инвентаризацията, която предотвратява „способността на неизвестен агент“ да стане стандартна. Всеки инструмент трябва да има собственик, ниво на риска и оперативни метаданни. Минимален запис в регистъра може да изглежда така:

{
  "tool_id": "crm.create_ticket",
  "display_name": "Create CRM support ticket",
  "owner_team": "support-automation",
  "execution_type": "internal_api",
  "server_url": "https://tools.internal.example/crm",
  "allowed_tenants": ["enterprise", "support"],
  "allowed_models": ["general-large", "general-fast"],
  "risk_tier": "reversible_write",
  "data_classification": "customer_metadata",
  "required_scopes": ["tool:crm.create_ticket"],
  "approval_policy": "not_required_under_100_tickets_per_day",
  "default_timeout_ms": 8000,
  "max_cost_per_call_usd": 0.05,
  "max_calls_per_run": 3,
  "rollback_owner": "support-ops-oncall",
  "retention_policy": "redacted_30_days"
}

За MCP сървъри регистърът трябва също така да включва URL адреса на сървъра, рекламирани инструменти, версия на схемата, метод за оторизация, дата на последен преглед и дали новите инструменти са деактивирани по подразбиране. MCP подобрява оперативната съвместимост, но съвместимостта на протокола не е същото като разрешението за производство. Чувствителните ресурси и операции все още се нуждаят от изрични обхвати, проверки на маршрути и изолация на клиента.

Препоръчителни полета в регистъра

• Име на инструмента, каноничен идентификатор, собственик и контакт на повикване.
• Местоположение на изпълнение: инструмент на хостван доставчик, MCP сървър, вътрешен API, браузър работещ, изпълняващ код, задание на опашка или локален SDK инструмент.
• Разрешени наематели, екипи, потребители, версии на агенти и профили на модели.
• Класификация на данните: публични, вътрешни, клиентски метаданни, клиентско съдържание, тайни, данни за плащане, идентификационни данни, регулирани данни.
• Ниво на риска и обратимост.
• Необходими обхвати и правила за одобрение.
• Время на изчакване, ограничения на скоростта, максимални обаждания на изпълнение, кумулативен бюджет за изпълнение и максимална цена на повикване.
• Режим на регистриране: пълният полезен товар е забранен, редактиран, хеширан, семплиран или изрично запазен.
• Инструкции за връщане назад и път за ескалация.

Стъпка 2: Отделете обхватите на модела от обхватите на инструмента

Ключът на производствения шлюз трябва да изразява какво може да направи повикващият. Достъпът до модела и достъпът до инструмента трябва да са независими. Например:

model:chat
model:embeddings
tool:docs.search_readonly
tool:crm.create_ticket
tool:email.send_requires_approval
tool:billing.refund_blocked
tool:code.execute_blocked

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

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

Препоръката е да се затвори неуспешно: неизвестните инструменти се отказват, липсващите обхвати отказват изпълнение, новообявените MCP инструменти са неактивни, докато не бъдат одобрени, а локалните инструменти трябва да използват същата обвивка на правила като хостваните инструменти.

Стъпка 3: Класифициране на инструментите по радиус на взрив

Не всяко извикване на инструмент изисква човешко одобрение. Управлението трябва да бъде пропорционално на риска. Полезен класификационен модел е:

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

Стъпка 4: Добавяне на пропуски за одобрение за високорискови действия

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

Общ поток на одобрение:

1. Агентът изисква извикване на инструмент със структурирани аргументи.
2. Шлюзът оценява самоличността, обхвата, нивото на риска, бюджета и политиката.
3. Ако се изисква одобрение, шлюзът връща чакащо одобрение събитие, вместо да изпълни инструмента.
4. Приложението показва визуализация на потребителя или изпраща известие за операции до канал за одобрение.
5. Одобряващият може да одобри, откаже, редактира аргументи, ако правилата позволяват, или да поиска пояснение.
6. Шлюзът записва решението и изпълнява само одобрената версия.

Полезният товар за одобрение трябва да показва действието от човешка гледна точка, а не само необработен JSON:

{
  "approval_id": "appr_123",
  "agent_run_id": "run_456",
  "requested_by_user": "user_789",
  "tool_id": "email.send",
  "risk_tier": "external_communication",
  "summary": "Send a reply to customer@example.com about ticket #4812",
  "redacted_arguments": {
    "to": "customer@example.com",
    "subject": "Update on ticket #4812",
    "body_hash": "sha256:..."
  },
  "expires_at": "2026-08-09T12:30:00Z"
}

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

Стъпка 5: Проследяване на бюджетите за всеки инструмент и лимитите на скоростта

Бюджетите за токени не са достатъчни. Един евтин модел може да предизвика скъпи търсения, сесии на браузъра, изпълнение на код, API извиквания на трети страни или дълги цикли на инструмента. Шлюзът трябва да проследява поне четири брояча:

• Брой извиквания на инструмент: максимален брой извиквания на изпълнение, потребител, наемател и времеви прозорец.
• Разходи за инструмент: директни такси на трета страна, разходи за браузър/време на изпълнение, разходи за търсене или прогноза за вътрешно връщане на плащане.
• Кумулативни разходи за управление на агент: токени за модели плюс разходи за инструменти.
• Дълбочина на цикъла: максимален брой итерации модел-инструмент-модел.

Когато се достигне ограничение, шлюзът трябва да избягва тиха твърда повреда, когато е възможно. По-безопасните модели на деградация включват връщане на обобщение на напредъка, искане на одобрение за продължаване, намаляване на дълбочината на извличане, поставяне на фоново задание на опашка или превключване към режим само за четене. Твърдият отказ все още е подходящ за блокирани инструменти, липсващи обхвати, неизвестни MCP възможности и опасни действия.

Стъпка 6: Свържете телеметрията на модела и инструмента в един одитен запис

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

• Ключ за наемател, работно пространство, потребител, акаунт за услуга и шлюз.
• ID на агента, версия на агента, версия на шаблона за подкана и ID на модел.
• Име на инструмента, версия на регистъра, URL адрес на сървъра или среда за изпълнение и хеш на схемата.
• Въведен хеш на инструмента или редактиран вход, никога необработени чувствителни полезни данни по подразбиране.
• Статус на одобрение, самоличност на одобряващия, клеймо за време на одобрение и одобрен хеш на аргумента.
• Забавяне, повторни опити, грешки на доставчика, грешки на инструмента, цена на токена, цена на инструмента и краен резултат.
• Справка за връщане назад, ако действието е променило състоянието.

OpenAI SDK включва проследявания за генериране на LLM, извиквания на инструменти, предавания, предпазни огради и персонализирани събития, което поддържа по-широк принцип за наблюдение: проследяванията на агенти трябва да включват дейност на инструмента, не само използване на токени и закъснение. Въпреки това, един SDK тръбопровод може да не покрива всеки хостван инструмент, локален път за изпълнение или вътрешен API. Одитът на ниво шлюз помага за нормализиране на записите между доставчици и рамки.

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

Стъпка 7: Третирайте MCP сървърите и инструментите на трети страни като зависимости от веригата за доставки

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

• Поддържайте разрешен списък с одобрени MCP сървъри и източници на инструменти.
• Закачете версии, където е възможно, и запишете хешовете на схемата.
• Изискване на собственик за всеки сървър и инструмент с висок риск.
• Прегледайте имената на инструментите, описанията, схемите и исканията за разрешения, преди да ги активирате.
• Деактивирайте новодобавените инструменти, докато не бъдат прегледани.
• Проверете необходимите обхвати за маршрут или възможност.
• Разделете идентификационните данни на клиента и избягвайте споделени токени между клиенти.
• Изпълнявайте ненадеждни или високорискови инструменти в тестови среди с ограничения на мрежата и файловата система.

Фактът, че даден инструмент е изложен чрез стандартен протокол, не го прави безопасен. Слоят на управление все още се нуждае от най-малко привилегии, изрично разрешение, контрол на версиите и възможност за проверка.

Контролен списък за внедряване

Дизайн на политика

• Дефинирайте шаблони за роли за общи потребители на агенти и акаунти за услуги.
• Създайте отделни обхвати за извиквания на модели и извиквания на инструменти.
• Класифицирайте инструментите по чувствителност на данните, обратимост, външно въздействие, финансово въздействие и ниво на привилегия.
• Задаване на поведение за отказ по подразбиране за неизвестни инструменти и липсващи обхвати.
• Дефинирайте правила за одобрение само за високорискови действия.

Налагане на Gateway

• Изискване от всеки агент да извиква инструменти през шлюза или подписана обвивка на правила.
• Проверете наемател, потребител, ключ, агент, модел, инструмент, обхват, бюджет и статус на одобрение преди изпълнение.
• Налагане на максимална дълбочина на извикване на инструмента и кумулативни разходи за изпълнение.
• Записване на версията на регистъра на инструмента и хеша на схемата за всяко повикване.
• Неуспешно затваряне, когато машината за правила не може да вземе решение.

Одит и операции

• Свържете извикванията на модела и извикванията на инструмента под един ID на трасиране или изпълнение на агент.
• Редактиране или хеширане на чувствителни входове на инструменти по подразбиране.
• Съхранявайте доказателства за одобрение с окончателния запис на изпълнение.
• Изложете на администраторите анализа на цената на инструмента и лимита на скоростта.
• Собственици на връщане на документи за инструменти, които променят състоянието.

Очаквани компромиси

Постоянство срещу усилие за интегриране. Управлението на ниво шлюз осигурява последователно прилагане в модели, SDK и екипи. Цената е приемане: разработчиците трябва да маршрутизират изпълнението на инструмента през одобрения път, вместо да извикват инструменти директно от кода на приложението.

Най-малко привилегии срещу сложност на правилата. Фино детайлизираните обхвати намаляват радиуса на взривяване, но изискват шаблони, правила за именуване и редовно почистване. Без шаблони екипите може да предоставят повече разрешения, за да се движат по-бързо.

Одобрение срещу автономност. Човешкото одобрение намалява риска от необратими действия, но добавя забавяне. Използвайте одобрения за инструменти с висок риск, а не за всяко търсене.

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

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

Прогнози: накъде се насочва този модел

Прогноза: управлението на агентите ще стане по-ориентирано към самоличността. Екипите ще питат по-рядко „кой модел използва този?“ и по-често „кое удостоверено лице или услуга е позволило това действие на инструмента?“

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

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

Приложимо заключение

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

Целта не е да направим агентите безсилни. Целта е силата им да бъде четлива, обхватна, обратима, където е възможно, и отчетна. Това е практическата основа за управлението на екип API, тъй като агентите преминават от отговаряне на въпроси към предприемане на действия.

Свързано четене

• екип API практики за изолиране и ротация на ключове
• съединени проследявания, регистри на токени и безопасна подкана регистриране
• структурирани изходи и модели за валидиране на извикване на инструменти