Tool e pratiche per creare agenti AI: come progettarli, testarli e metterli in produzione

Introduzione: perché i tool senza le pratiche producono agenti fragili

Escono di continuo nuovi framework per costruire agenti AI. La demo funziona in pochi minuti, poi qualcuno prova a metterla in produzione e arrivano allucinazioni, costi fuori controllo e passaggi manuali che annullano il valore dell’automazione. Per questo nella consulenza AI di Niuexa seguiamo un percorso in 10 passi, dai failure modes al rilascio controllato.

Un agente AI che funziona in demo e fallisce in produzione di solito non ha un problema di modello, ma di ingegneria: mancano i test, i guardrail, le metriche e il processo che rendono affidabile un prototipo.

Gli agenti arriveranno comunque, spesso dentro software che l’azienda usa già: secondo Gartner (comunicato del 26 agosto 2025) entro la fine del 2026 il 40% delle applicazioni aziendali integrerà agenti dedicati a compiti specifici, contro meno del 5% nel 2025. Lo stesso Gartner (25 giugno 2025) prevede che oltre il 40% dei progetti di agentic AI sarà cancellato entro la fine del 2027, per costi crescenti, valore poco chiaro o controlli del rischio inadeguati. La differenza la fanno le pratiche descritte in questa guida.

Demo vs produzione: cosa si rompe e perché

In una demo, l'agente riceve input puliti, opera in un contesto controllato e non ha vincoli di costo o latenza. In produzione, affronta: input ambigui o maliziosi, dati incompleti, tool che falliscono, utenti che escono dal flusso previsto, picchi di traffico, e budget per token che si esaurisce. Il gap tra demo e produzione non si colma con un modello migliore, ma con engineering practices rigorose.

Definizione operativa di "agente"

In questa guida, per "agente AI" intendiamo un sistema che:

• Pianifica: scompone un obiettivo in sotto-task e sceglie la sequenza di azioni
• Usa tool: invoca API, database, servizi esterni attraverso tool calling strutturato
• Gestisce stato: mantiene memoria della conversazione e del contesto tra i passi
• Gestisce errori: rileva fallimenti dei tool, ripianifica o escala a un operatore umano
• Rispetta policy: opera entro limiti definiti di budget, azioni consentite e dati accessibili

La mappa dei tool: cosa serve nello stack

Lo stack va scelto in base al processo: modello, istruzioni e tool, controllo dell’esecuzione, accesso alle informazioni necessarie e controlli operativi. Un’API del gestionale o una query autorizzata possono fornire il contesto senza RAG o database vettoriali. Un framework dedicato serve quando aiuta a gestire la complessità; non è un requisito per ogni agente.

LLM + API: criteri di selezione

La scelta del modello non è solo una questione di benchmark. I criteri che contano in produzione sono:

• Supporto nativo al tool calling: il modello deve gestire function calling con schema JSON validabile, non solo testo libero
• Costo per token: con volumi elevati, la differenza di prezzo per milione di token tra un modello e l’altro (anche di un ordine di grandezza) decide la sostenibilità economica
• Latenza P95: non la latenza media, ma il 95° percentile. Un agente che risponde in 2s nel 90% dei casi e in 15s nel restante 10% genera frustrazione
• Context window: per agenti con conversazioni lunghe o documenti da analizzare, la finestra di contesto limita o abilita interi casi d'uso
• Affidabilità del tool calling: percentuale di chiamate a tool con schema valido e parametri corretti (testare empiricamente, non fidarsi dei benchmark)
• Dove gira il modello: API in cloud oppure un modello più piccolo, specializzato sul compito, su infrastruttura propria. Il secondo costa meno per chiamata e tiene i dati in casa, ma va mantenuto e rende bene solo su compiti stretti e ripetitivi

Framework di orchestrazione a confronto

Il framework di orchestrazione è il "sistema nervoso" dell'agente: gestisce il flusso di esecuzione, le chiamate ai tool, la memoria e il recovery dagli errori.

Piattaforme dei fornitori o stack proprio

Accanto ai framework open source, i grandi fornitori offrono piattaforme per costruire e gestire agenti dentro il proprio ecosistema. Sono tecnologie da valutare come le altre, e il criterio più utile è partire da dove l’azienda lavora già: lì ci sono i dati, i permessi e le persone che useranno l’agente.

