Tool e practice per creare agenti AI: la guida Niuexa per progettare, testare e mettere in produzione agenti affidabili

Introduzione — Perché "tool" senza "practice" produce agenti fragili

Ogni settimana viene pubblicato un nuovo framework per costruire agenti AI. La demo funziona in 10 minuti, il tweet raccoglie migliaia di like, e il giorno dopo qualcuno prova a metterlo in produzione. Risultato: allucinazioni, costi fuori controllo, escalation manuali che annullano il valore dell'automazione.

"Un agente AI che funziona in demo e fallisce in produzione non è un problema di modello. È un problema di engineering: mancano i test, i guardrail, le metriche e il processo che trasformano un prototipo in un sistema affidabile."

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 tecnologico di un agente AI in produzione si compone di quattro livelli: il modello di linguaggio, il framework di orchestrazione, il pipeline RAG e i tool di produzione. Scegliere il componente sbagliato in uno qualsiasi di questi livelli compromette l'intero sistema.

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 tra 1$ e 15$ per milione di token input determina 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)

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.

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: conoscenza persistente tra sessioni, tipicamente un vector DB (Pinecone, Weaviate, Qdrant, pgvector) con embedding del contenuto aziendale
• Working memory: lo stato intermedio dell'esecuzione corrente — quali tool sono stati chiamati, quali risultati ottenuti, quali sotto-task completati

Il pipeline RAG (Retrieval-Augmented Generation) collega il modello alla conoscenza aziendale. I componenti critici sono: chunking strategy (dimensione e overlap dei frammenti), embedding model (trade-off qualità/costo), retrieval strategy (similarity search, hybrid search, re-ranking), e prompt di contesto che integra i risultati del retrieval nell'istruzione al modello.

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, Helicone — tracciamento di 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)

Practice fondamentali — Progettare prima di codificare

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

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 nel prompt non può diventare un test automatico, non è una regola: è una speranza. In produzione, le speranze non scalano."

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

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

Workflow Niuexa — Da idea a 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 (es. "Risolvere il 70% dei ticket L1 entro 5 minuti"). Mappare i failure modes: cosa succede se l'agente 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 reali (50-200)

   Raccogliere 50-200 esempi reali dal dominio: input utente, output atteso, edge case, casi di errore. Questo dataset diventa il golden set per le evals. Senza dati reali, si costruisce sull'intuizione invece che sull'evidenza.

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. Le metriche minime sono: Task Success Rate, Groundedness, Cost per Resolution, Escalation Rate.

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 settimanalmente i casi di errore e aggiornare: il golden set (aggiungendo i nuovi edge case), il prompt (raffinando le istruzioni), i tool (correggendo bug o migliorando le validazioni), il retrieval (aggiungendo o aggiornando documenti nel vector DB).

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 (50-200 esempi)

Il golden set è il cuore del sistema di evals. Per costruirlo efficacemente:

• Fonti: ticket reali, chat log, email dei clienti, casi risolti dagli operatori
• Distribuzione: 60% casi tipici, 20% edge case, 20% casi di errore o adversariali
• Formato: per ogni esempio: input utente, contesto disponibile, output atteso, tool call attese, criteri di valutazione
• Aggiornamento: aggiungere 10-20 nuovi esempi al mese dai casi di errore in produzione
• 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: validare il giudice su un campione con valutazioni umane e misurare l'accordo (Cohen's kappa > 0.7)

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 (es. TSR non può scendere sotto 85%)
• 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

Blueprint — 3 architetture pronte

Ogni agente AI ha un contesto specifico, ma i pattern architetturali sono ricorrenti. Presentiamo tre blueprint pronti per la produzione, validati su progetti reali Niuexa.

Blueprint A: Customer Support (RAG + escalation + quality)

Blueprint B: Operations/IT (ticketing + tool-calling controllato)

Blueprint C: Sales Enablement (CRM + quoting + compliance)

Quando NON usare un agente

Non tutti i problemi richiedono un agente AI. 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 LLM call aggiunge 1-5 secondi. Per risposte sub-secondo, servono sistemi rule-based 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 migliori non sono quelli con il modello più potente. Sono quelli con il processo di engineering più maturo: evals solide, guardrail rigorosi, osservabilità completa e un team che itera ogni settimana sui failure modes."

Articoli Correlati