Beheer van agenttools via een AI API-gateway: bereik, goedkeuringen, budgetten en audittrails
Een praktische referentiearchitectuur voor beheertools via een AI API-gateway: toolregisters, scoped-sleutels, goedkeuringspoorten, budgetten per tool, MCP-toelatingslijsten en samengevoegde audittrails voor modellen/tools.
Het agentrisico is niet langer beperkt tot de modelprompt. Een productieagent kan interne bestanden doorzoeken, klantgegevens opvragen, een MCP-server bellen, code uitvoeren, een browser openen, e-mail verzenden, een CRM bijwerken of een factureringsworkflow activeren. De governancevraag wordt: welke gebruiker, sleutel, model, agent en tool mocht welke actie ondernemen, met welk budget, audittraject en terugdraaipad?
Als elk team de toegang tot tools afhandelt binnen zijn eigen SDK-code, raakt het beleid verspreid over omgevingsvariabelen, providerdashboards, applicatie-middleware en niet-gedocumenteerde MCP-servers. Een veiliger patroon is om de uitvoering van agenttools te behandelen als een probleem op het besturingsvlak en dit af te dwingen via een AI API-gateway of een standaard wrapper voor tooluitvoering die elke agent moet gebruiken.
In dit artikel worden feiten, aanbevelingen en voorspellingen gescheiden. De feiten zijn ontleend aan de huidige publieke richtlijnen: de LLM Application Top 10 van OWASP omvat risico's zoals openbaarmaking van gevoelige informatie, kwetsbaarheden in de toeleveringsketen en buitensporige keuzevrijheid; NIST’s Genative AI Profile for the AI Risk Management Framework legt de nadruk op het in kaart brengen, meten en beheren van generatieve AI-risico’s; De agentenrichtlijnen van OpenAI bevelen aan om het toolrisico te evalueren op basis van lees-/schrijftoegang, omkeerbaarheid, machtigingen en financiële impact; en MCP-autorisatierichtlijnen maken gebruik van autorisatieconcepten met een bereik voor gevoelige bronnen en bewerkingen. De onderstaande aanbevelingen zijn implementatiepatronen en geen universele vereisten.
Het lezersprobleem: toegang tot modellen en tools worden door elkaar gehaald
In veel vroege LLM-toepassingen beantwoordde een API-sleutel één fundamentele vraag: kan deze service een model aanroepen? Agenten maken dat te grof. Een sleutel die chataanvullingen kan verzenden, mag niet automatisch klantgegevens exporteren, shell-opdrachten uitvoeren, op Slack posten, tickets wijzigen, door willekeurige websites bladeren of betalingswijzigingen doorgeven.
De bestuurslaag moet meer specifieke vragen beantwoorden:
- Welke tenant, werkruimte, gebruiker, serviceaccount of resellerklant heeft de run gestart?
- Welk model, promptsjabloon, agentversie en toolschema zijn gebruikt?
- Was de gevraagde tool alleen-lezen, omkeerbaar, onomkeerbaar, extern gericht, financieel of bevoorrecht?
- Heeft de aanvrager het vereiste bereik?
- Was goedkeuring vereist, verleend, geweigerd, verlopen of omzeild door het noodbeleid?
- Wat kostte de tool, hoe vaak werd deze aangeroepen en hoeveel cumulatief budget bleef er over?
- Welk bewijs bestaat er voor foutopsporing, nalevingsbeoordeling en terugdraaien?
De onderstaande architectuur gaat ervan uit dat de gateway al modelaanroepen ontvangt. De uitvoering van tools kan vervolgens via dezelfde gateway worden gerouteerd, via een zijspanservice of via een standaardbibliotheek die voor en na elke tooloproep aan de gateway rapporteert.
Referentiearchitectuur: een toolbeheerlaag op gatewayniveau
Een praktisch agent-governancesysteem bestaat uit zeven componenten:
- Toolregister: de gezaghebbende lijst met goedgekeurde tools, MCP-servers, gehoste functies, lokale uitvoeringstools en interne API's.
- Identiteit en sleutellaag: gatewaysleutels, gebruikers, tenants, serviceaccounts, teams en resellerklanten.
- Scope-engine: beleidscontroles die beslissen of een sleutel of gebruiker een specifieke toolmogelijkheid kan aanroepen.
- Risicoclassificator: metadata die de ontploffingsradius, gegevensgevoeligheid, omkeerbaarheid, externe impact en kostenblootstelling beschrijft.
- Goedkeuringsworkflow: menselijke of systeemgoedkeuring voor risicovolle acties vóór uitvoering.
- Budget- en tarieflimietgrootboek: limieten per tool en per agent, niet alleen tokenlimieten per model.
- Audit- en traceeropslag: samengevoegde records voor modelaanroepen, toolaanroepen, goedkeuringen, fouten en resultaten.
De belangrijke ontwerpbeslissing is om van de gateway het beleidsbeslissingspunt te maken, zelfs als de daadwerkelijke tool ergens anders draait. Een browsertool kan bijvoorbeeld worden uitgevoerd in een sandbox-werknemer, en een CRM-schrijfbewerking kan worden uitgevoerd binnen een interne service. De gateway evalueert nog steeds of de oproep is toegestaan, registreert de beslissing, houdt de kosten bij en stuurt een ondertekende autorisatiebeslissing of weigering terug.
Stap 1: Bouw een centraal toolregister
Een toolregister is de inventaris die voorkomt dat “onbekende agentmogelijkheden” de standaard worden. Elke tool moet een eigenaar, een risicolaag en operationele metagegevens hebben. Een minimaal registerrecord kan er als volgt uitzien:
{
"tool_id": "crm.create_ticket",
"display_name": "CRM-ondersteuningsticket maken",
"owner_team": "ondersteuningsautomatisering",
"execution_type": "interne_api",
"server_url": "https://tools.internal.example/crm",
"allowed_tenants": ["onderneming", "ondersteuning"],"allowed_models": ["algemeen-groot", "algemeen-snel"],
"risk_tier": "omkeerbaar_schrijven",
"data_classification": "klant_metadata",
"required_scopes": ["tool:crm.create_ticket"],
"approval_policy": "not_required_under_100_tickets_per_day",
"default_timeout_ms": 8000,
"max_kosten_per_gesprek_usd": 0,05,
"max_calls_per_run": 3,
"rollback_owner": "support-ops-oncall",
"retention_policy": "redacted_30_days"
Voor MCP-servers moet het register ook de server-URL, geadverteerde tools, schemaversie, autorisatiemethode, laatste beoordelingsdatum en of nieuwe tools standaard zijn uitgeschakeld, bevatten. MCP verbetert de interoperabiliteit, maar protocolcompatibiliteit is niet hetzelfde als productieautorisatie. Gevoelige bronnen en bewerkingen hebben nog steeds expliciete bereiken, routecontroles en huurderisolatie nodig.
Aanbevolen registervelden
- Toolnaam, canonieke ID, eigenaar en contactpersoon op afroep.
- Uitvoeringslocatie: gehoste providertool, MCP-server, interne API, browserwerker, coderunner, wachtrijtaak of lokale SDK-tool.
- Toegestane tenants, teams, gebruikers, agentversies en modelprofielen.
- Gegevensclassificatie: openbaar, intern, metagegevens van klanten, klantinhoud, geheimen, betalingsgegevens, inloggegevens, gereguleerde gegevens.
- Risiconiveau en omkeerbaarheid.
- Vereiste bereiken en goedkeuringsbeleid.
- Time-outs, tarieflimieten, max. aantal oproepen per run, cumulatief runbudget en max. kosten per oproep.
- Logboekmodus: volledige payload verboden, geredigeerd, gehasht, bemonsterd of expliciet bewaard.
- Rollback-instructies en escalatiepad.
Stap 2: Scheid modelscopes van toolscopes
Een productiegatewaysleutel moet aangeven wat de beller kan doen. Toegang tot modellen en tools moeten onafhankelijk zijn. Bijvoorbeeld:
model:chat
model: inbedding
hulpprogramma:docs.search_readonly
tool: crm.create_ticket
tool:email.send_requires_approval
tool:billing.refund_blocked
tool:code.execute_blockedDit zorgt ervoor dat een chatbot met een laag risico niet per ongeluk een automatiseringsagent wordt. Het ondersteunt ook rolsjablonen:
- Ontwikkelaarsassistent: modelchat, documentatie zoeken, code-uitleg, geen productieschrijftools.
- Ondersteuningsbot: klanten opzoeken, tickets maken, antwoorden opstellen, goedkeuring vereist voor externe verzendingen.
- Analistagent: alleen-lezen datawarehouse-query's met rijlimieten, standaard geen klantexports.
- Beheerder: beperkte bevoorrechte bewerkingen, sterke goedkeuring, kortstondige sleutels, volledige audit.
- Tenantagent voor wederverkopers: modeltoegang voor huurders, tools voor huurders, budgetplafonds per klant.
De aanbeveling is om 'fail close' te doen: onbekende tools worden geweigerd, ontbrekende scopes weigeren uitvoering, nieuw geadverteerde MCP-tools zijn inactief totdat ze worden goedgekeurd, en lokale tools moeten dezelfde beleidswrapper gebruiken als gehoste tools.
Stap 3: Classificeer gereedschappen op explosieradius
Niet elke tool call heeft menselijke goedkeuring nodig. Governance moet in verhouding staan tot het risico. Een bruikbaar classificatiemodel is:
Deze classificatie zou zichtbaar moeten zijn in de codebeoordeling en in de beheerdersinterface. Gereedschapsbeschrijvingen alleen zijn niet voldoende, omdat agenten beschrijvingen als instructies kunnen beschouwen. De beleidsengine moet vertrouwen op registermetagegevens en -bereiken, en niet alleen op toolnamen in natuurlijke taal.
Stap 4: Voeg goedkeuringspoorten toe voor acties met een hoog risico
Goedkeuring moet gericht zijn. Als voor elke gereedschapsoproep een persoon nodig is, wordt de agent onbruikbaar. Als geen enkele tool-oproep goedkeuring vereist, kan het systeem buitensporige bevoegdheden toekennen.
Een algemeen goedkeuringsproces:
- De agent vraagt om een tooloproep met gestructureerde argumenten.
- De gateway evalueert identiteit, reikwijdte, risiconiveau, budget en beleid.
- Als goedkeuring vereist is, retourneert de gateway een in behandeling zijnde goedkeuringsgebeurtenis in plaats van de tool uit te voeren.
- De applicatie toont een voorbeeld aan de gebruiker of stuurt een operationele melding naar een goedkeuringskanaal.
- De goedkeurder kan argumenten goedkeuren, weigeren, bewerken als het beleid dit toestaat, of om opheldering vragen.
- De gateway registreert de beslissing en voert alleen de goedgekeurde versie uit.
De goedkeuringspayload moet de actie in menselijke termen weergeven, en niet alleen in ruwe JSON:
{
"approval_id": "appr_123",
"agent_run_id": "run_456",
"requested_by_user": "user_789",
"tool_id": "e-mail.verzenden",
"risk_tier": "externe_communicatie",
"summary": "Stuur een antwoord naar [email protected] over ticket #4812",
"redacted_arguments": {
"naar": "[email protected]",
"subject": "Update over ticket #4812",
"body_hash": "sha256:..."
},
"expires_at": "2026-08-09T12:30:00Z"
Goedkeuring is vooral nuttig voor externe communicatie, financiële acties, onomkeerbare schrijfbewerkingen, geprivilegieerd beheer en brede gegevensexport. Dit is meestal niet nodig bij het zoeken naar openbare documentatie in kleine hoeveelheden.
Stap 5: Houd budgetten en tarieflimieten per tool bij
Tokenbudgetten zijn niet voldoende. Een goedkoop model kan dure zoekopdrachten, browsersessies, coderuns, API-aanroepen van derden of lange toolloops veroorzaken. De gateway moet minimaal vier tellers bijhouden:
- Aantal oproepen per tool: maximale oproepen per uitvoering, gebruiker, tenant en tijdvenster.
- Kosten per tool: directe kosten van derden, browser-/runtimekosten, zoekkosten of interne terugvorderingsschatting.
- Cumulatieve kosten voor het uitvoeren van agenten: modeltokens plus gereedschapskosten.
- Lusdiepte: maximaal aantal model-tool-model-iteraties.
Wanneer een limiet wordt bereikt, moet de gateway indien mogelijk een stille harde storing vermijden. Veiliger degradatiepatronen zijn onder meer het retourneren van een samenvatting van de voortgang, het vragen om goedkeuring om door te gaan, het verlagen van de ophaaldiepte, het in de wachtrij plaatsen van een achtergrondtaak of het overschakelen naar een alleen-lezenmodus. Harde weigering is nog steeds geschikt voor geblokkeerde tools, ontbrekende scopes, onbekende MCP-mogelijkheden en gevaarlijke acties.
Stap 6: Voeg model- en tooltelemetrie samen in één auditrecord
Het debuggen van agenten mislukt wanneer modellogboeken op één plek staan en toollogboeken ergens anders. Het auditrecord moet de volledige keten verbinden:
- Tenant, werkruimte, gebruiker, serviceaccount en gatewaysleutel.
- Agent-ID, agentversie, promptsjabloonversie en model-ID.
- Toolnaam, registerversie, server-URL of uitvoeringsomgeving en schema-hash.
- Tool-invoerhash of geredigeerde invoer, standaard nooit onbewerkte gevoelige payloads.
- Goedkeuringsstatus, identiteit van de goedkeurder, tijdstempel van de goedkeuring en hash van het goedgekeurde argument.
- Latentie, nieuwe pogingen, providerfouten, toolfouten, tokenkosten, toolkosten en eindresultaat.
- Terugdraaireferentie, als de actie van status is veranderd.
De traceringsdocumentatie van de Agents SDK van OpenAI omvat traceringen voor LLM-generaties, toolaanroepen, overdrachten, guardrails en aangepaste gebeurtenissen, wat een breder observatieprincipe ondersteunt: agenttraceringen moeten toolactiviteit omvatten, en niet alleen het tokengebruik en de latentie. Het is echter mogelijk dat één enkele SDK-pijplijn niet alle gehoste tools, lokale uitvoeringspaden of interne API's dekt. Audit op gatewayniveau helpt bij het normaliseren van records tussen providers en frameworks.
Privacy is belangrijk. Gedetailleerde logboeken verbeteren het opsporen van fouten en het beoordelen van naleving, maar het vasthouden van onbewerkte prompts en de payload van tools kan een nieuw veiligheidsaansprakelijkheid creëren. Bewerk of hash invoer die geheimen, inloggegevens, betalingsgegevens, persoonlijke gegevens of bedrijfseigen documenten bevat. Bewaar onbewerkte payloads alleen onder expliciet bewaarbeleid, toegangscontroles en verwijderingsregels.
Stap 7: Behandel MCP-servers en tools van derden als afhankelijkheden van de toeleveringsketen
MCP-servers en tools van derden moeten hetzelfde beoordelingsproces doorlopen als bibliotheken, webhooks en infrastructuurafhankelijkheden. Aanbevolen beheersmaatregelen zijn onder meer:
- Houd een toelatingslijst bij van goedgekeurde MCP-servers en tooloorsprongen.
- Versies waar mogelijk vastzetten en schema-hashes vastleggen.
- Vereist een eigenaar voor elke server en tool met een hoog risico.
- Bekijk de namen, beschrijvingen, schema's en toestemmingsclaims van tools voordat u ze inschakelt.
- Schakel nieuw toegevoegde tools uit totdat ze zijn beoordeeld.
- Verifieer de vereiste bereiken per route of mogelijkheid.
- Gescheiden huurderreferenties en vermijd gedeelde tokens tussen klanten.
- Voer niet-vertrouwde of risicovolle tools uit in sandboxes met netwerk- en bestandssysteembeperkingen.
Het feit dat een tool via een standaardprotocol wordt ontmaskerd, betekent niet dat het veilig is. De bestuurslaag heeft nog steeds de minste bevoegdheden, expliciete autorisatie, versiebeheer en controleerbaarheid nodig.
Implementatiechecklist
Beleidsontwerp
- Definieer rolsjablonen voor algemene agentgebruikers en serviceaccounts.
- Maak afzonderlijke bereiken voor modelaanroepen en toolaanroepen.
- Classificeer tools op basis van gegevensgevoeligheid, omkeerbaarheid, externe impact, financiële impact en privilegeniveau.
- Stel standaard deny-gedrag in voor onbekende tools en ontbrekende bereiken.
- Definieer alleen goedkeuringsregels voor acties met een hoog risico.
Gatewayhandhaving
- Vereisen dat elke agent tools aanroept via de gateway of een ondertekende beleidswrapper.
- Controleer de tenant-, gebruiker-, sleutel-, agent-, model-, tool-, bereik-, budget- en goedkeuringsstatus vóór uitvoering.
- Dwing maximale diepte van toolcalls en cumulatieve uitvoeringskosten af.
- Registreerversie en schema-hash van tool registreren voor elke oproep.
- Fout gesloten wanneer de beleidsengine niet tot een besluit kan komen.
Audit en operaties
- Voeg modelaanroepen en toolaanroepen samen onder één tracering of agentrun-ID.
- Standaard gevoelige toolinvoer redigeren of hashen.
- Bewaar het goedkeuringsbewijs bij het definitieve uitvoeringsdossier.
- Maak analyses van kosten per tool en tarieflimieten zichtbaar voor beheerders.
- Eigenaren van het terugdraaien van documenten voor tools die de status muteren.
Te verwachten compromissen
Consistentie versus integratie-inspanning. Beheer op gatewayniveau zorgt voor consistente handhaving tussen modellen, SDK's en teams. De kosten zijn adoptie: ontwikkelaars moeten de uitvoering van tools via het goedgekeurde pad leiden in plaats van tools rechtstreeks vanuit de applicatiecode aan te roepen.
Minste bevoegdheden versus beleidscomplexiteit. Fijnmazige scopes verkleinen de explosieradius, maar vereisen sjablonen, naamgevingsconventies en regelmatig opruimen. Zonder sjablonen kunnen teams te veel rechten verlenen om sneller te kunnen werken.
Goedkeuring versus autonomie. Menselijke goedkeuring vermindert het risico op onomkeerbare acties, maar zorgt ook voor latentie. Gebruik goedkeuringen voor tools met een hoog risico, niet voor elke zoekopdracht.
Controleerbaarheid versus gegevensblootstelling. Uitgebreide logboeken helpen bij incidentrespons en foutopsporing. Het vastleggen van onbewerkte payloads kan geheimen en persoonlijke gegevens blootleggen. Redactie, hashing, configureerbare retentie en toegangsbeoordeling zijn geen optionele details.
Harde limieten versus taakvoltooiing. Kostenlimieten per tool voorkomen weggelopen agenten. Ze kunnen ook legitieme, langlopende werkzaamheden onderbreken. Geef vervolgpaden op, zoals goedkeuring om door te gaan, wachtrijen op de achtergrond of samengevatte gedeeltelijke resultaten.
Voorspellingen: waar dit patroon naartoe gaat
Voorspelling: agent-governance zal meer identiteitsgericht worden. Teams zullen minder vaak vragen: “Welk model is hiervoor gebruikt?” en vaker “welke geverifieerde persoon of dienst heeft deze toolactie toegestaan?”
Voorspelling: toolregisters zullen net zo normaal worden als modelregisters. Naarmate MCP-servers, interne API's en gehoste tools zich vermenigvuldigen, zullen productieteams een inventarisatie nodig hebben van toegestane mogelijkheden, eigenaren, schema's en risiconiveaus.
Voorspelling: kostenbeheer zal verschuiven van rapportage op alleen tokens naar rapportage op actieniveau. Het duurste onderdeel van het uitvoeren van een agent kan het ophalen, de browserautomatisering, de uitvoering van code of API's van derden zijn, in plaats van de modelaanroep zelf.
Bruikbare conclusie
Begin met één regel: een modelsleutel is geen gereedschapssleutel. Bouw dan naar buiten. Creëer een register van goedgekeurde tools, wijs eigenaren en risiconiveaus toe, eis expliciete scopes, voeg alleen goedkeuringen toe als de actie een betekenisvolle actieradius heeft, dwing budgetten per tool af en voeg model- en toolgebeurtenissen samen in één audittrail.
Het doel is niet om agenten machteloos te maken. Het doel is om hun macht waar mogelijk leesbaar, reikwijdte, omkeerbaar en verantwoordelijk te maken. Dat is de praktische basis voor team-API-beheer terwijl agenten overgaan van het beantwoorden van vragen naar het ondernemen van actie.