MCP e tool layer per agent AI B2B

Cos'è un tool layer (e cosa non è)

Un tool layer è il contratto tra l'agent e i tuoi sistemi: operazioni nominate, input/output tipizzati, contesto auth, rate limit e policy sui side effect. MCP e protocolli simili standardizzano come gli host scoprono e invocano quei tool; non sostituiscono il design di prodotto. Non è un pass-through verso ogni microservizio interno. La discovery di cinquanta endpoint di write è come gli agent inventano disastri creativi. Tratta i tool come un'API pubblica per un caller semi-trusted (il modello): least privilege, validation, idempotency e audit di default.

• Scelta del protocollo ≠ modello di security
• Il catalogo va curato per agent e persona
• I tool con side effect servono gate più forti dei tool di read
• L'approvazione umana sta sopra i tool, non dentro ogni connector

Tool stretti vs API god-mode

Preferisci `get_order_status(order_id)`, `create_draft_ticket(...)`, `propose_price_change(...)` rispetto a `run_sql`, `call_http` o `erp_proxy(any)`. I tool stretti codificano l'intent e rendono trattabili allowlist, test ed evidence card UX. Se devi wrappare un backend ampio, metti una facade davanti: route allowlistate, field mask e max blast radius (es. update su singolo record). Non dare al modello un bearer token con scope admin ERP. La composizione sta nel grafo (più call strette), non in un mega-tool che 'se la cava da solo'.

• Un intent di business per tool quando è pratico
• Vieta esecuzione codice arbitraria e shell grezza negli agent di produzione
• Separa cataloghi di read da cataloghi di write
• Reviewa i nuovi tool come aggiunte API in CAB o design review

Permessi e principal autenticato

Ogni invocazione tool gira come utente (o identity di servizio strettamente scoped) con tenant e ruolo. Eredita i diritti da SSO e identity; non escalare a un account god condiviso per 'far funzionare la demo'. Controlla l'autorizzazione prima della call outbound. Logga i deny. Ruoli partner e plant-scoped devono sopravvivere nei filtri tool come nelle route UI. Allinea a security AI enterprise per rischi di prompt injection ed esfiltrazione via tool: il testo ticket non trusted è dato, non un'istruzione per allargare lo scope.

Schema, validation e idempotency

Pubblica JSON schema (o equivalente) per ogni tool. Valida enum, range, ID e campi required al boundary. Rifiuta property sconosciute quando abilitano lo smuggling. I tool con side effect prendono idempotency key e restituiscono shape di risultato stabili così i retry dai grafi agent non fanno double-post. Tieni i messaggi di errore actionable per il grafo (retryable vs fatal vs needs human) senza leakare stack trace o secret nel contesto del modello.

Connector ERP, CRM e ticket

I connector sono integrazioni productizzate, non script del weekend. Mappa ai system of record con ownership chiara per data readiness. Preferisci tool draft/propose più human-in-the-loop prima di post ERP irreversibili. I tool ticket e CRM dovrebbero field-maskare la PII e rispettare ACL a livello record. Le operazioni bulk servono cap hard e gate di conferma. Credential di sandbox, contract test e fixture di replay appartengono all'acceptance di delivery—vedi le pratiche di integrazione ERP.

• Pattern draft-then-commit per sistemi money-moving
• External ID stabili nei risultati tool per audit e UI
• Circuit breaker quando latenza o error rate ERP salgono
• Non inventare record ID nel modello—solo tool di lookup

RAG e search come tool

Esponi il retrieval come tool esplicito con filtri tenant e confidence—non come stuffing di contesto ambientale. Segui RAG in produzione per ACL ed evaluation. Restituisci chunk ID e citazioni che UI e card HITL possono renderizzare. Limita la size dei risultati così gli agent non si annegano di token. Tieni tool di write e tool di retrieval in set di permesso separati.

Versioning e compatibilità

Nomi tool e schema sono contratti. Versiona i breaking change (`create_ticket` → `create_ticket_v2`) e tieni le vecchie versioni finché grafi e prompt migrano. Applica la stessa disciplina di API design e versioning. Pinna gli agent a una versione di catalogo tool in produzione. Schema drift silenzioso a metà volo causa failure misteriosi e retry unsafe. Documenta le finestre di deprecation per contractor e team interni allo stesso modo.

Observability per le tool call

Traccia nome tool, latenza, classe success/failure, tenant, correlation ID e se è seguito un gate umano. Alimenta dashboard e alert di observability su spike di errore e volumi di write insoliti. Redigi i campi sensibili nelle trace. Conserva abbastanza per debuggare 'perché abbiamo postato questo ordine' senza tenere payload PII completi per sempre. Accoppia a strategia di testing: contract test per tool, chaos per outage delle dipendenze e scenario golden agent che assertano quali tool possono essere chiamati.

• Alert su sequenze tool novel che bypassano i grafi attesi
• Budgetta max tool call per run
• Sample delle trace di produzione per anomalie di permesso
• Includi metriche tool nelle review di go-live readiness

Delivery MVP e gate contractor

Spedisci un catalogo minimo per un journey: poche read, una write draft, un commit-after-approval. Non-goal: aprire MCP a tutta la superficie API enterprise al day one. Acceptance: validazione schema, test ACL, write idempotenti, audit di arg/result ID dei tool, runbook per outage connector. Collega a hiring contractor, criteri di acceptance AI e production readiness. Costa il tool layer nelle stime—connector e safety rail dominano le fee del modello per agent B2B reali.

Prossimi passi

Elenca ogni tool di cui l'agent avrebbe bisogno per un journey verticale. Barrane quelli più ampi di un singolo intent di business. Ciò che resta è il catalogo v1. Poi reviewa AI agentica, UX human-in-the-loop, altre risorse, case study, prenota una call, o contatti prima di collegare agent a ERP o CRM con credenziali ampie.

Domande frequenti