Come creare il catalogo dei tool di un agent AI

CRM, email, file, calendario non sono quattro permessi. Sono quattro famiglie di sistemi che possono contenere decine di letture, scritture, esportazioni, cancellazioni e passaggi verso persone reali.

Se il tuo inventario dice soltanto che l'agent “usa il CRM”, non sai quale record può leggere, con quale identità, quale campo può cambiare, chi conferma e cosa resta dopo l'azione.

Un catalogo dei tool serve a rendere quel confine esplicito. Per ogni strumento collega ciò che il modello vede a ciò che l'infrastruttura permette davvero. La scheda non deve impressionare chi guarda una demo. Deve aiutare owner, security e operations a rispondere a una domanda concreta: qual è il massimo effetto possibile da questa chiamata?

Distingui catalogo tool, inventario e matrice accessi

Tre artefatti vicini hanno unità diverse.

L'inventario dei workflow AI resta il router: collega agent, processo, owner e stato. Il catalogo scende di un livello. Un agent può avere dieci tool; lo stesso tool può essere esposto a tre agent con scope diversi.

Anche il nome search_customer può ingannare. Potrebbe cercare per email in un solo tenant oppure interrogare l'intero database. Potrebbe restituire nome e stato contrattuale o anche note libere. Il catalogo descrive questo comportamento senza obbligare chi approva a leggere l'implementazione.

Parti dall'identità effettiva

Microsoft suggerisce di trattare l'agent come un principal dedicato con owner, scopo e ciclo di vita. Prima del tool, registra quindi chi agisce.

Le modalità comuni sono:

• identità propria dell'agent

• delega dell'utente corrente

• account tecnico condiviso

• elevazione temporanea per un singolo passaggio

• combinazione di identità fra più sistemi

La combinazione non può restare implicita. Se l'agent legge con l'identità dell'utente ma scrive con un account tecnico, la conferma deve mostrare l'autorità usata per l'effetto. Se un tool recupera dati da una cartella e un altro li invia all'esterno, il rischio nasce dalla composizione anche quando ciascun accesso sembra limitato.

L'articolo sugli accessi di un workflow AI aiuta a progettare ruoli, scadenza e revoca. Nel catalogo riporta il binding effettivo:

execution_identity:
  mode: dedicated_agent_principal
  principal_ref: agent-support-prod
  delegated_user_scope: false
  elevation: none
owner: support-operations

Non inserire token, ID sensibili o dettagli che aprono una nuova superficie. Usa riferimenti controllati che permettano al team autorizzato di risalire alla configurazione.

Scrivi il record minimo di ogni tool

Un record utile contiene almeno cinque gruppi di informazioni.

Identità e provenienza

• nome stabile e ID interno

• publisher o team proprietario

• origine del pacchetto, server o connettore

• versione o hash della configurazione

• owner tecnico e owner di processo

Interfaccia visibile al modello

• nome esposto

• descrizione completa

• schema degli input

• schema dell'output

• esempi ammessi e casi esclusi

Autorità ed effetto

• identità di esecuzione

• risorse e dati raggiungibili

• operazioni ammesse

• side effect diretti e indiretti

• reversibilità e ricevuta

Gate operativi

• conferma richiesta

• limiti per task, tempo e volume

• policy applicata ai parametri

• ambienti ammessi

• fallback e comportamento al timeout

Ciclo di vita

• stato: bozza, test, attivo, sospeso o ritirato

• data dell'ultima review

• trigger di revisione

• procedura di revoca

• test e log obbligatori

Ecco un esempio sintetico:

tool_id: crm.create_draft_followup.v2
publisher: internal-crm-team
model_visible_name: create_draft_followup
description_sha256: 8f2a...d91c
operations:
  allowed: [create_draft]
  forbidden: [send, delete, change_owner]
scope:
  tenant: current
  objects: [open_lead]
  fields_write: [draft_subject, draft_body]
approval:
  before_effect: false
  before_send: required_outside_tool
receipt:
  fields: [draft_id, actor, timestamp, source_case]
revocation:
  owner: crm-security
  max_time: 15m

