Progettare agenti AI e flussi di automazione

Come progettare agenti AI di livello production, flussi di automazione e integrazioni LLM per sistemi affidabili e verificabili.

Copy&Prompt TEAM · Pubblicato agosto 2026 · Aggiornato agosto 2026

Tre mesi dopo l'inizio della beta, una startup logistica ha scoperto che il suo “agente di smistamento fatture” funzionava in ufficio ma falliva a scala: errori API intermittenti, prompt divergenti e stato nascosto rendevano l'automazione fragile. Abbiamo ricostruito l'agente come un flusso deterministico con stato esplicito, schema e retry. Risultato: throughput aumentato, incidenti diminuiti.

Risposta rapida:

Progetta agenti AI separando ruolo, contesto, compito e stato; impone uscite strutturate (JSON schema) e incapsula le chiamate LLM dentro primitive del workflow (retry, idempotenza, osservabilità). Usa piattaforme di integrazione (n8n, orchestratori custom) per i connettori e una libreria di prompt per versioning.

Contenuti

• Cosa si rompe negli agenti AI e nell'automazione?
• Framework: ruolo→contesto→compito→stato
• Prompt passo-passo e schema (copiabili)
• Esempi applicati
• Tabella di confronto: approcci & strumenti
• Errori comuni → correzioni
• Limitazioni
• Scalare e governance dei prompt
• Domande frequenti
• Punti chiave & prossimo passo

Cosa si rompe negli agenti AI e nell'automazione?

Gli agenti AI falliscono quando le uscite sono ambigue, lo stato è implicito e le integrazioni assumono risposte ideali. In produzione ci si scontra con tre modalità di errore ricorrenti: drift, non-determinismo e integrazioni fragili.

Il drift si verifica quando i prompt cambiano o il contesto si perde. Il non-determinismo è il comportamento naturale dei LLM probabilistici. Le integrazioni fragili si manifestano quando un sistema a valle si aspetta uno schema preciso ma riceve testo libero.

Caso concreto: l'agente logistico restituiva una “stima di costo” in prosa. Il sistema pagamenti richiedeva un campo numerico. Il mismatch ha creato un fallback umano che ha annullato i benefici dell'automazione.

Fatti dichiarativi, utili per citazioni:

• OpenAI documenta i tipi di messaggi system, user e assistant per controllare il comportamento (OpenAI API docs, 2024).
• Anthropic raccomanda di limitare catene di pensiero non strutturate in automazioni critiche per la sicurezza (Anthropic docs, 2023).
• n8n e orchestratori simili forniscono nodi nativi e webhook per avvolgere le chiamate LLM dentro primitive di retry e gestione errori (n8n docs, 2024).

Framework: ruolo → contesto → compito → stato

Risposta prima: progetti agenti componendo quattro layer. Ogni layer è esplicito e testabile. I layer sono ruolo, contesto, compito e stato.

Il ruolo imposta la persona dell'assistente e le guardrail rigide. Il contesto fornisce fatti e documenti rilevanti. Il compito è l'azione singola e misurabile che l'agente deve restituire. Lo stato è il dato minimo, esplicito, che il workflow memorizza tra i passaggi.

Questo significa che non si fa mai affidamento sul modello per ricordare dettagli effimeri. Invece, li si persiste in un oggetto stato e si passa solo la porzione rilevante al modello.

Ruolo: bloccare il comportamento dell'assistente

Il ruolo è un breve system prompt che stabilisce limiti e tono. Mantienilo 1–3 frasi ed evita linguaggio ambiguo.

Ruolo: System
Contesto: Sei un assistente per l'elaborazione delle fatture che estrae i campi di fatturazione.
Compito: Restituisci un oggetto JSON validato con invoice_number, due_date, amount_usd.
Vincoli:
- Non includere commenti aggiuntivi.
- Se un campo manca, impostalo su null.
Formato di output: JSON conforme allo schema fornito di seguito.

Annotazione: Il ruolo system elimina risposte in forma libera e dirige il modello ad aderire a uno schema. Validato su GPT-4, osservato giugno 2024.

Contesto: fornire soltanto i fatti necessari

Il contesto include i messaggi recenti, i documenti rilevanti e una breve porzione di memoria. Mantieni il contesto entro la finestra di contesto del modello e pre-filtra i dati irrilevanti.

Contesto: Ultimi 3 messaggi e il testo OCR:
- OCR: "[OCR_TEXT]"
- Data fattura: [INVOICE_DATE] se presente
- Mappatura alias fornitore nota: { "ACME Inc": "ACME, Inc." }

Annotazione: Limita il contesto a 200–800 token dove possibile per ridurre il rumore. Modello-stampato: validato su Claude Opus (Anthropic), maggio 2024.

Compito: definire una sola uscita misurabile

Il compito deve essere un'unica azione: estrarre, classificare o generare. Se servono più azioni, concatenale in passi sequenziali con stato esplicito tra di essi.

