Správa nástroje agenta prostřednictvím brány AI API: Rozsahy, schválení, rozpočty a kontrolní záznamy
Praktická referenční architektura pro řízení nástrojů agenta prostřednictvím brány AI API: registry nástrojů, klíče s rozsahem, schvalovací brány, rozpočty pro jednotlivé nástroje, seznamy povolených MCP a spojené záznamy auditu modelu/nástroje.
Riziko agenta již není omezeno na výzvu modelu. Produkční agent může prohledávat interní soubory, dotazovat se na záznamy zákazníků, volat na MCP server, spouštět kód, otevírat prohlížeč, odesílat e-maily, aktualizovat CRM nebo spouštět fakturační pracovní postup. Otázka řízení zní: kterému uživateli, klíči, modelu, agentovi a nástroji bylo povoleno provést jakou akci, s jakým rozpočtem, auditní stopou a cestou vrácení?
Pokud každý tým zpracovává přístup k nástrojům ve svém vlastním kódu SDK, zásady se rozptýlí mezi proměnné prostředí, řídicí panely poskytovatelů, aplikační middleware a nezdokumentované servery MCP. Bezpečnějším vzorem je zacházet se spouštěním nástroje agenta jako s problémem řídicí roviny a vynucovat jej prostřednictvím brány AI API nebo standardního modulu pro spouštění nástrojů, který musí používat každý agent.
Tento článek odděluje fakta, doporučení a předpovědi. Fakta jsou čerpána z aktuálních veřejných pokynů: Top 10 aplikací OWASP LLM zahrnuje rizika, jako je prozrazení citlivých informací, zranitelnost dodavatelského řetězce a nadměrné zastupování; Generativní profil AI společnosti NIST pro rámec řízení rizik AI klade důraz na mapování, měření a řízení generativních rizik AI; Pokyny pro agenty OpenAI doporučují vyhodnotit riziko nástroje podle přístupu pro čtení/zápis, vratnosti, oprávnění a finančního dopadu; a Pokyny pro autorizaci MCP používají koncepty autorizace pro citlivé zdroje a operace. Níže uvedená doporučení představují vzory implementace, nikoli univerzální požadavky.
Problém čtenáře: přístup k modelu a přístup k nástrojům jsou zmatené
V mnoha raných aplikacích LLM odpovídal klíč API na jednu základní otázku: může tato služba volat model? Agenti to dělají příliš hrubé. Klíč, který může odesílat dokončení chatu, by neměl být schopen automaticky exportovat zákaznická data, spouštět příkazy shellu, odesílat příspěvky na Slack, upravovat vstupenky, procházet libovolné webové stránky nebo odesílat změny plateb.
Vrstva správy musí odpovědět na konkrétnější otázky:
- Který tenant, pracovní prostor, uživatel, servisní účet nebo zákazník prodejce zahájil běh?
- Jaký model, šablona výzvy, verze agenta a schéma nástroje byly použity?
- Byl požadovaný nástroj pouze pro čtení, vratný, nevratný, externí, finanční nebo privilegovaný?
- Měl žadatel požadovaný rozsah?
- Bylo schválení vyžadováno, uděleno, zamítnuto, vypršelo nebo bylo vynecháno nouzovými zásadami?
- Kolik nástroj stál, kolikrát byl volán a jaký zůstal kumulativní rozpočet?
- Jaké důkazy existují pro ladění, kontrolu souladu a vrácení zpět?
Níže uvedená architektura předpokládá, že brána již přijímá modelová volání. Spouštění nástroje pak může být směrováno přes stejnou bránu, přes službu postranního vozíku nebo přes standardní knihovnu, která se bráně hlásí před a po každém volání nástroje.
Referenční architektura: vrstva správy nástrojů na úrovni brány
Praktický systém správy agentů má sedm komponent:
- Registr nástrojů: autoritativní seznam schválených nástrojů, serverů MCP, hostovaných funkcí, nástrojů pro místní spouštění a interních rozhraní API.
- Identita a klíčová vrstva: klíče brány, uživatelé, tenanti, servisní účty, týmy a zákazníci prodejců.
- Scope engine: kontroly zásad, které rozhodují, zda klíč nebo uživatel může vyvolat konkrétní funkci nástroje.
- Klasifikátor rizika: metadata, která popisují poloměr výbuchu, citlivost dat, vratnost, vnější dopad a náklady.
- Pracovní postup schvalování: schvalování vysoce rizikových akcí člověkem nebo systémem před provedením.
- Hlavní kniha limitů rozpočtu a sazeb: limity na nástroj a agenta, nejen limity na tokeny modelu.
- Úložiště auditu a sledování: spojené záznamy pro volání modelu, volání nástrojů, schválení, chyby a výsledky.
Důležitým návrhovým rozhodnutím je učinit z brány bod pro rozhodování o politice, i když skutečný nástroj běží jinde. Například nástroj prohlížeče se může spustit v sandboxovém pracovníkovi a zápis CRM se může spustit uvnitř interní služby. Brána stále vyhodnocuje, zda je hovor povolen, zaznamenává rozhodnutí, sleduje náklady a vrací podepsané rozhodnutí o autorizaci nebo zamítnutí.
Krok 1: Vytvořte centrální registr nástrojů
Registr nástrojů je inventář, který zabraňuje tomu, aby se „funkce neznámého agenta“ stala výchozí. Každý nástroj by měl mít vlastníka, úroveň rizika a provozní metadata. Minimální záznam registru může vypadat takto:
{
"tool_id": "crm.create_ticket",
"display_name": "Vytvořit lístek podpory CRM",
"owner_team": "podpora-automatizace",
"execution_type": "interní_api",
"url_serveru": "https://tools.internal.example/crm",
"allowed_tenants": ["podnik", "podpora"],"allowed_models": ["general-large", "general-fast"],
"risk_tier": "reverzibilní_zápis",
"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"
}U serverů MCP by měl registr obsahovat také adresu URL serveru, inzerované nástroje, verzi schématu, metodu autorizace, datum poslední kontroly a to, zda jsou nové nástroje ve výchozím nastavení zakázány. MCP zlepšuje interoperabilitu, ale kompatibilita protokolů není totéž jako autorizace výroby. Citlivé zdroje a operace stále vyžadují explicitní rozsahy, kontroly směrování a izolaci tenantů.
Doporučená pole registru
- Název nástroje, kanonické ID, vlastník a telefonický kontakt.
- Místo provedení: nástroj hostovaného poskytovatele, server MCP, interní rozhraní API, pracovník prohlížeče, programátor kódu, úloha ve frontě nebo místní nástroj SDK.
- Povolení nájemci, týmy, uživatelé, verze agentů a profily modelů.
- Klasifikace dat: veřejná, interní, metadata zákazníka, obsah zákazníka, tajemství, platební údaje, přihlašovací údaje, regulovaná data.
- Úroveň rizika a vratnost.
- Požadované rozsahy a zásady schvalování.
- Časové limity, limity sazeb, maximální počet hovorů na spuštění, kumulativní rozpočet na běh a maximální cena za hovor.
- Režim protokolování: zakázáno, redigováno, hašováno, vzorkováno nebo explicitně zachováno celé užitečné zatížení.
- Pokyny k vrácení a postup eskalace.
Krok 2: Oddělte rozsahy modelu od rozsahů nástrojů
Klíč produkční brány by měl vyjadřovat, co může volající udělat. Přístup k modelu a přístup k nástrojům by měly být nezávislé. Například:
model:chat
model: vložky
tool:docs.search_readonly
tool:crm.create_ticket
tool:email.send_requires_approval
tool:billing.refund_blocked
tool:code.execute_blockedTo zabrání tomu, aby se chatbot s nízkým rizikem nestal náhodným automatizačním agentem. Podporuje také šablony rolí:
- Asistent vývojáře: model chat, vyhledávání dokumentace, vysvětlení kódu, žádné nástroje pro produkční zápis.
- Podporný robot: vyhledání zákazníků, vytvoření lístku, návrh odpovědi, vyžadováno schválení pro externí odesílání.
- Agent analytika: dotazy datového skladu pouze pro čtení s limity řádků, ve výchozím nastavení žádné exporty zákazníků.
- Administrátor: úzké privilegované operace, silné schválení, klíče s krátkou životností, úplný audit.
- Agent tenant distributora: přístup k modelu v rozsahu tenanta, nástroje v rozsahu tenanta, rozpočtové stropy na zákazníka.
Doporučení zní: Neznámé nástroje jsou odepřeny, chybějící rozsahy odmítají provedení, nově inzerované nástroje MCP jsou neaktivní, dokud nejsou schváleny, a místní nástroje musí používat stejný obal zásad jako hostované nástroje.
Krok 3: Klasifikujte nástroje podle poloměru tryskání
Ne každé volání nástroje potřebuje lidský souhlas. Řízení by mělo být úměrné riziku. Užitečný klasifikační model je:
Tato klasifikace by měla být viditelná v kontrole kódu a v uživatelském rozhraní správce. Samotné popisy nástrojů nestačí, protože agenti mohou popisy považovat za instrukce. Modul zásad by se měl spoléhat na metadata a rozsahy registru, nikoli pouze na názvy nástrojů v přirozeném jazyce.
Krok 4: Přidejte schvalovací brány pro vysoce rizikové akce
Schválení by mělo být cílené. Pokud každé volání nástroje vyžaduje osobu, agent se stane nepoužitelným. Pokud žádné volání nástroje nevyžaduje schválení, systém může udělit nadměrné zastoupení.
Běžný postup schvalování:
- Agent požaduje volání nástroje se strukturovanými argumenty.
- Brána vyhodnocuje identitu, rozsah, úroveň rizika, rozpočet a zásady.
- Pokud je vyžadováno schválení, brána místo spuštění nástroje vrátí událost čekající na schválení.
- Aplikace zobrazí uživateli náhled nebo odešle oznámení o operaci schvalovacímu kanálu.
- Schvalovatel může schválit, zamítnout, upravit argumenty, pokud to zásady umožňují, nebo požádat o vysvětlení.
- Brána zaznamená rozhodnutí a provede pouze schválenou verzi.
Schvalovací datová část by měla ukazovat akci v lidských termínech, nikoli pouze nezpracovaný JSON:
{
"approval_id": "appr_123",
"agent_run_id": "run_456",
"requested_by_user": "user_789",
"tool_id": "email.send",
"risk_tier": "externí_komunikace",
"summary": "Odeslat odpověď na adresu [email protected] ohledně lístku #4812",
"redacted_arguments": {
"to": "[email protected]",
"subject": "Aktualizace na lístku č. 4812",
"body_hash": "sha256:..."
},
"expires_at": "2026-08-09T12:30:00Z"
}Schválení je nejužitečnější pro externí komunikaci, finanční akce, nevratné zápisy, privilegovanou správu a rozsáhlé exporty dat. Obvykle je to zbytečné pro vyhledávání v maloobjemové veřejné dokumentaci.
Krok 5: Sledujte rozpočty jednotlivých nástrojů a limity sazeb
Tokenové rozpočty nestačí. Levný model může spustit drahé vyhledávání, relace prohlížeče, spouštění kódu, volání API třetích stran nebo dlouhé smyčky nástrojů. Brána by měla sledovat alespoň čtyři čítače:
- Počet volání na nástroj: maximální počet volání za běh, uživatele, nájemce a časové okno.
- Náklady na nástroj: přímé poplatky třetích stran, náklady na prohlížeč/běh, náklady na vyhledávání nebo odhad interního zpětného zúčtování.
- Kumulativní provozní náklady agenta: tokeny modelu plus náklady na nástroje.
- Hloubka smyčky: maximální počet iterací model-nástroj-model.
Po dosažení limitu by se brána měla vyvarovat tichého selhání, je-li to možné. Mezi bezpečnější vzorce degradace patří vracení souhrnu o průběhu, žádost o schválení pokračování, snížení hloubky načítání, zařazení úlohy na pozadí do fronty nebo přepnutí do režimu pouze pro čtení. Tvrdé odmítnutí je stále vhodné pro zablokované nástroje, chybějící rozsahy, neznámé možnosti MCP a nebezpečné akce.
Krok 6: Spojte telemetrii modelu a nástroje do jednoho auditního záznamu
Ladění agenta se nezdaří, pokud jsou protokoly modelu uloženy na jednom místě a protokoly nástrojů jsou uloženy někde jinde. Záznam auditu by měl propojit celý řetězec:
- Nájemce, pracovní prostor, uživatel, servisní účet a klíč brány.
- ID agenta, verze agenta, verze šablony výzvy a ID modelu.
- Název nástroje, verze registru, adresa URL serveru nebo prostředí spuštění a hodnota hash schématu.
- Vstup nástroje hash nebo redigovaný vstup, ve výchozím nastavení nikdy nezpracované citlivé datové části.
- Stav schválení, identita schvalovatele, časové razítko schválení a hodnota hash schváleného argumentu.
- Latence, opakování, chyby poskytovatele, chyby nástrojů, cena tokenu, cena nástroje a konečný výsledek.
- Reference o vrácení, pokud se stav akce změnil.
Dokumentace trasování sady Agents SDK od OpenAI zahrnuje trasování pro generace LLM, volání nástrojů, předávání, zábradlí a vlastní události, což podporuje širší princip pozorovatelnosti: trasování agentů by mělo zahrnovat aktivitu nástroje, nejen použití tokenů a latenci. Jediný kanál SDK však nemusí pokrývat každý hostovaný nástroj, cestu místního spuštění nebo interní rozhraní API. Audit na úrovni brány pomáhá normalizovat záznamy napříč poskytovateli a rámci.
Na soukromí záleží. Podrobné protokoly zlepšují ladění a kontrolu dodržování předpisů, ale neupravená okamžitá a uchovávání užitečného zatížení nástroje může vytvořit novou bezpečnostní odpovědnost. Opravte nebo hashujte vstupy, které obsahují tajemství, přihlašovací údaje, platební údaje, osobní údaje nebo vlastnické dokumenty. Ukládejte nezpracované datové části pouze v rámci explicitních zásad uchovávání, řízení přístupu a pravidel mazání.
Krok 7: Považujte servery MCP a nástroje třetích stran za závislé na dodavatelském řetězci
Servery MCP a nástroje třetích stran by měly projít stejným procesem kontroly jako knihovny, webhooky a závislosti na infrastruktuře. Mezi doporučené ovládací prvky patří:
- Udržujte seznam povolených schválených serverů MCP a původů nástrojů.
- Připněte verze, kde je to možné, a zaznamenejte hodnoty hash schématu.
- Vyžadovat vlastníka pro každý server a vysoce rizikový nástroj.
- Před aktivací nástrojů zkontrolujte názvy, popisy, schémata a nároky na oprávnění.
- Deaktivujte nově přidané nástroje, dokud nebudou zkontrolovány.
- Ověřte požadované rozsahy pro každou trasu nebo funkci.
- Oddělte přihlašovací údaje tenanta a vyhněte se sdíleným tokenům mezi zákazníky.
- Spouštějte nedůvěryhodné nebo vysoce rizikové nástroje v karanténách s omezeními sítě a souborového systému.
Skutečnost, že je nástroj vystaven prostřednictvím standardního protokolu, neznamená, že je bezpečný. Vrstva governance stále potřebuje nejmenší oprávnění, explicitní autorizaci, kontrolu verzí a auditovatelnost.
Kontrolní seznam implementace
Návrh zásad
- Definujte šablony rolí pro běžné uživatele agentů a servisní účty.
- Vytvořte samostatné rozsahy pro volání modelů a volání nástrojů.
- Klasifikujte nástroje podle citlivosti dat, vratnosti, externího dopadu, finančního dopadu a úrovně oprávnění.
- Nastavit chování odmítnutí výchozím nastavením pro neznámé nástroje a chybějící rozsahy.
- Definujte pravidla schvalování pouze pro vysoce rizikové akce.
Vynucení brány
- Vyžadujte, aby každý agent volal nástroje přes bránu nebo podepsaný obal zásad.
- Před provedením zkontrolujte tenanta, uživatele, klíč, agenta, model, nástroj, rozsah, rozpočet a stav schválení.
- Vynutit maximální hloubku vyvolání nástroje a kumulativní provozní náklady.
- Zaznamenejte verzi registru nástroje a hodnotu hash schématu pro každé volání.
- Selhání uzavřeno, když modul zásad nemůže dosáhnout rozhodnutí.
Audit a operace
- Připojte volání modelu a volání nástrojů pod jedno ID trasování nebo spuštění agenta.
- Ve výchozím nastavení upravujte nebo hashujte vstupy nástroje citlivé na hodnotu.
- Uchovávejte důkaz o schválení spolu s konečným záznamem o provedení.
- Poskytněte správcům analýzu nákladů na nástroj a omezení sazby.
- Vlastníky vrácení dokumentů pro nástroje, které mutují stav.
Očekávané kompromisy
Konzistence versus úsilí o integraci. Správa na úrovni brány zajišťuje konzistentní vymáhání napříč modely, sadami SDK a týmy. Náklady jsou přijetí: vývojáři musí směrovat spouštění nástroje přes schválenou cestu namísto volání nástrojů přímo z kódu aplikace.
Nejmenší oprávnění versus složitost zásad. Jemné rozsahy snižují rádius výbuchu, ale vyžadují šablony, konvence pojmenování a pravidelné čištění. Bez šablon mohou týmy udělit oprávnění k rychlejšímu pohybu.
Schválení versus autonomie. Lidský souhlas snižuje riziko nevratných akcí, ale zvyšuje latenci. Používejte schválení pro vysoce rizikové nástroje, ne pro každé vyhledávání nebo vyhledávání.
Kontrola versus vystavení dat. Bohaté protokoly pomáhají s reakcí na incidenty a laděním. Nezpracované protokolování užitečného zatížení může odhalit tajemství a osobní údaje. Redakce, hašování, konfigurovatelné uchování a kontrola přístupu nejsou volitelné podrobnosti.
Přísné limity versus dokončení úkolu. Limity nákladů na nástroj zabraňují útěku agentů. Mohou také přerušit legitimní dlouhotrvající práci. Poskytněte cesty pokračování, jako je schválení pro pokračování, fronty na pozadí nebo souhrnné dílčí výsledky.
Předpovědi: kam tento vzor směřuje
Předpověď: Správa agentů bude více zaměřena na identitu. Týmy se budou méně často ptát: „Jaký model byl použit? a častěji „která ověřená osoba nebo služba povolila tuto akci nástroje?“
Předpověď: Registry nástrojů budou stejně běžné jako modelové registry. Jak se servery MCP, interní rozhraní API a hostované nástroje množí, produkční týmy budou potřebovat inventář povolených schopností, vlastníků, schémat a úrovní rizik.
Předpověď: Správa nákladů se přesune z přehledů pouze tokenů na přehledy na úrovni akcí. Nejdražší částí běhu agenta může být spíše načítání, automatizace prohlížeče, spouštění kódu nebo API třetích stran než samotné volání modelu.
Akční závěr
Začněte s jedním pravidlem: klíč modelu není klíč nástroje. Poté postavte ven. Vytvořte registr schválených nástrojů, přiřaďte vlastníky a úrovně rizik, požadujte explicitní rozsahy, přidejte schválení pouze tam, kde má akce smysluplný rádius, prosazujte rozpočty na jednotlivé nástroje a spojte události modelu a nástroje do jednoho auditního záznamu.
Cílem není učinit agenty bezmocnými. Cílem je, aby jejich síla byla čitelná, v rozsahu, kde je to možné, vratná a zodpovědná. To je praktický základ pro správu týmového API, protože agenti přecházejí od odpovídání na otázky k provádění akcí.