Il nome dice draft. L'enforcement deve impedire l'invio anche se il modello chiede un parametro inatteso. Una parola corretta nella descrizione non è un controllo tecnico.

Separa lettura, proposta e scrittura

Molti cataloghi ereditano connettori troppo larghi. Un singolo tool manage_ticket può leggere, modificare, assegnare, chiudere e cancellare. Per il modello, una descrizione lunga dovrebbe spiegare quando scegliere ogni azione. Per l'infrastruttura, invece, tutte le azioni condividono spesso la stessa credenziale.

Preferisci unità con una conseguenza riconoscibile:

• get_ticket_summary

• create_ticket_draft

• propose_ticket_assignment

• apply_ticket_assignment

• close_ticket

Non significa moltiplicare tool senza criterio. Significa separare passaggi che richiedono autorità, conferme e rollback diversi.

Microsoft propone ruoli basati su task e la separazione fra raccolta delle evidenze e remediation. Applica lo stesso principio al catalogo. Lettura, proposta e azione non sono sinonimi.

Per un'operazione ad alto impatto, la scheda dovrebbe indicare:

1. quali parametri il modello può proporre

2. quali valori arrivano da fonti fidate

3. quale policy valida la richiesta

4. chi vede cosa nella conferma

5. quale identità esegue dopo l'approvazione

6. quale ricevuta permette riconciliazione e indagine

La matrice di approvazione per workflow AI definisce livelli e autorità. Il catalogo applica quella regola alla singola azione.

Descrivi lo scope su tre assi

Read-only sembra prudente, ma può ancora esporre troppo. Registra lo scope per:

• risorsa: tenant, workspace, progetto, cartella, tabella o casella

• dato: collezione, etichetta, categoria, campo o periodo

• operazione: lettura, ricerca, export, bozza, update, send, delete o admin

Esempio:

Risorsa   tenant corrente / coda supporto EU
Dato      ticket aperti / esclusi allegati e note private
Operazione search + read summary / export vietato

Aggiungi il limite temporale quando serve. Un agent per la chiusura mensile può ottenere un entitlement di due ore, non un ruolo permanente. L'identità resta stabile per audit; l'elevazione scade.

Annota anche lo scope composto. L'accesso a email e drive può permettere di correlare dati che nessuno dei due owner aveva valutato insieme. Il catalogo non risolve da solo questa combinazione, ma la rende visibile al review gate.

Tratta i metadata come una superficie di cambio

Il modello usa nome, descrizione e schema per decidere se e come chiamare un tool. Questi metadata non sono semplice documentazione.

Microsoft ha descritto un pattern in cui una descrizione tool modificata introduce istruzioni che portano l'agent a raccogliere e inoltrare dati aggiuntivi. La raccomandazione è netta: tratta le descrizioni come istruzioni di sistema, verifica i publisher e riesamina le modifiche.

Per ogni versione conserva:

• publisher e origine verificata

• nome e versione del server o pacchetto

• descrizione verbatim

• schema verbatim

• hash dei metadata

• diff rispetto alla versione approvata

• test eseguiti

• approvatore e data di attivazione

Un aggiornamento che lascia invariato il nome ma cambia descrizione o schema deve riaprire il gate. Lo stesso vale se un endpoint cambia dominio, se un parametro diventa opzionale o se una risposta inizia a contenere testo non fidato che tornerà nel contesto dell'agent.

OWASP distingue tool misuse, abuso di identità e rischio di supply chain. Il catalogo deve quindi rispondere a tre domande separate:

1. il tool può essere usato per uno scopo diverso?

2. l'identità gli concede un impatto eccessivo?

3. publisher, pacchetto o metadata possono cambiare senza review?

Una sola colonna approved: yes non copre nessuna delle tre.

Registra approvazioni e policy prima dell'effetto

La conferma umana è utile solo se arriva prima dell'effetto e mostra informazioni sufficienti.

Per ogni tool definisci:

• never: l'azione non richiede conferma perché non ha side effect e resta nel perimetro ammesso

• always: ogni esecuzione richiede approvazione

• conditional: la policy decide in base a importo, destinazione, dato o tipo di azione

• forbidden: l'agent non dispone del tool in quell'ambiente