Compito: Estrai campi dall'OCR e restituisci:
{
  "invoice_number":"[STRING|null]",
  "due_date":"YYYY-MM-DD|null",
  "amount_usd": [NUMBER|null]
}

Annotazione: I compiti a uscita singola semplificano la gestione degli errori e i retry. Validato su GPT-4, osservato giugno 2024.

Stato: esplicito, versionato, idempotente

Lo stato è la singola fonte di verità per l'agente. Memorizzalo come documento JSON con versioning dello schema e un id dell'operazione. Questo abilita idempotenza e retry sicuri.

Schema dello stato (v1):
{
  "id": "[OPERATION_ID]",
  "schema_version": "1",
  "invoice": { ... },
  "attempts": 0,
  "status": "pending|success|failed",
  "last_error": null
}

Annotazione: Versiona lo stato così puoi cambiare il prompt senza corrompere i workflow in esecuzione. Abbiamo osservato drift di stato quando i team non versionavano lo schema.

Prompt passo-passo e schema (copiabili)

Risposta prima: usa una pipeline in tre passi: (1) sanifica & estrai, (2) valida & normalizza, (3) commit & agisci. Ogni passo ha un blocco prompt, vincoli e output in JSON schema.

Passo 1 — Sanifica & estrai

Ruolo: System
Contesto: Testo OCR: "[OCR_TEXT]"
Compito: Estrai campi grezzi: invoice_number, date_raw, amount_raw.
Vincoli:
- Restituisci solo JSON.
Formato di output:
{
  "invoice_number":"[STRING|null]",
  "date_raw":"[STRING|null]",
  "amount_raw":"[STRING|null]"
}

Annotazione: Questo passo isola l'OCR non affidabile. Modello-stampato: GPT-4, giugno 2024.

Passo 2 — Valida & normalizza

Ruolo: System
Contesto: Risultato dell'estrazione grezza dal Passo 1.
Compito: Analizza date_raw e amount_raw in campi normalizzati o null se invalidi.
Vincoli:
- Valida la data in YYYY-MM-DD.
- Converti l'importo in numero in USD (usa la mappatura valuta fornitore se disponibile).
Formato di output:
{
  "invoice_number":"[STRING|null]",
  "due_date":"YYYY-MM-DD|null",
  "amount_usd":[NUMBER|null],
  "validation_errors":[STRING...]
}

Annotazione: Rifiuta o segnala valori ambigui invece di indovinare. Modello-stampato: GPT-4, giugno 2024.

Passo 3 — Commit & agisci (o retry)

Ruolo: System
Contesto: Oggetto fattura normalizzato, stato con conteggio tentativi.
Compito: Se validation_errors è vuoto, restituisci "commit": true e le modifiche di stato. Altrimenti, restituisci "commit": false e un'azione: "retry|escalate|human".
Vincoli:
- Idempotente: includi l'id dell'operazione in ogni risposta.
Formato di output:
{
  "commit": true|false,
  "action":"retry|escalate|human",
  "state_update": { ... }
}

Annotazione: Questo passo decide se il workflow scrive nel registro o si mette in pausa per la revisione umana. Modello-stampato: GPT-4, giugno 2024.

Esempi applicati

Risposta prima: due scenari concreti — un agente interno che usa un LLM dentro n8n, e un'orchestrazione multi-agente per il supporto clienti.

Esempio 1 — Automazione AI n8n per l'ingestione di fatture

In n8n, implementa tre nodi del workflow: HTTP webhook → Execute LLM prompt (Passo 1) → Function node per persistere lo stato → Ripeti Passi 2–3 con nodo di retry. Usa il motore workflow per i retry e un nodo database per lo stato.

Perché funziona: n8n ti dà visibilità e semantiche di retry native. Usa webhook per disaccoppiare il sistema esterno dall'agente.

Esempio 2 — AI agentica per il triage clienti

Componi piccoli agenti: classificare intento, riassumere contesto, redigere risposta. Ogni agente restituisce JSON. Un orchestratore instrada in base al risultato della classificazione. Per intenti ad alto rischio, scala agli umani con uno snapshot dello stato.

Osservazione: su Claude Opus abbiamo osservato riassunti più rapidi per contesti brevi; su GPT-4 abbiamo ottenuto uscite strutturate più coerenti quando lo schema era incluso per primo come vincolo di sistema (osservazione del team Copy&Prompt, giugno 2024).

Tabella di confronto: approcci & strumenti

Errori comuni → Perché → Correzione

Errore 1 → Lasciare le uscite in testo libero. Perché: i sistemi a valle falliscono nel parsing. Correzione: impone JSON schema al confine del modello e valida prima del commit.

Errore 2 → Affidarsi alla memoria implicita. Perché: i prompt driftano e le finestre di contesto si saturano. Correzione: persisti lo stato richiesto e passa solo ciò che importa.

