Governance dello strumento agente tramite un gateway API AI: ambiti, approvazioni, budget e audit trail
Un'architettura di riferimento pratica per governare gli strumenti degli agenti tramite un gateway API AI: registri degli strumenti, chiavi con ambito, gate di approvazione, budget per strumento, liste consentite MCP e audit trail di modelli/strumenti uniti.
Il rischio dell'agente non è più limitato alla richiesta del modello. Un agente di produzione può cercare file interni, interrogare i record dei clienti, chiamare un server MCP, eseguire codice, aprire un browser, inviare e-mail, aggiornare un CRM o attivare un flusso di lavoro di fatturazione. La domanda sulla governance diventa: quale utente, chiave, modello, agente e strumento è stato autorizzato a intraprendere quale azione, con quale budget, traccia di controllo e percorso di rollback?
Se ogni team gestisce l'accesso agli strumenti all'interno del proprio codice SDK, le policy si disperdono tra variabili di ambiente, dashboard dei fornitori, middleware applicativo e server MCP non documentati. Un modello più sicuro consiste nel trattare l'esecuzione dello strumento dell'agente come un problema del piano di controllo e applicarlo tramite un gateway API AI o un wrapper di esecuzione dello strumento standard che ogni agente deve utilizzare.
Questo articolo separa fatti, consigli e previsioni. I fatti sono tratti dalle attuali linee guida pubbliche: la Top 10 delle applicazioni LLM di OWASP include rischi come la divulgazione di informazioni sensibili, le vulnerabilità della catena di fornitura e l’eccesso di azione; Il profilo di intelligenza artificiale generativa del NIST per il quadro di gestione del rischio di intelligenza artificiale enfatizza la mappatura, la misurazione e la gestione dei rischi di intelligenza artificiale generativa; La guida dell'agente di OpenAI consiglia di valutare il rischio dello strumento in base all'accesso in lettura/scrittura, alla reversibilità, alle autorizzazioni e all'impatto finanziario; e la guida all'autorizzazione MCP utilizza concetti di autorizzazione con ambito per risorse e operazioni sensibili. I consigli riportati di seguito rappresentano modelli di implementazione, non requisiti universali.
Il problema del lettore: l'accesso al modello e l'accesso allo strumento vengono confusi
In molte delle prime applicazioni LLM, una chiave API rispondeva a una domanda fondamentale: questo servizio può chiamare un modello? Gli agenti lo rendono troppo volgare. Una chiave in grado di inviare completamenti di chat non dovrebbe essere in grado automaticamente di esportare i dati dei clienti, eseguire comandi shell, pubblicare su Slack, modificare ticket, navigare in siti Web arbitrari o inviare modifiche ai pagamenti.
Il livello di governance deve rispondere a domande più specifiche:
- Quale tenant, area di lavoro, utente, account di servizio o cliente rivenditore ha avviato l'esecuzione?
- Quale modello, modello di prompt, versione dell'agente e schema dello strumento sono stati utilizzati?
- Lo strumento richiesto era di sola lettura, reversibile, irreversibile, rivolto all'esterno, finanziario o privilegiato?
- Il richiedente aveva l'ambito richiesto?
- L'approvazione è stata richiesta, concessa, negata, scaduta o aggirata dalla politica di emergenza?
- Quanto è costato lo strumento, quante volte è stato richiamato e quale budget cumulativo è rimasto?
- Quali prove esistono per il debug, la revisione della conformità e il rollback?
L'architettura seguente presuppone che il gateway riceva già chiamate di modello. L'esecuzione dello strumento può quindi essere instradata attraverso lo stesso gateway, tramite un servizio collaterale o tramite una libreria standard che segnala al gateway prima e dopo ogni chiamata allo strumento.
Architettura di riferimento: un livello di governance dello strumento a livello di gateway
Un sistema pratico di governance degli agenti ha sette componenti:
- Registro degli strumenti: l'elenco autorevole di strumenti approvati, server MCP, funzioni ospitate, strumenti di esecuzione locale e API interne.
- Identità e livello chiave: chiavi gateway, utenti, tenant, account di servizio, team e clienti rivenditori.
- Motore di ambito: controlli dei criteri che decidono se una chiave o un utente può richiamare una funzionalità specifica dello strumento.
- Classificatore di rischio: metadati che descrivono il raggio dell'esplosione, la sensibilità dei dati, la reversibilità, l'impatto esterno e l'esposizione ai costi.
- Flusso di lavoro di approvazione: approvazione umana o di sistema per azioni ad alto rischio prima dell'esecuzione.
- Budget e registro dei limiti di velocità: limiti per strumento e per agente, non solo limiti di token per modello.
- Archiviazione di controllo e traccia: record uniti per chiamate di modelli, chiamate di strumenti, approvazioni, errori e risultati.
L'importante decisione progettuale è rendere il gateway il punto decisionale politico anche se lo strumento vero e proprio viene eseguito altrove. Ad esempio, uno strumento browser può essere eseguito in un lavoratore sandbox e una scrittura CRM può essere eseguita all'interno di un servizio interno. Il gateway valuta comunque se la chiamata è consentita, registra la decisione, tiene traccia dei costi e restituisce una decisione o un rifiuto di autorizzazione firmato.
Passaggio 1: crea un registro centrale degli strumenti
Un registro degli strumenti è l'inventario che impedisce che la "capacità dell'agente sconosciuto" diventi l'impostazione predefinita. Ogni strumento dovrebbe avere un proprietario, un livello di rischio e metadati operativi. Un record di registro minimo può assomigliare a questo:
{ "tool_id": "crm.create_ticket", "display_name": "Crea ticket di supporto CRM", "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" }
Per i server MCP, il registro deve includere anche l'URL del server, gli strumenti pubblicizzati, la versione dello schema, il metodo di autorizzazione, la data dell'ultima revisione e se i nuovi strumenti sono disabilitati per impostazione predefinita. MCP migliora l'interoperabilità, ma la compatibilità dei protocolli non è la stessa cosa dell'autorizzazione alla produzione. Le risorse e le operazioni sensibili necessitano ancora di ambiti espliciti, controlli del percorso e isolamento dei tenant.
Campi di registro consigliati
- Nome dello strumento, ID canonico, proprietario e contatto di guardia.
- Posizione di esecuzione: strumento del provider ospitato, server MCP, API interna, browser work, code runner, processo in coda o strumento SDK locale.
- Tenant, team, utenti, versioni agente e profili modello consentiti.
- Classificazione dei dati: pubblici, interni, metadati del cliente, contenuto del cliente, segreti, dati di pagamento, credenziali, dati regolamentati.
- Livello di rischio e reversibilità.
- Ambiti richiesti e politica di approvazione.
- Timeout, limiti di tariffa, chiamate massime per esecuzione, budget cumulativo per esecuzione e costo massimo per chiamata.
- Modalità di registrazione: payload completo vietato, oscurato, sottoposto ad hashing, campionato o conservato esplicitamente.
- Istruzioni di rollback e percorso di escalation.
Passaggio 2: separa gli ambiti del modello dagli ambiti dello strumento
Una chiave del gateway di produzione dovrebbe esprimere ciò che può fare il chiamante. L'accesso al modello e l'accesso allo strumento dovrebbero essere indipendenti. Ad esempio:
modello:chat
modello: incastri
strumento:docs.search_readonly
strumento:crm.create_ticket
strumento:email.send_requires_approval
strumento:billing.refund_blocked
tool:code.execute_blockedCiò impedisce a un chatbot a basso rischio di diventare un agente di automazione accidentale. Supporta anche i modelli di ruolo:
- Assistente per sviluppatori: chat del modello, ricerca di documentazione, spiegazione del codice, nessuno strumento di scrittura di produzione.
- Bot di supporto: ricerca del cliente, creazione di ticket, redazione di risposte, approvazione richiesta per invii esterni.
- Agente analista: query di data warehouse di sola lettura con limiti di riga, nessuna esportazione dei clienti per impostazione predefinita.
- Agente amministrativo: operazioni privilegiate ristrette, approvazione forte, chiavi di breve durata, controllo completo.
- Agente tenant del rivenditore: accesso al modello con ambito tenant, strumenti con ambito tenant, limiti di budget per cliente.
La raccomandazione è di chiudere con errore: gli strumenti sconosciuti vengono negati, gli ambiti mancanti negano l'esecuzione, gli strumenti MCP appena pubblicizzati sono inattivi fino all'approvazione e gli strumenti locali devono utilizzare lo stesso wrapper di policy degli strumenti ospitati.
Passaggio 3: classifica gli strumenti in base al raggio dell'esplosione
Non tutte le chiamate agli strumenti necessitano dell'approvazione umana. La governance dovrebbe essere proporzionale al rischio. Un modello di classificazione utile è:
Questa classificazione dovrebbe essere visibile nella revisione del codice e nell'interfaccia utente di amministrazione. Le descrizioni degli strumenti da sole non sono sufficienti perché gli agenti possono trattare le descrizioni come istruzioni. Il motore delle politiche dovrebbe fare affidamento sui metadati e sugli ambiti del registro, non solo sui nomi degli strumenti in linguaggio naturale.
Passaggio 4: aggiungi cancelli di approvazione per le azioni ad alto rischio
L'approvazione dovrebbe essere mirata. Se ogni chiamata allo strumento richiede una persona, l'agente diventa inutilizzabile. Se nessuna chiamata allo strumento richiede l'approvazione, il sistema potrebbe concedere un'agenzia eccessiva.
Un flusso di approvazione comune:
- L'agente richiede una chiamata allo strumento con argomenti strutturati.
- Il gateway valuta identità, ambito, livello di rischio, budget e policy.
- Se è richiesta l'approvazione, il gateway restituisce un evento di approvazione in sospeso invece di eseguire lo strumento.
- L'applicazione mostra un'anteprima all'utente o invia una notifica operativa a un canale di approvazione.
- L'approvatore può approvare, negare, modificare gli argomenti se la politica lo consente o richiedere chiarimenti.
- Il gateway registra la decisione ed esegue solo la versione approvata.
Il payload di approvazione dovrebbe mostrare l'azione in termini umani, non solo in JSON non elaborato:
{ "approval_id": "appr_123", "agent_run_id": "run_456", "requested_by_user": "utente_789", "tool_id": "email.send", "risk_tier": "comunicazione_esterna", "summary": "Invia una risposta a [email protected] riguardo al ticket n. 4812", "argomenti_redatti": { "a": "[email protected]", "subject": "Aggiornamento sul ticket n. 4812", "body_hash": "sha256:..." }, "expires_at": "2026-08-09T12:30:00Z" }
L'approvazione è particolarmente utile per comunicazioni esterne, azioni finanziarie, scritture irreversibili, amministrazione privilegiata ed esportazioni di dati di grandi dimensioni. Di solito non è necessario per la ricerca di documentazione pubblica a basso volume.
Passaggio 5: monitora i budget e i limiti di tariffa per strumento
I budget dei token non sono sufficienti. Un modello economico può innescare ricerche costose, sessioni del browser, esecuzioni di codice, chiamate API di terze parti o lunghi cicli di strumenti. Il gateway dovrebbe tenere traccia di almeno quattro contatori:
- Conteggio chiamate per strumento: chiamate massime per esecuzione, utente, tenant e finestra temporale.
- Costo per strumento: addebiti diretti di terze parti, costo del browser/tempo di esecuzione, costo della ricerca o stima dello storno di addebito interno.
- Costo cumulativo di gestione dell'agente: token del modello più costi dello strumento.
- Profondità del loop: numero massimo di iterazioni modello-strumento-modello.
Quando viene raggiunto un limite, il gateway dovrebbe evitare un errore hardware silenzioso, quando possibile. I modelli di degrado più sicuri includono la restituzione di un riepilogo dei progressi, la richiesta di approvazione per continuare, la riduzione della profondità di recupero, l'accodamento di un processo in background o il passaggio a una modalità di sola lettura. La negazione definitiva è ancora appropriata per strumenti bloccati, ambiti mancanti, funzionalità MCP sconosciute e azioni pericolose.
Passaggio 6: unisci la telemetria del modello e dello strumento in un unico record di controllo
Il debug dell'agente fallisce quando i log del modello si trovano in un posto e i log degli strumenti si trovano altrove. Il record di audit dovrebbe collegare l'intera catena:
- Tenant, area di lavoro, utente, account di servizio e chiave gateway.
- ID agente, versione agente, versione modello prompt e ID modello.
- Nome dello strumento, versione del registro, URL del server o ambiente di esecuzione e hash dello schema.
- Hash di input dello strumento o input redatto, mai payload sensibili non elaborati per impostazione predefinita.
- Stato di approvazione, identità dell'approvatore, timestamp di approvazione e hash dell'argomento approvato.
- Latenza, nuovi tentativi, errori del fornitore, errori dello strumento, costo del token, costo dello strumento e risultato finale.
- Riferimento al rollback, se l'azione ha cambiato stato.
La documentazione di tracciamento dell'SDK degli agenti di OpenAI include tracce per generazioni LLM, chiamate di strumenti, trasferimenti, guardrail ed eventi personalizzati, che supporta un principio di osservabilità più ampio: le tracce degli agenti dovrebbero includere l'attività dello strumento, non solo l'utilizzo e la latenza dei token. Tuttavia, una singola pipeline SDK potrebbe non coprire tutti gli strumenti ospitati, il percorso di esecuzione locale o l'API interna. L'audit a livello di gateway aiuta a normalizzare i record tra fornitori e framework.
La privacy è importante. I registri dettagliati migliorano il debugging e la revisione della conformità, ma la conservazione dei dati grezzi e del carico utile dello strumento può creare una nuova responsabilità in termini di sicurezza. Redigere o sottoporre ad hash input che contengono segreti, credenziali, dati di pagamento, dati personali o documenti proprietari. Archivia i payload non elaborati solo in base a criteri di conservazione, controlli di accesso e regole di eliminazione espliciti.
Passaggio 7: tratta i server MCP e gli strumenti di terze parti come dipendenze della catena di fornitura
I server MCP e gli strumenti di terze parti devono essere sottoposti allo stesso processo di revisione delle librerie, dei webhook e delle dipendenze dell'infrastruttura. I controlli consigliati includono:
- Mantieni una lista consentita di server MCP approvati e origini degli strumenti.
- Aggiungi le versioni ove possibile e registra gli hash dello schema.
- Richiedi un proprietario per ogni server e strumento ad alto rischio.
- Esamina i nomi degli strumenti, le descrizioni, gli schemi e le richieste di autorizzazione prima di abilitarli.
- Disabilita gli strumenti appena aggiunti fino alla revisione.
- Verificare gli ambiti richiesti per percorso o funzionalità.
- Separare le credenziali del tenant ed evitare token condivisi tra i clienti.
- Esegui strumenti non attendibili o ad alto rischio in sandbox con restrizioni di rete e file system.
Il fatto che uno strumento sia esposto tramite un protocollo standard non lo rende sicuro. Il livello di governance necessita ancora di privilegi minimi, autorizzazione esplicita, controllo della versione e verificabilità.
Lista di controllo per l'implementazione
Progettazione delle politiche
- Definire modelli di ruolo per utenti agente comune e account di servizio.
- Crea ambiti separati per le chiamate ai modelli e alle chiamate agli strumenti.
- Classificare gli strumenti in base alla sensibilità dei dati, reversibilità, impatto esterno, impatto finanziario e livello di privilegio.
- Imposta il comportamento di rifiuto predefinito per strumenti sconosciuti e ambiti mancanti.
- Definire le regole di approvazione solo per le azioni ad alto rischio.
Applicazione del gateway
- Richiedi a ogni agente di richiamare gli strumenti tramite il gateway o un wrapper di policy firmato.
- Verifica tenant, utente, chiave, agente, modello, strumento, ambito, budget e stato di approvazione prima dell'esecuzione.
- Applica la massima profondità di chiamata degli strumenti e il costo di esecuzione cumulativo.
- Registra la versione del registro dello strumento e l'hash dello schema per ogni chiamata.
- Fail chiuso quando il motore delle politiche non riesce a prendere una decisione.
Audit e operazioni
- Unisci le chiamate al modello e alle chiamate allo strumento sotto un unico ID di traccia o esecuzione agente.
- Per impostazione predefinita, oscura o hash input dello strumento sensibile.
- Conservare la prova dell'approvazione con il registro finale dell'esecuzione.
- Esporre agli amministratori l'analisi dei costi per strumento e dei limiti di velocità.
- Proprietari di rollback dei documenti per strumenti che modificano lo stato.
Compromessi da aspettarsi
Coerenza rispetto allo sforzo di integrazione. La governance a livello di gateway garantisce un'applicazione coerente tra modelli, SDK e team. Il costo è l'adozione: gli sviluppatori devono instradare l'esecuzione dello strumento attraverso il percorso approvato invece di richiamare gli strumenti direttamente dal codice dell'applicazione.
Privilegio minimo rispetto alla complessità delle policy. Gli ambiti a grana fine riducono il raggio di esplosione, ma richiedono modelli, convenzioni di denominazione e pulizia regolare. Senza modelli, i team potrebbero concedere autorizzazioni eccessive per muoversi più velocemente.
Approvazione contro autonomia. L'approvazione umana riduce il rischio di azioni irreversibili, ma aggiunge latenza. Utilizza le approvazioni per strumenti ad alto rischio, non per ogni ricerca o ricerca.
Verificabilità ed esposizione dei dati. I ricchi log aiutano nella risposta agli incidenti e nel debug. La registrazione del payload non elaborato può esporre segreti e dati personali. Redazione, hashing, conservazione configurabile e revisione dell'accesso non sono dettagli facoltativi.
Limiti rigidi rispetto al completamento delle attività. I limiti di costo per strumento impediscono la fuga degli agenti. Possono anche interrompere il lavoro legittimo di lunga durata. Fornisci percorsi di continuazione come approvazione per continuare, code in background o risultati parziali riepilogati.
Previsioni: dove sta andando questo modello
Previsione: la governance degli agenti diventerà più incentrata sull'identità. I team chiederanno meno spesso "quale modello è stato utilizzato?" e più spesso "quale persona o servizio autenticato ha consentito l'azione di questo strumento?"
Previsione: i registri degli strumenti diventeranno normali quanto i registri dei modelli. Con il moltiplicarsi dei server MCP, delle API interne e degli strumenti ospitati, i team di produzione avranno bisogno di un inventario delle funzionalità consentite, dei proprietari, degli schemi e dei livelli di rischio.
Previsione: la governance dei costi passerà dal reporting solo token al reporting a livello di azione. La parte più costosa dell'esecuzione di un agente potrebbe essere il recupero, l'automazione del browser, l'esecuzione del codice o le API di terze parti piuttosto che la chiamata del modello stesso.
Conclusione attuabile
Inizia con una regola: la chiave del modello non è la chiave dello strumento. Quindi costruisci verso l'esterno. Crea un registro di strumenti approvati, assegna proprietari e livelli di rischio, richiedi ambiti espliciti, aggiungi approvazioni solo dove l'azione ha un raggio di azione significativo, applica budget per strumento e unisci eventi di modello e strumento in un unico audit trail.
L'obiettivo non è rendere gli agenti impotenti. L’obiettivo è rendere il loro potere leggibile, mirato, reversibile ove possibile e responsabile. Questa è la base pratica per la governance delle API del team mentre gli agenti passano dalla risposta alle domande all'azione.