Standard di interoperabilità: MCP e A2A

Due protocolli aperti stanno diventando il modo comune di collegare agenti, tool e dati:

• MCP (Model Context Protocol): introdotto da Anthropic a fine 2024, standardizza il modo in cui un agente si collega a tool e fonti di dati. Un connettore MCP scritto una volta, per esempio verso il gestionale, può essere usato da modelli e client diversi
• A2A (Agent2Agent): proposto da Google nel 2025 e oggi gestito dalla Linux Foundation, definisce come agenti di fornitori diversi si scambiano compiti e risultati

La conseguenza pratica è una: chiedere che le integrazioni siano costruite su standard aperti, così da poter cambiare modello o fornitore senza riscriverle. Un server MCP resta comunque un tool come gli altri: va registrato nel tool registry, limitato con allowlist e permessi minimi, e testato.

Memoria, contesto e pipeline RAG

Un agente senza memoria è stateless e riparte da zero a ogni interazione. Un agente con troppa memoria consuma token inutilmente e introduce rumore. Il design della memoria richiede tre decisioni:

• Short-term memory: la conversazione corrente, gestita nel context window del modello. Limitata dalla dimensione della finestra
• Long-term memory: informazioni conservate tra sessioni in un archivio adatto al contenuto e ai permessi; un database vettoriale è una delle opzioni, non una scelta obbligatoria
• Working memory: lo stato intermedio dell’esecuzione corrente: quali tool sono stati chiamati, quali risultati ottenuti, quali sotto-task completati

Quando serve recuperare documenti per fondare una risposta, una pipeline RAG (Retrieval-Augmented Generation) può collegare il modello alla conoscenza aziendale. La ricerca può usare parole chiave, vettori o entrambi: suddivisione dei documenti, metodo di recupero e fonti fornite al modello vanno verificati sui casi del processo. Per dati strutturati come un prezzo o lo stato di un ordine, può bastare una lettura autorizzata dal sistema di riferimento.

Per decidere cosa conservare e chi può correggerlo, usi il framework 4D: dato, destinazione, durata e diritto di revisione.

Tool di produzione: osservabilità, logging, rate limiting

Un agente in produzione senza osservabilità è una scatola nera. I tool di produzione essenziali sono:

• Tracing: LangSmith, Arize Phoenix o Helicone, per tracciare ogni step dell’agente con latenza, token consumati e output
• Logging strutturato: ogni decisione dell'agente, ogni tool call e ogni errore devono essere loggati in formato JSON queryable
• Rate limiting: limiti per utente, per sessione e per finestra temporale per prevenire abusi e costi fuori controllo
• Cost tracking: monitoraggio in tempo reale della spesa per token, per agente e per cliente
• Alerting: notifiche automatiche quando le metriche escono dai range accettabili (tasso di errore, latenza, costo)

Pratiche fondamentali: progettare prima di codificare

I tool migliori non compensano un design scadente. Le pratiche che seguono sono il fondamento su cui costruire un agente che funziona in produzione, non solo in demo.

Scegliere il primo processo da affidare a un agente

Prima del design viene la scelta del caso. I processi da cui conviene partire hanno tre caratteristiche:

• Volume alto: lo stesso compito si ripete molte volte al mese, quindi il tempo risparmiato si vede e si misura
• Regole documentabili: chi lo fa oggi sa spiegare come decide, e quelle regole si possono scrivere
• Errori correggibili: uno sbaglio si intercetta e si corregge prima che arrivi al cliente o nel gestionale

Esempi tipici: richieste di primo livello dei clienti (stato ordini, domande ricorrenti), lettura e smistamento dei documenti in arrivo, abbinamento tra fatture e ordini, preparazione di report ricorrenti, gestione degli appuntamenti.

Task decomposition: da obiettivo a sotto-task

Il primo passo è scomporre l'obiettivo dell'agente in una mappa di sotto-task, ciascuno con tool associati e criteri di uscita espliciti. Questa mappa diventa il contratto tra il team di sviluppo e gli stakeholder.

Contractual prompting: istruzioni + schema + regole testabili

Il prompt non è un suggerimento: è un contratto. Ogni istruzione deve essere verificabile con un test automatico. Il contractual prompting combina tre elementi:

