Agentværktøjsstyring gennem en AI API-gateway: omfang, godkendelser, budgetter og revisionsspor
En praktisk referencearkitektur til styring af agentværktøjer gennem en AI API-gateway: værktøjsregistre, scoped-nøgler, godkendelsesporte, budgetter pr.
Agentrisiko er ikke længere begrænset til modelprompten. En produktionsagent kan søge i interne filer, forespørge på kunderegistre, ringe til en MCP-server, udføre kode, åbne en browser, sende e-mail, opdatere en CRM eller udløse en faktureringsworkflow. Governance-spørgsmålet bliver: Hvilken bruger, nøgle, model, agent og værktøj fik lov til at foretage hvilken handling, med hvilket budget, revisionsspor og rollback-sti?
Hvis hvert team håndterer værktøjsadgang inde i sin egen SDK-kode, bliver politikken spredt på tværs af miljøvariabler, udbyderdashboards, applikations-middleware og udokumenterede MCP-servere. Et mere sikkert mønster er at behandle agentværktøjsudførelse som et kontrolplanproblem og håndhæve det gennem en AI API-gateway eller en standardværktøjsudførelsesindpakning, som hver agent skal bruge.
Denne artikel adskiller fakta, anbefalinger og forudsigelser. Fakta er hentet fra aktuelle offentlige vejledninger: OWASP's LLM Application Top 10 inkluderer risici såsom offentliggørelse af følsom information, forsyningskædesårbarheder og overdreven agentur; NISTs Generative AI Profile for AI Risk Management Framework lægger vægt på kortlægning, måling og styring af generative AI-risici; OpenAIs agentvejledning anbefaler at evaluere værktøjsrisiko ved læse-/skriveadgang, reversibilitet, tilladelser og økonomisk påvirkning; og MCP-autorisationsvejledning bruger scoped autorisationskoncepter til følsomme ressourcer og operationer. Nedenstående anbefalinger er implementeringsmønstre, ikke universelle krav.
Læserproblemet: Modeladgang og værktøjsadgang forveksles
I mange tidlige LLM-applikationer besvarede en API-nøgle et grundlæggende spørgsmål: kan denne tjeneste kalde en model? Agenter gør det for groft. En nøgle, der kan sende chatafslutninger, bør ikke automatisk være i stand til at eksportere kundedata, køre shell-kommandoer, sende til Slack, ændre billetter, gennemse vilkårlige websteder eller indsende betalingsændringer.
Governance-laget skal besvare mere specifikke spørgsmål:
- Hvilken lejer, arbejdsområde, bruger, servicekonto eller forhandlerkunde startede kørslen?
- Hvilken model, promptskabelon, agentversion og værktøjsskema blev brugt?
- Var det anmodede værktøj skrivebeskyttet, reversibelt, irreversibelt, eksternt vendt, finansielt eller privilegeret?
- Havde anmoderen det påkrævede omfang?
- Blev godkendelse påkrævet, givet, nægtet, udløbet eller omgået af nødpolitik?
- Hvad kostede værktøjet, hvor mange gange blev det kaldt, og hvilket kumulativt budget var der tilbage?
- Hvilket bevis findes for fejlretning, overholdelsesgennemgang og tilbagerulning?
Arkitekturen nedenfor antager, at gatewayen allerede modtager modelopkald. Værktøjsudførelse kan derefter dirigeres gennem den samme gateway, gennem en sidevognstjeneste eller gennem et standardbibliotek, der rapporterer til gatewayen før og efter hvert værktøjskald.
Referencearkitektur: et værktøjsstyringslag på gatewayniveau
Et praktisk agentstyringssystem har syv komponenter:
- Værktøjsregistrering: den autoritative liste over godkendte værktøjer, MCP-servere, hostede funktioner, lokale eksekveringsværktøjer og interne API'er.
- Identitet og nøglelag: gatewaynøgler, brugere, lejere, servicekonti, teams og forhandlerkunder.
- Scope engine: politiktjek, der afgør, om en nøgle eller en bruger kan påberåbe sig en specifik værktøjsfunktion.
- Risikoklassifikator: metadata, der beskriver sprængningsradius, datafølsomhed, reversibilitet, ekstern påvirkning og omkostningseksponering.
- Godkendelsesworkflow: menneskelig eller systemgodkendelse for højrisikohandlinger før udførelse.
- Budget- og hastighedsgrænser: grænser pr. værktøj og pr. agent, ikke kun token-grænser pr. model.
- Revision og sporing af lager: Sammenlagte registreringer for modelkald, værktøjsopkald, godkendelser, fejl og resultater.
Den vigtige designbeslutning er at gøre gatewayen til det politiske beslutningspunkt, selvom det faktiske værktøj kører andre steder. For eksempel kan et browserværktøj udføres i en sandboxed-arbejder, og en CRM-skrivning kan udføres i en intern tjeneste. Gatewayen evaluerer stadig, om opkaldet er tilladt, registrerer beslutningen, sporer omkostninger og returnerer en underskrevet godkendelsesbeslutning eller afvisning.
Trin 1: Byg et centralt værktøjsregister
Et værktøjsregister er den beholdning, der forhindrer "ukendt agentkapacitet" i at blive standard. Hvert værktøj skal have en ejer, et risikoniveau og operationelle metadata. En minimal registrering i registreringsdatabasen kan se sådan ud:
For MCP-servere skal registreringsdatabasen også indeholde server-URL, annoncerede værktøjer, skemaversion, godkendelsesmetode, dato for sidste gennemgang og om nye værktøjer er deaktiveret som standard. MCP forbedrer interoperabiliteten, men protokolkompatibilitet er ikke det samme som produktionsautorisation. Følsomme ressourcer og operationer har stadig brug for eksplicitte omfang, rutetjek og lejerisolering.
Anbefalede registreringsdatabasefelter
- Værktøjsnavn, kanonisk id, ejer og vagtkontakt.
- Udførelsesplacering: hostet udbyderværktøj, MCP-server, intern API, browserarbejder, kodeløber, køjob eller lokalt SDK-værktøj.
- Tilladte lejere, teams, brugere, agentversioner og modelprofiler.
- Dataklassificering: offentlig, intern, kundemetadata, kundeindhold, hemmeligheder, betalingsdata, legitimationsoplysninger, regulerede data.
- Risikoniveau og reversibilitet.
- Påkrævet omfang og godkendelsespolitik.
- Timeouts, takstgrænser, maks. opkald pr. kørsel, kumulativt kørselsbudget og maks. pris pr. opkald.
- Logningstilstand: fuld nyttelast forbudt, redigeret, hashed, samplet eller eksplicit bevaret.
- Tilbageføringsinstruktioner og eskaleringssti.
Trin 2: Adskil modelomfang fra værktøjsomfang
En produktionsgateway-nøgle skal udtrykke, hvad den, der ringer, kan gøre. Modeladgang og værktøjsadgang bør være uafhængig. For eksempel:
model:chat
model: indstøbninger
tool:docs.search_readonly
tool:crm.create_ticket
tool:email.send_requires_approval
tool:billing.refund_blocked
tool:code.execute_blockedDette forhindrer en chatbot med lav risiko i at blive en utilsigtet automatiseringsagent. Det understøtter også rolleskabeloner:
- Udviklerassistent: modelchat, dokumentationssøgning, kodeforklaring, ingen produktionsskriveværktøjer.
- Supportbot: kundeopslag, oprettelse af billet, udarbejdelse af svar, godkendelse påkrævet for eksterne afsendelser.
- Analytikeragent: skrivebeskyttede datavarehusforespørgsler med rækkebegrænsninger, ingen kundeeksport som standard.
- Administrator: snævre privilegerede operationer, stærk godkendelse, kortvarige nøgler, fuld revision.
- Forhandler lejeragent: lejerbestemt modeladgang, lejerbaserede værktøjer, budgetlofter pr. kunde.
Anbefalingen er at mislykkes lukket: ukendte værktøjer afvises, manglende omfang nægter udførelse, nyligt annoncerede MCP-værktøjer er inaktive, indtil de er godkendt, og lokale værktøjer skal bruge den samme politikindpakning som hostede værktøjer.
Trin 3: Klassificer værktøjer efter sprængningsradius
Ikke alle værktøjskald kræver menneskelig godkendelse. Styring bør være proportional med risiko. En nyttig klassifikationsmodel er:
Denne klassifikation bør være synlig i kodegennemgang og i administratorbrugergrænsefladen. Værktøjsbeskrivelser alene er ikke nok, fordi agenter kan behandle beskrivelser som instruktioner. Politikmotoren bør stole på registreringsdatabasens metadata og scopes, ikke kun på værktøjsnavne på det naturlige sprog.
Trin 4: Tilføj godkendelsesporte for højrisikohandlinger
Godkendelse bør målrettes. Hvis hvert værktøjskald kræver en person, bliver agenten ubrugelig. Hvis intet værktøjskald kræver godkendelse, kan systemet give overdreven handlefrihed.
Et almindeligt godkendelsesflow:
- Agenten anmoder om et værktøjskald med strukturerede argumenter.
- Gatewayen evaluerer identitet, omfang, risikoniveau, budget og politik.
- Hvis godkendelse er påkrævet, returnerer gatewayen en afventende godkendelseshændelse i stedet for at udføre værktøjet.
- Applikationen viser en forhåndsvisning til brugeren eller sender en driftsmeddelelse til en godkendelseskanal.
- Godkenderen kan godkende, afvise, redigere argumenter, hvis politikken tillader det, eller anmode om afklaring.
- Gatewayen registrerer beslutningen og udfører kun den godkendte version.
Godkendelsens nyttelast skal vise handlingen i menneskelige termer, ikke kun rå JSON:
Godkendelse er mest nyttig til ekstern kommunikation, økonomiske handlinger, irreversible skrivninger, privilegeret administration og bred dataeksport. Det er normalt unødvendigt at søge i offentlig dokumentation i lav volumen.
Trin 5: Spor budgetter pr. værktøj og satsgrænser
Tokenbudgetter er ikke nok. En billig model kan udløse dyre søgninger, browsersessioner, kodekørsler, tredjeparts API-kald eller lange værktøjsløkker. Gatewayen skal spore mindst fire tællere:
- Antal opkald pr. værktøj: maksimalt antal opkald pr. kørsel, bruger, lejer og tidsvindue.
- Pris pr. værktøj: direkte tredjepartsgebyrer, browser-/runtime-omkostninger, søgeomkostninger eller intern tilbageførselsestimat.
- Kumulerede omkostninger ved agentkørsel: modeltokens plus værktøjsomkostninger.
- Sløjfedybde: maksimalt antal model-værktøj-model iterationer.
Når en grænse er nået, bør gatewayen undgå en tavs hård fejl, når det er muligt. Sikrere nedbrydningsmønstre omfatter returnering af en oversigt over fremskridt, bede om godkendelse for at fortsætte, sænke genfindingsdybden, sætte et baggrundsjob i kø eller skifte til en skrivebeskyttet tilstand. Hård benægtelse er stadig passende for blokerede værktøjer, manglende scopes, ukendte MCP-kapaciteter og farlige handlinger.
Trin 6: Saml model- og værktøjstelemetri i én revisionspost
Agent-fejlfinding mislykkes, når modellogfiler findes ét sted, og værktøjslogfiler lever et andet sted. Revisionsposten skal forbinde hele kæden:
- Lejer, arbejdsområde, bruger, tjenestekonto og gatewaynøgle.
- Agent-id, agentversion, promptskabelonversion og model-id.
- Værktøjsnavn, registreringsdatabaseversion, server-URL eller eksekveringsmiljø og skemahash.
- Værktøjsinput-hash eller redigeret input, aldrig råfølsomme nyttelaster som standard.
- Godkendelsesstatus, godkenderidentitet, godkendelsestidsstempel og godkendt argumenthash.
- Latens, genforsøg, udbyderfejl, værktøjsfejl, tokenomkostninger, værktøjsomkostninger og endeligt resultat.
- Tilbageføringsreference, hvis handlingen ændrede tilstand.
OpenAIs Agents SDK-sporingsdokumentation inkluderer spor for LLM-generationer, værktøjsopkald, overdragelser, autoværn og tilpassede hændelser, som understøtter et bredere observerbarhedsprincip: agentsporing bør omfatte værktøjsaktivitet, ikke kun tokenbrug og latens. En enkelt SDK-pipeline dækker dog muligvis ikke alle hostede værktøj, lokal eksekveringssti eller intern API. Revision på gatewayniveau hjælper med at normalisere registreringer på tværs af udbydere og rammer.
Privatliv er vigtigt. Detaljerede logfiler forbedrer fejlfinding og overholdelsesgennemgang, men rå prompt og værktøjs-nyttelast-opbevaring kan skabe et nyt sikkerhedsansvar. Rediger eller hash-input, der indeholder hemmeligheder, legitimationsoplysninger, betalingsdata, personlige data eller proprietære dokumenter. Gem kun rå nyttelast under eksplicit opbevaringspolitik, adgangskontrol og sletningsregler.
Trin 7: Behandl MCP-servere og tredjepartsværktøjer som forsyningskædeafhængigheder
MCP-servere og tredjepartsværktøjer bør gennemgå den samme gennemgangsproces som biblioteker, webhooks og infrastrukturafhængigheder. Anbefalede kontroller omfatter:
- Oprethold en tilladelsesliste over godkendte MCP-servere og værktøjsoprindelse.
- Fastgør versioner, hvor det er muligt, og optag skemahash.
- Kræv en ejer for hver server og højrisikoværktøj.
- Gennemgå værktøjsnavne, beskrivelser, skemaer og tilladelseskrav, før du aktiverer dem.
- Deaktiver nyligt tilføjede værktøjer, indtil de er gennemgået.
- Bekræft påkrævede omfang pr. rute eller kapacitet.
- Adskil lejerlegitimationsoplysninger og undgå delte tokens på tværs af kunder.
- Kør ikke-pålidelige eller højrisikoværktøjer i sandkasser med netværks- og filsystembegrænsninger.
Det faktum, at et værktøj eksponeres gennem en standardprotokol, gør det ikke sikkert. Styringslaget har stadig brug for mindste privilegier, eksplicit autorisation, versionskontrol og revisionsmuligheder.
Implementeringstjekliste
Politikdesign
- Definer rolleskabeloner for almindelige agentbrugere og tjenestekonti.
- Opret separate omfang for modelkald og værktøjskald.
- Klassificer værktøjer efter datafølsomhed, reversibilitet, ekstern påvirkning, økonomisk påvirkning og privilegieniveau.
- Indstil deny-by-default-adfærd for ukendte værktøjer og manglende omfang.
- Definer kun godkendelsesregler for højrisikohandlinger.
Gatewayhåndhævelse
- Kræv, at hver agent ringer til værktøjer gennem gatewayen eller en underskrevet politikindpakning.
- Tjek lejer, bruger, nøgle, agent, model, værktøj, omfang, budget og godkendelsesstatus før udførelse.
- Håndhæv maksimal værktøjsopkaldsdybde og kumulative driftsomkostninger.
- Optag værktøjets registreringsversion og skemahash for hvert opkald.
- Fejl lukket, når politikmotoren ikke kan træffe en beslutning.
Revision og drift
- Forbind modelopkald og værktøjsopkald under ét sporings- eller agentkørsels-id.
- Rediger eller hash-følsomme værktøjsinput som standard.
- Opbevar godkendelsesbeviser sammen med den endelige udførelsesjournal.
- Udslæb pr. værktøjsomkostninger og hastighedsgrænseanalyser for administratorer.
- Dokumentrulningsejere for værktøjer, der muterer tilstand.
Forventede afvejninger
Konsistens versus integrationsindsats. Governance på gatewayniveau giver konsekvent håndhævelse på tværs af modeller, SDK'er og teams. Prisen er vedtagelse: Udviklere skal dirigere værktøjsudførelse gennem den godkendte sti i stedet for at kalde værktøjer direkte fra applikationskoden.
Mindste privilegier i forhold til politikkompleksitet. Finkornede scopes reducerer sprængningsradius, men de kræver skabeloner, navnekonventioner og regelmæssig oprydning. Uden skabeloner kan teams overgive tilladelser til at bevæge sig hurtigere.
Godkendelse versus autonomi. Menneskelig godkendelse reducerer risikoen for irreversible handlinger, men det tilføjer latens. Brug godkendelser til højrisikoværktøjer, ikke alle opslag eller søgninger.
Auditabilitet versus dataeksponering. Rich logs hjælper med hændelsesrespons og fejlretning. Logning af rå nyttelast kan afsløre hemmeligheder og personlige data. Redaktion, hashing, konfigurerbar opbevaring og adgangsgennemgang er ikke valgfri detaljer.
Hårde grænser versus færdiggørelse af opgave. Omkostningsgrænser pr. værktøj forhindrer løbske agenter. De kan også afbryde lovligt langvarigt arbejde. Angiv fortsættelsesstier såsom godkendelse for at fortsætte, baggrundskøer eller opsummerede delresultater.
Forudsigelser: hvor dette mønster er på vej hen
Forudsigelse: Agentstyring vil blive mere identitetscentreret. Hold vil sjældnere spørge "hvilken model brugte denne?" og oftere "hvilken godkendt person eller tjeneste tillod denne værktøjshandling?"
Forudsigelse: Værktøjsregistre bliver lige så normale som modelregistre. Efterhånden som MCP-servere, interne API'er og hostede værktøjer bliver flere, vil produktionsteams få brug for en opgørelse over tilladte egenskaber, ejere, skemaer og risikoniveauer.
Forudsigelse: omkostningsstyring vil gå fra token-only-rapportering til rapportering på handlingsniveau. Den dyreste del af en agentkørsel kan være hentning, browserautomatisering, kodekørsel eller tredjeparts API'er i stedet for selve modelkaldet.
Aktiv konklusion
Start med én regel: en modelnøgle er ikke en værktøjsnøgle. Byg derefter udad. Opret et register over godkendte værktøjer, tildel ejere og risikoniveauer, kræve eksplicitte omfang, tilføj kun godkendelser, hvor handlingen har en meningsfuld sprængningsradius, håndhæv budgetter pr.
Målet er ikke at gøre agenter magtesløse. Målet er at gøre deres magt læselig, omfangsrig, reversibel, hvor det er muligt, og ansvarlig. Det er det praktiske grundlag for team-API-styring, da agenter bevæger sig fra at besvare spørgsmål til at udføre handlinger.