Non chiedere Procedo? dopo un riepilogo scritto dal modello. Mostra i parametri che determinano la conseguenza: destinatario, record, campi, importo, allegati, policy applicata e identità che agirà.

La conferma non deve concedere un permesso riutilizzabile se l'utente intendeva approvare una sola azione. Registra ambito e scadenza dell'autorizzazione.

Per delete, send, pay, publish, export e cambi di privilegio, valuta un tool separato e un percorso reversibile o staged. Una bozza o una quarantena riducono il raggio d'impatto meglio di un disclaimer.

Collega test, log e ricevute

Il record è verde solo se puoi provare che l'implementazione coincide.

Testa almeno:

• operazioni fuori allowlist rifiutate

• risorse fuori scope non raggiungibili

• parametri inattesi scartati

• approvazione richiesta nel punto giusto

• revoca effettiva entro il tempo dichiarato

• timeout e retry senza doppio effetto

• metadata modificati che riaprono il gate

• ricevuta completa per esito positivo, rifiuto e errore

La risposta del modello non dimostra che il tool si sia fermato. Controlla policy decision, chiamata, parametri e stato del sistema bersaglio.

Definisci un log minimo comune:

trace_id: tr_20260902_041
agent_version: support-agent-3.2
tool_id: crm.create_draft_followup.v2
tool_metadata_hash: 8f2a...d91c
authority: agent-support-prod
policy_result: allow_draft_only
effect: draft_created
receipt_id: dr_8821

Non registrare più dati del necessario. Il log deve permettere di capire cosa è successo e sotto quale autorità, senza diventare una copia permanente dei payload.

Gestisci sospensione, revoca e ritiro

Un tool non resta approvato per sempre. Definisci trigger di revisione:

• nuova versione o publisher

• modifica di descrizione, schema o endpoint

• nuovo tipo di dato o risorsa

• aumento di autonomia o volume

• incidente, finding o anomalia

• owner mancante

• credenziale, contratto o dipendenza in scadenza

La procedura di stop deve invalidare l'accesso, non limitarsi a nascondere il tool dall'interfaccia. Un agent già in esecuzione può avere token, job o retry pendenti. Prevedi il drenaggio o l'annullamento sicuro e verifica lo stato finale.

Conserva le versioni ritirate per spiegare azioni storiche, ma impedisci nuove chiamate. Il record dovrebbe dire da quando non è più valido e quale sostituto è ammesso.

Il controllo delle modifiche di un workflow AI aiuta a valutare impatto e dipendenze. Nel catalogo, un cambio tool produce un diff circoscritto e riapre i test legati a quella superficie.

Esempio fittizio: agent per richieste d'acquisto

Un agent raccoglie requisiti e prepara una richiesta d'acquisto. La prima versione ha un connettore procurement con operazioni search_supplier, create_request, approve_request e send_order sotto la stessa identità.

Il catalogo rivela che il caso d'uso richiede solo ricerca e bozza. Il team sostituisce il connettore largo con due tool:

• search_approved_supplier, limitato all'elenco approvato e senza export

• create_purchase_request_draft, limitato a bozza e con receipt

approve_request e send_order non vengono descritti come vietati: non sono proprio esposti all'agent. La successiva approvazione avviene nel sistema procurement con identità e policy proprie.

Quando il publisher aggiorna la descrizione del tool di ricerca, l'hash cambia. Il gate sospende quella versione, confronta diff e schema, riesegue i casi sul leakage e poi sposta l'alias approvato. Nessuna modifica silenziosa entra nel contesto.

Think, Build, Enable applicato al catalogo

Think: elenca effetti, identità, dati e autorità necessari per il singolo task. Escludi ciò che la demo non richiede.

Build: separa operazioni, applica scope su risorsa, dato e azione, versiona metadata e collega policy, test e receipt.

Enable: assegna owner, pubblica una vista leggibile, addestra chi approva e prova revoca e sospensione prima dell'incidente.

Progetta con MAIKER HUB automazioni e agent AI con n8n partendo da tool e permessi effettivi. Un catalogo ben fatto non mostra quante integrazioni hai. Mostra quali conseguenze hai scelto di rendere possibili, con quale prova e sotto quale autorità.