• Istruzioni in linguaggio naturale: cosa deve fare l'agente, in che tono, con quali vincoli
• JSON Schema per ogni tool: definizione formale di parametri richiesti, tipi, vincoli di validazione
• Regole testabili: ogni regola del prompt deve poter essere tradotta in un assertion automatica (es. "Non menzionare mai il nome di un competitor" → test: nessun output contiene [lista competitor])

Se una regola del prompt non può diventare un test automatico, non è una regola ma un auspicio, e in produzione gli auspici non bastano.

Tool design: piccoli, deterministici, con I/O validato

Ogni tool esposto all'agente deve seguire tre principi:

• Single Responsibility: un tool fa una sola cosa. "search_knowledge_base" è un buon tool; "search_and_summarize_and_send_email" non lo è
• Determinismo: a parità di input, il tool restituisce lo stesso output (escluso il componente LLM). Questo rende il testing possibile
• I/O validato: input e output definiti con JSON Schema. L'agente non può chiamare un tool con parametri malformati, e il tool non può restituire strutture inattese

{
  "request_id": "REQ-DEMO-001",
  "customer_id": "C-DEMO-01",
  "sku": "SKU-DEMO-42",
  "quantity": 3,
  "unit_price": 12.50,
  "currency": "EUR",
  "source_versions": {
    "customer_record": "C-DEMO-01:v3",
    "price_record": "LISTINO-DEMO:v7"
  },
  "approval_status": "awaiting_review"
}

Human-in-the-loop: quando e come

Non tutte le decisioni devono essere automatiche. Il pattern human-in-the-loop prevede tre livelli di intervento umano:

• Approvazione pre-azione: per azioni irreversibili (es. invio email a cliente, modifica database), l'agente propone l'azione e attende approvazione
• Review post-azione: l'agente esegue e un umano rivede un campione (5-20%) per qualità
• Escalation su incertezza: quando la confidence scende sotto la soglia, l'agente trasferisce il caso a un operatore con il contesto completo

Un agente o più agenti: pattern di orchestrazione

Un sistema multi-agente divide il lavoro tra più agenti specializzati, ciascuno con i propri tool e le proprie istruzioni, coordinati da un orchestratore o da regole di passaggio. Ha senso quando un unico agente dovrebbe gestire troppi tool o competenze molto diverse. Ogni agente in più, però, aggiunge chiamate al modello, costo, latenza e punti in cui qualcosa può rompersi.

Framework come LangGraph, AutoGen (Microsoft) e CrewAI offrono questi pattern già pronti, e le piattaforme dei fornitori descritte sopra includono un’orchestrazione multi-agente nativa.

Il percorso Niuexa: dall’idea alla produzione in 10 passi

Questo è il processo che seguiamo in Niuexa per portare un agente AI dal concept alla produzione. Ogni passo ha un deliverable concreto e un gate di approvazione prima di procedere al successivo.

1. Obiettivo + KPI + failure modes

   Definire l’obiettivo dell’agente in termini misurabili (per esempio la quota di ticket L1 risolti entro un tempo massimo, confrontata con la misura di partenza). Mappare i failure modes: cosa succede se l’agente ha un’allucinazione? Se il tool fallisce? Se il costo per conversazione supera il budget? Ogni failure mode deve avere una contromisura progettata prima di scrivere una riga di codice.

2. Dataset di casi rappresentativi

   Raccogliere esempi del dominio con input, output atteso, casi limite ed errori. Per un primo perimetro ristretto, 50-200 esempi possono essere un’ipotesi di lavoro, non una soglia che certifica l’affidabilità. La copertura va verificata rispetto a frequenza e impatto degli errori, con casi validati da chi conosce il processo.

3. RAG evaluation

   Se l'agente usa RAG, valutare il pipeline di retrieval indipendentemente dal modello: precision@k, recall@k, MRR (Mean Reciprocal Rank). Un retrieval scadente produce risposte scadenti indipendentemente dalla qualità del modello.

4. Tool registry + policy

   Registrare ogni tool con: nome, descrizione, JSON Schema per input/output, policy di accesso (chi può usarlo, in quali condizioni), rate limit, costo stimato per chiamata. Il registry è il contratto tra l'agente e i sistemi aziendali.

5. Evals automatiche

   Implementare una suite di test automatici che valuta l'agente sul golden set ad ogni modifica del prompt, del modello o dei tool. Scegliere metriche pertinenti al compito: completamento corretto, costo per esito accettato, escalation e, quando la risposta usa fonti, fedeltà a quelle fonti.

