Agentverktøystyring gjennom en AI API-gateway: omfang, godkjenninger, budsjetter og revisjonsspor
En praktisk referansearkitektur for å styre agentverktøy gjennom en AI API-gateway: verktøyregistre, scoped-nøkler, godkjenningsporter, budsjetter per verktøy, MCP-godkjenningslister og sammenkoblede modell-/verktøyrevisjonsspor.
Agentrisiko er ikke lenger begrenset til modellforespørselen. En produksjonsagent kan søke i interne filer, spørre etter kundeposter, ringe en MCP-server, kjøre kode, åpne en nettleser, sende e-post, oppdatere en CRM eller utløse en faktureringsarbeidsflyt. Styringsspørsmålet blir: hvilken bruker, nøkkel, modell, agent og verktøy fikk lov til å utføre hvilken handling, med hvilket budsjett, revisjonsspor og tilbakeføringsvei?
Hvis hvert team håndterer verktøytilgang i sin egen SDK-kode, blir policyen spredt på tvers av miljøvariabler, leverandørdashbord, programmellomvare og udokumenterte MCP-servere. Et sikrere mønster er å behandle kjøring av agentverktøy som et kontrollplanproblem og håndheve det gjennom en AI API-gateway eller en standard verktøyutførelsesomslag som hver agent må bruke.
Denne artikkelen skiller fakta, anbefalinger og spådommer. Fakta er hentet fra gjeldende offentlig veiledning: OWASPs LLM Application Topp 10 inkluderer risikoer som avsløring av sensitiv informasjon, sårbarheter i forsyningskjeden og overdreven byråkrati; NISTs generative AI-profil for AI Risk Management Framework legger vekt på kartlegging, måling og håndtering av generative AI-risikoer; OpenAIs agentveiledning anbefaler å evaluere verktøyrisiko ved lese-/skrivetilgang, reversibilitet, tillatelser og økonomisk innvirkning; og MCP-autorisasjonsveiledning bruker scoped autorisasjonskonsepter for sensitive ressurser og operasjoner. Anbefalingene nedenfor er implementeringsmønstre, ikke universelle krav.
Leserproblemet: modelltilgang og verktøytilgang forveksles
I mange tidlige LLM-applikasjoner svarte en API-nøkkel på ett grunnleggende spørsmål: kan denne tjenesten kalle en modell? Agenter gjør det for grovt. En nøkkel som kan sende chatfullføringer skal ikke automatisk kunne eksportere kundedata, kjøre shell-kommandoer, poste til Slack, endre billetter, bla gjennom vilkårlige nettsteder eller sende inn betalingsendringer.
Styringslaget må svare på mer spesifikke spørsmål:
- Hvilken leietaker, arbeidsområde, bruker, tjenestekonto eller forhandlerkunde startet kjøringen?
- Hvilken modell, ledetekstmal, agentversjon og verktøyskjema ble brukt?
- Var det forespurte verktøyet skrivebeskyttet, reversibelt, irreversibelt, eksternt, økonomisk eller privilegert?
- Hadde forespørselen det nødvendige omfanget?
- Var godkjenning påkrevd, gitt, avslått, utløpt eller forbigått av retningslinjer for nødsituasjoner?
- Hva kostet verktøyet, hvor mange ganger ble det kalt, og hvilket kumulativt budsjett gjensto?
- Hvilke bevis finnes for feilsøking, samsvarsgjennomgang og tilbakeføring?
Arkitekturen nedenfor forutsetter at gatewayen allerede mottar modellanrop. Verktøykjøring kan deretter rutes gjennom samme gateway, gjennom en sidevognstjeneste eller gjennom et standardbibliotek som rapporterer til gatewayen før og etter hvert verktøykall.
Referansearkitektur: et verktøystyringslag på gatewaynivå
Et praktisk agentstyringssystem har syv komponenter:
- Verktøyregister: den autoritative listen over godkjente verktøy, MCP-servere, vertsfunksjoner, lokale kjøringsverktøy og interne API-er.
- Identitet og nøkkellag: gatewaynøkler, brukere, leietakere, tjenestekontoer, team og forhandlerkunder.
- Omfangsmotor: policysjekker som bestemmer om en nøkkel eller bruker kan påkalle en bestemt verktøyfunksjon.
- Risikoklassifiserer: metadata som beskriver eksplosjonsradius, datafølsomhet, reversibilitet, ekstern påvirkning og kostnadseksponering.
- Arbeidsflyt for godkjenning: menneskelig eller systemgodkjenning for høyrisikohandlinger før utførelse.
- Budsjett og satsgrenser: grenser per verktøy og per agent, ikke bare per modell token-grenser.
- Revisjons- og sporingslager: sammenslåtte poster for modellanrop, verktøyanrop, godkjenninger, feil og utfall.
Den viktige designbeslutningen er å gjøre porten til det politiske beslutningspunktet selv om selve verktøyet kjører andre steder. For eksempel kan et nettleserverktøy kjøres i en sandkassearbeider, og en CRM-skriving kan kjøres i en intern tjeneste. Gatewayen evaluerer fortsatt om anropet er tillatt, registrerer avgjørelsen, sporer kostnadene og returnerer en signert autorisasjonsbeslutning eller avslag.
Trinn 1: Bygg et sentralt verktøyregister
Et verktøyregister er inventaret som forhindrer "ukjent agentkapasitet" fra å bli standard. Hvert verktøy bør ha en eier, et risikonivå og operasjonelle metadata. En minimal registerpost kan se slik ut:
{
"tool_id": "crm.create_ticket",
"display_name": "Opprett CRM-støttebillett",
"owner_team": "støtte-automatisering",
"execution_type": "intern_api",
"server_url": "https://tools.internal.example/crm",
"allowed_tenants": ["bedrift", "support"],"allowed_models": ["generell-stor", "generell-rask"],
"risk_tier": "reversible_write",
"data_classification": "customer_metadata",
"required_scopes": ["tool:crm.create_ticket"],
"approval_policy": "ikke_påkrevd_under_100_billetter_per_dag",
"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"
}For MCP-servere bør registret også inkludere server-URL, annonserte verktøy, skjemaversjon, autorisasjonsmetode, siste gjennomgangsdato og om nye verktøy er deaktivert som standard. MCP forbedrer interoperabilitet, men protokollkompatibilitet er ikke det samme som produksjonsautorisasjon. Sensitive ressurser og operasjoner trenger fortsatt eksplisitte omfang, rutesjekker og leietakerisolasjon.
Anbefalte registerfelt
- Verktøynavn, kanonisk ID, eier og vaktkontakt.
- Utføringssted: vertsleverandørverktøy, MCP-server, intern API, nettleserarbeider, kodeløper, køjobb eller lokalt SDK-verktøy.
- Tillatte leietakere, team, brukere, agentversjoner og modellprofiler.
- Dataklassifisering: offentlig, intern, kundemetadata, kundeinnhold, hemmeligheter, betalingsdata, legitimasjon, regulerte data.
- Risikonivå og reversibilitet.
- Nødvendige omfang og godkjenningspolicy.
- Tidsavbrudd, takstgrenser, maks. samtaler per kjøring, kumulativt kjøringsbudsjett og maks. kostnad per samtale.
- Loggingsmodus: full nyttelast forbudt, redigert, hashet, samplet eller eksplisitt beholdt.
- Instruksjoner for tilbakeføring og eskaleringsbane.
Trinn 2: Skille modellskoper fra verktøyskoper
En produksjonsgatewaynøkkel skal uttrykke hva den som ringer kan gjøre. Modelltilgang og verktøytilgang bør være uavhengige. For eksempel:
model:chat
modell:innstøpinger
tool:docs.search_readonly
tool:crm.create_ticket
tool:email.send_requires_approval
tool:billing.refund_blocked
tool:code.execute_blockedDette forhindrer at en chatbot med lav risiko blir en utilsiktet automatiseringsagent. Den støtter også rollemaler:
- Utviklerassistent: modellchat, dokumentasjonssøk, kodeforklaring, ingen produksjonsskriveverktøy.
- Støtterobot: kundeoppslag, billettoppretting, svarutkast, godkjenning kreves for eksterne sendinger.
- Analytikeragent: skrivebeskyttede datavarehusspørringer med radgrenser, ingen kundeeksport som standard.
- Administrasjonsagent: begrensede privilegerte operasjoner, sterk godkjenning, kortvarige nøkler, full revisjon.
- Forhandlerleieagent: leietakerbasert modelltilgang, leietakerbaserte verktøy, per-kunde budsjetttak.
Anbefalingen er å mislykkes lukket: ukjente verktøy nektes, manglende omfang nekter kjøring, nylig annonserte MCP-verktøy er inaktive inntil de er godkjent, og lokale verktøy må bruke samme policy-omslag som vertsbaserte verktøy.
Trinn 3: Klassifiser verktøy etter sprengningsradius
Ikke alle verktøykall trenger menneskelig godkjenning. Styring bør være proporsjonal med risiko. En nyttig klassifiseringsmodell er:
Denne klassifiseringen skal være synlig i kodegjennomgang og i administrasjonsgrensesnittet. Verktøybeskrivelser alene er ikke nok fordi agenter kan behandle beskrivelser som instruksjoner. Policymotoren bør stole på registermetadata og omfang, ikke bare på verktøynavn på naturlige språk.
Trinn 4: Legg til godkjenningsporter for høyrisikohandlinger
Godkjenning bør være målrettet. Hvis hvert verktøykall krever en person, blir agenten ubrukelig. Hvis ingen verktøykall krever godkjenning, kan systemet gi overdreven agentur.
En vanlig godkjenningsflyt:
- Agenten ber om et verktøykall med strukturerte argumenter.
- Gatewayen evaluerer identitet, omfang, risikonivå, budsjett og policy.
- Hvis godkjenning kreves, returnerer gatewayen en ventende godkjenningshendelse i stedet for å kjøre verktøyet.
- Appen viser en forhåndsvisning til brukeren eller sender et driftsvarsel til en godkjenningskanal.
- Godkjenneren kan godkjenne, avslå, redigere argumenter hvis policyen tillater det, eller be om avklaring.
- Gatewayen registrerer avgjørelsen og utfører kun den godkjente versjonen.
Godkjenningsnyttelasten skal vise handlingen i menneskelige termer, ikke bare rå JSON:
{
"approval_id": "appr_123",
"agent_run_id": "run_456",
"requested_by_user": "user_789",
"tool_id": "email.send",
"risk_tier": "ekstern_kommunikasjon",
"summary": "Send et svar til [email protected] om billett #4812",
"redacted_arguments": {
"to": "[email protected]",
"subject": "Oppdatering på billett #4812",
"body_hash": "sha256:..."
},
"expires_at": "2026-08-09T12:30:00Z"
}Godkjenning er mest nyttig for ekstern kommunikasjon, økonomiske handlinger, irreversible skrivinger, privilegert administrasjon og bred dataeksport. Det er vanligvis unødvendig for lavvolum av offentlig dokumentasjonssøk.
Trinn 5: Spor budsjetter per verktøy og takstgrenser
Tokenbudsjetter er ikke nok. En billig modell kan utløse dyre søk, nettleserøkter, kodekjøringer, tredjeparts API-kall eller lange verktøyløkker. Gatewayen bør spore minst fire tellere:
- Anrop per verktøy: maksimalt antall samtaler per kjøring, bruker, leietaker og tidsvindu.
- Kostnad per verktøy: direkte tredjepartskostnader, nettleser-/kjøretidskostnader, søkekostnader eller intern tilbakeføringsestimat.
- Kumulative agentdrevne kostnader: modelltokens pluss verktøykostnader.
- Sløyfedybde: maksimalt antall modell-verktøy-modell-iterasjoner.
Når en grense er nådd, bør gatewayen unngå en stille hard feil når det er mulig. Sikrere degraderingsmønstre inkluderer å returnere et sammendrag av fremdriften, be om godkjenning for å fortsette, senke gjenfinningsdybden, sette en bakgrunnsjobb i kø eller bytte til en skrivebeskyttet modus. Hard fornektelse er fortsatt passende for blokkerte verktøy, manglende omfang, ukjente MCP-funksjoner og farlige handlinger.
Trinn 6: Slå sammen modell- og verktøytelemetri til én revisjonspost
Agent-feilsøking mislykkes når modellloggene er på ett sted og verktøyloggene finnes et annet sted. Revisjonsposten skal koble sammen hele kjeden:
- Leietaker, arbeidsområde, bruker, tjenestekonto og gatewaynøkkel.
- Agent-ID, agentversjon, forespørselsmalversjon og modell-ID.
- Verktøynavn, registerversjon, server-URL eller utførelsesmiljø og skjemahash.
- Verktøyinndatahash eller redigert input, aldri råsensitive nyttelaster som standard.
- Godkjenningsstatus, godkjenneridentitet, godkjenningstidsstempel og godkjent argumenthash.
- Latens, gjenforsøk, leverandørfeil, verktøyfeil, tokenkostnad, verktøykostnad og sluttresultat.
- Tilbakeføringsreferanse, hvis handlingen endret tilstand.
OpenAIs Agents SDK-sporingsdokumentasjon inkluderer spor for LLM-generasjoner, verktøykall, overleveringer, rekkverk og tilpassede hendelser, som støtter et bredere observerbarhetsprinsipp: agentsporing bør inkludere verktøyaktivitet, ikke bare tokenbruk og latens. Imidlertid kan det hende at en enkelt SDK-pipeline ikke dekker alle vertsbaserte verktøy, lokal utførelsesbane eller intern API. Revisjon på gatewaynivå hjelper til med å normalisere poster på tvers av leverandører og rammeverk.
Personvern er viktig. Detaljerte logger forbedrer feilsøking og samsvarsgjennomgang, men rå melding og oppbevaring av nyttelast av verktøy kan skape et nytt sikkerhetsansvar. Rediger eller hash-inndata som inneholder hemmeligheter, legitimasjon, betalingsdata, personlige data eller proprietære dokumenter. Lagre rå nyttelast kun under eksplisitt oppbevaringspolicy, tilgangskontroller og slettingsregler.
Trinn 7: Behandle MCP-servere og tredjepartsverktøy som forsyningskjedeavhengigheter
MCP-servere og tredjepartsverktøy bør gå gjennom den samme gjennomgangsprosessen som biblioteker, webhooks og infrastrukturavhengigheter. Anbefalte kontroller inkluderer:
- Oppretthold en godkjenningsliste over godkjente MCP-servere og verktøyopprinnelse.
- Fest versjoner der det er mulig og registrer skjemahasher.
- Krev en eier for hver server og høyrisikoverktøy.
- Se gjennom verktøynavn, beskrivelser, skjemaer og tillatelseskrav før du aktiverer dem.
- Deaktiver nylig lagt til verktøy til de er gjennomgått.
- Bekreft nødvendige omfang per rute eller kapasitet.
- Skill leietakerlegitimasjon og unngå delte tokens på tvers av kunder.
- Kjør uklarerte eller høyrisikoverktøy i sandkasser med nettverks- og filsystembegrensninger.
Det faktum at et verktøy er eksponert gjennom en standardprotokoll gjør det ikke trygt. Styringslaget trenger fortsatt minst privilegier, eksplisitt autorisasjon, versjonskontroll og reviderbarhet.
Implementeringssjekkliste
Retningslinjer
- Definer rollemaler for vanlige agentbrukere og tjenestekontoer.
- Opprett separate omfang for modellanrop og verktøykall.
- Klassifiser verktøy etter datasensitivitet, reversibilitet, ekstern påvirkning, økonomisk påvirkning og rettighetsnivå.
- Angi deny-by-default-atferd for ukjente verktøy og manglende omfang.
- Definer godkjenningsregler bare for høyrisikohandlinger.
Gatewayhåndhevelse
- Krev at hver agent ringer verktøy gjennom gatewayen eller en signert policyomslag.
- Sjekk leietaker, bruker, nøkkel, agent, modell, verktøy, omfang, budsjett og godkjenningsstatus før utførelse.
- Håndhev maksimal verktøyanropsdybde og kumulative driftskostnader.
- Ta opp verktøyets registerversjon og skjemahash for hver samtale.
- Feil lukket når policymotoren ikke kan ta en avgjørelse.
Revisjon og drift
- Bli med modellanrop og verktøyanrop under én sporings- eller agentkjørings-ID.
- Rediger eller hash-sensitive verktøyinndata som standard.
- Behold godkjenningsbevis sammen med den endelige utførelsesprotokollen.
- Utsett analyser per verktøy for kostnader og hastighetsgrenser for administratorer.
- Eiere av tilbakeføring av dokumenter for verktøy som muterer tilstand.
Forventede avveininger
Konsistens versus integreringsarbeid. Gateway-nivå gir konsekvent håndhevelse på tvers av modeller, SDK-er og team. Kostnaden er bruk: utviklere må rute verktøykjøring gjennom den godkjente banen i stedet for å ringe verktøy direkte fra applikasjonskoden.
Minst privilegium kontra policykompleksitet. Finkornede omfang reduserer eksplosjonsradius, men de krever maler, navnekonvensjoner og regelmessig opprydding. Uten maler kan team overgi tillatelser til å bevege seg raskere.
Godkjenning versus autonomi. Menneskelig godkjenning reduserer risikoen for irreversible handlinger, men det øker ventetiden. Bruk godkjenninger for høyrisikoverktøy, ikke alle oppslag eller søk.
Auditabilitet versus dataeksponering. Rike logger hjelper med hendelsesrespons og feilsøking. Rå nyttelastlogging kan avsløre hemmeligheter og personlige data. Redaksjon, hashing, konfigurerbar oppbevaring og tilgangsgjennomgang er ikke valgfrie detaljer.
Harde grenser kontra fullføring av oppgave. Kostnadsgrenser per verktøy forhindrer løpende agenter. De kan også avbryte lovlig langvarig arbeid. Gi fortsettelsesbaner som godkjenning for å fortsette, bakgrunnskøer eller oppsummerte delresultater.
Spådommer: hvor dette mønsteret er på vei
Prediksjon: Agentstyring vil bli mer identitetssentrert. Lag vil sjeldnere spørre "hvilken modell brukte denne?" og oftere "hvilken autentisert person eller tjeneste tillot denne verktøyhandlingen?"
Prediksjon: verktøyregistre vil bli like normale som modellregistre. Etter hvert som MCP-servere, interne APIer og vertsbaserte verktøy multipliseres, vil produksjonsteam trenge en oversikt over tillatte evner, eiere, skjemaer og risikonivåer.
Prediksjon: kostnadsstyring vil gå fra token-only-rapportering til handlingsnivårapportering. Den dyreste delen av en agentkjøring kan være henting, nettleserautomatisering, kodekjøring eller tredjeparts API-er i stedet for selve modellkallet.
Aktiv konklusjon
Start med én regel: en modellnøkkel er ikke en verktøynøkkel. Bygg deretter utover. Opprett et register over godkjente verktøy, tilordne eiere og risikonivåer, krev eksplisitte omfang, legg til godkjenninger bare der handlingen har en meningsfull eksplosjonsradius, håndhev budsjetter per verktøy, og slå sammen modell- og verktøyhendelser i ett revisjonsspor.
Målet er ikke å gjøre agenter maktesløse. Målet er å gjøre deres makt lesbar, omfangsrik, reversibel der det er mulig og ansvarlig. Det er det praktiske grunnlaget for team-API-styring ettersom agenter går fra å svare på spørsmål til å utføre handlinger.