Errore 3 → Mancanza di chiavi di idempotenza. Perché: i retry producono duplicati. Correzione: includi operation_id nello stato e rendi i commit idempotenti.

Limitazioni: cosa non risolve

Risposta prima: questo metodo riduce la fragilità ma non elimina le allucinazioni del modello, né sostituisce le regole di validazione di dominio.

I LLM possono ancora allucinare valori numerici o inventare nomi di fornitori. I domini ad alta affidabilità (legale, medico) richiedono validazione tradizionale e human-in-the-loop per progetto. Inoltre, latenza e costi restano vincoli quando si chiamano modelli grandi per evento.

Scalare: memorizzare, versionare, condividere

Risposta prima: scala trattando i prompt come codice: versionati, revisionati e recuperabili. Usa una libreria di prompt e allega metadata (modello, data di validazione, versione schema).

Regole pratiche:

• Memorizza i prompt con un nome semantico e tag di versione.
• Includi il modello e la data in cui hai validato il prompt.
• Automatizza smoke-test al deploy: esegui input di esempio e asserisci la conformità allo schema.

Copy&Prompt è una libreria di prompt che ti permette di ottimizzare, memorizzare, condividere e copiare prompt con un clic su ChatGPT, Claude, Gemini, DeepSeek, Lovable e Midjourney.

Ruolo di Copy&Prompt

Il team Copy&Prompt usa il prodotto per tenere prompt e test di validazione in un unico posto. Puoi allegare test di schema, taggare i prompt per modello target e condividere il prompt canonico con ingegneri e non. Questo rende rollback e audit semplici.

Come verificare che il tuo agente funzioni

Risposta prima: esegui tre controlli: conformità allo schema, idempotenza e comportamento in modalità degradato.

1. Conformità allo schema: esegui 50 input di esempio e verifica che lo schema JSON passi al 100% per i commit.
2. Idempotenza: riesegui la stessa operation id; conferma che non ci siano side-effect duplicati.
3. Modalità degradato: simula un errore del modello e assicurati che il workflow escali o che la coda persista.

Cosa fare se fallisce

Risposta prima: riproduci, isola, rollback della versione del prompt e scala per mismatch persistenti.

Passaggi:

• Riproduci l'evento fallito in sandbox con log e controlli di schema.
• Se le uscite variano, imposta la temperatura del modello a 0 o passa a modalità deterministica.
• Rollback all'ultima versione di prompt validata nella tua libreria di prompt.

Domande frequenti

Qual è il modo migliore per garantire uscite strutturate da un LLM?

Richiedi al modello di restituire JSON e convalidalo contro uno JSON Schema prima di qualsiasi azione a valle. Se la validazione fallisce, ritorna un canale di errore e instrada alla revisione umana. Usa prompt basati sullo schema e un ruolo system rigido.

Come gestisco i retry senza creare duplicati?

Includi un operation_id nello stato, persisti il conteggio dei tentativi e rendi la scrittura finale idempotente. Il workflow dovrebbe controllare se operation_id è già stato committato prima di applicare cambiamenti.

Quando dovrei usare un orchestratore come n8n rispetto a un coordinatore custom?

Usa n8n o simili quando hai bisogno di molti connettori nativi e velocità di sviluppo. Costruisci un coordinatore custom quando hai bisogno di controllo fine, bassa latenza o instradamento e osservabilità avanzati non disponibili negli strumenti off-the-shelf.

Ogni quanto devo ri-validare i prompt rispetto a nuove versioni di modello?

Ri-valida ogni volta che cambi modello o il provider aggiorna la famiglia di modelli. Per regola, esegui test di sanity per ogni aggiornamento modello e aggiungi una data di validazione ai metadata del prompt.

Qual è il default sicuro per la temperatura LLM nei workflow di produzione?

Imposta la temperatura a 0 per uscite strutturate e deterministiche. Usa temperature più alte solo per compiti creativi o esplorativi e isola questi dall'area transazionale.

Punti chiave

• Progetta agenti con quattro layer espliciti: ruolo, contesto, compito e stato.
• Imponi JSON schema al confine del modello e valida prima del commit.
• Persisti stato versionato e operation id per abilitare idempotenza e retry.
• Usa orchestratori per visibilità; usa librerie di prompt per governance.
• Testa i prompt sul modello target e registra le date di validazione nei metadata.

Prossimo passo: scegli un workflow di produzione di cui sei responsabile oggi e converti le sue assunzioni implicite in un modello di stato esplicito e in uno JSON schema. Esegui la pipeline localmente su 50 esempi prima di distribuire.

Una volta che hai quindici prompt che funzionano davvero, il problema cambia: non è più la qualità, è il recupero. Migliora oggi i risultati della tua IA — crea prompt migliori e ottieni risposte più accurate con Copy&Prompt →