6. Red teaming

   Sottoporre l'agente a test adversariali: prompt injection, jailbreak, input fuori dominio, richieste di dati sensibili, tentativi di manipolazione. Il red teaming rivela vulnerabilità che i test funzionali non catturano.

7. Rollout controllato (canary 5-10%)

   Avviare l'agente su un sottoinsieme del traffico reale (5-10%), con human review al 100% nella prima settimana. Confrontare le metriche con il baseline (operatore umano o sistema precedente). Scalare solo se le metriche superano le soglie definite al passo 1.

8. Monitoring + tracing

   Attivare il monitoraggio in tempo reale: latenza per step, costo per conversazione, tasso di errore, distribuzione delle escalation. Ogni conversazione deve essere tracciabile end-to-end per debugging e audit.

9. Retraining / iterazione

   Analizzare i casi di errore con una frequenza adeguata al rischio e ai cambiamenti del sistema e aggiornare il golden set, le istruzioni e le validazioni dei tool. Se è presente una pipeline di recupero delle informazioni, verificare anche le fonti e gli indici effettivamente usati.

10. Cost governance

    Implementare dashboard di costo per agente, per cliente e per caso d'uso. Definire budget ceiling con alert automatici. Ottimizzare: caching delle risposte frequenti, routing verso modelli più economici per task semplici, compressione del contesto per ridurre i token consumati.

Testing ed evals

Un agente AI senza evals automatiche è un sistema non testato. In produzione, "non testato" significa "inaffidabile". Il testing degli agenti richiede metriche specifiche, dataset curati e automazione in CI/CD.

Metriche fondamentali

Costruzione del golden set: copertura prima del numero

Il golden set raccoglie casi con esiti attesi verificabili. Dimensione e composizione dipendono dal processo e dai rischi: un piccolo campione può aiutare a trovare problemi, ma non dimostra da solo l’affidabilità in produzione. Per costruirlo:

• Fonti: ticket reali, chat log, email dei clienti, casi risolti dagli operatori
• Distribuzione: rappresentare il lavoro reale e includere prove separate per errori rari ma gravi. Una ripartizione 60/20/20 tra casi tipici, limite e avversariali è solo un esempio di piano di test, non la distribuzione da assumere in produzione
• Formato: per ogni esempio: input utente, contesto disponibile, output atteso, tool call attese, criteri di valutazione
• Aggiornamento: aggiungere i nuovi errori osservati e riesaminare il set quando cambiano processo, dati, prompt, modello o tool. Una quota mensile fissa non garantisce copertura
• Validazione: ogni esempio deve essere validato da un esperto di dominio (non solo dal team tech)

LLM-as-judge: quando e come ridurre il bias

Usare un LLM per valutare l'output di un altro LLM è potente ma rischioso. Per ridurre il bias:

• Criteri espliciti: fornire al giudice una rubrica con criteri binari o su scala 1-5, non valutazioni soggettive
• Riferimento al ground truth: quando disponibile, il giudice confronta l'output con la risposta attesa, non con la propria "opinione"
• Modello diverso: usare un modello diverso da quello dell'agente come giudice per evitare auto-valutazione favorevole
• Calibrazione: confrontare il giudice con valutazioni umane, esaminare i disaccordi e scegliere la soglia di accettazione in base al rischio del compito, prima di usarlo per decidere sui rilasci

Per approfondire: la guida pratica OpenAI agli agenti descrive modello, tool e istruzioni; le indicazioni OpenAI sulle valutazioni spiegano come scegliere casi pertinenti al compito e calibrare i giudizi automatici con revisioni umane.

Test di regressione in CI/CD

Ogni modifica al prompt, al modello o ai tool deve triggerare automaticamente la suite di evals sul golden set. Se una metrica regredisce oltre la soglia, il deploy viene bloccato. Questo richiede:

• Pipeline CI/CD con step dedicato alle evals (es. GitHub Actions, GitLab CI)
• Soglie definite per ogni metrica (per esempio il TSR non può scendere sotto la soglia fissata al passo 1)
• Report automatico con diff tra la versione corrente e la precedente
• Budget di test: stimare il costo in token delle evals e includerlo nel budget operativo

Guardrail, sicurezza e compliance

Un agente AI in produzione opera con dati reali, interagisce con sistemi aziendali e prende decisioni che hanno impatto su clienti e processi. I guardrail non sono un'opzione: sono un requisito.

Policy engine, allowlist, sandbox

• Policy engine: un layer che intercetta ogni input e output dell'agente e verifica il rispetto delle regole (es. "Non rivelare informazioni di altri clienti", "Non eseguire azioni di cancellazione su database di produzione")
• Allowlist di tool e azioni: l'agente può usare solo i tool esplicitamente registrati. Ogni nuovo tool richiede una review di sicurezza prima dell'attivazione
• Sandbox per esecuzione codice: se l'agente genera o esegue codice, questo deve avvenire in un ambiente isolato con risorse limitate, senza accesso alla rete o al filesystem di produzione
• Simulazione pre-deploy: prima di attivare un nuovo tool o una nuova policy, simulare il comportamento dell'agente su un campione di traffico storico per verificare l'assenza di regressioni

Privacy: PII, retention, logging, access control

La gestione dei dati personali è critica, specialmente in Europa con il GDPR:

• PII detection: filtrare automaticamente i dati personali (nomi, email, numeri di telefono, codici fiscali) dai log e dal contesto inviato al modello
• Data retention: definire policy di retention per le conversazioni (es. 90 giorni per debugging, poi anonimizzazione)
• Logging selettivo: loggare le metriche e le decisioni, non il contenuto integrale delle conversazioni con dati sensibili
• Access control: role-based access ai log, ai dati dell'agente e alle configurazioni. Principio del minimo privilegio

Contromisure al prompt injection

Il prompt injection è il tentativo di far eseguire all'agente istruzioni non autorizzate iniettate nell'input utente. Le contromisure principali sono:

• Separazione dei contesti: system prompt e user input devono essere chiaramente delimitati e il modello deve essere istruito a non eseguire istruzioni nell'user input
• Input sanitization: rilevare pattern di injection noti (es. "Ignora le istruzioni precedenti") e bloccarli prima che raggiungano il modello
• Output validation: verificare che l'output dell'agente sia coerente con le istruzioni del system prompt e non con potenziali istruzioni iniettate
• Least privilege: anche se un injection ha successo, l'agente non ha accesso a tool o dati oltre il necessario

Incident response: playbook, audit trail, kill switch

Tre architetture di riferimento

Ogni agente AI ha un contesto specifico, ma i pattern architetturali si ripetono. Ecco tre architetture di riferimento da adattare al proprio caso.

Architettura A: assistenza clienti (RAG, escalation, controllo qualità)

Architettura B: operations e IT (ticketing e tool calling controllato)

Architettura C: supporto alle vendite (CRM, offerte, conformità)

Quando NON usare un agente

Non tutti i problemi richiedono un agente AI. Prima di investire in un agente, il team di consulenza Niuexa valuta se il caso d'uso giustifica la complessità agenziale. Evitare l'approccio agenziale quando:

• Il task è deterministico: se l'input mappa direttamente a un output senza ragionamento (es. lookup in tabella), un workflow tradizionale è più veloce, affidabile ed economico
• La latenza è critica (< 200ms): ogni chiamata a un LLM aggiunge in genere da qualche centinaio di millisecondi a qualche secondo. Per risposte sotto il secondo servono sistemi a regole o ML tradizionale
• Il volume è altissimo e il valore per interazione è basso: se il costo per token supera il margine generato dall'automazione, l'agente non è sostenibile
• Non esistono dati per valutare la correttezza: senza un golden set e metriche oggettive, non si può sapere se l'agente funziona o no
• Il dominio vieta decisioni algoritmiche opache: in alcuni contesti normativi (credito al consumo, assunzioni), le decisioni devono essere spiegabili e auditabili in modo che un agente LLM non può garantire

Conclusione: checklist finale per agenti AI in produzione

Costruire un agente AI che funziona in produzione non è questione di scegliere il framework giusto o il modello più potente. È questione di integrare tool e practice in un processo ingegneristico ripetibile. Questa checklist riassume i requisiti minimi per il go-live.

Gli agenti AI più affidabili non sono quelli con il modello più potente, ma quelli con il processo di ingegneria più maturo: evals solide, guardrail rigorosi, osservabilità completa e un team che torna ogni settimana sui failure modes.

Articoli correlati