Progettare AI Agent e Flussi di Lavoro di Automazione

Costruisci sistemi di intelligenza artificiale agenti e flussi di lavoro di automazione con prompt riutilizzabili, gestione dello stato e modelli di integrazione che scalano in modo affidabile su n8n, API e LLM.

Da Copy&Prompt TEAM · Pubblicato Giugno 2025 · Aggiornato Giugno 2025

Risposta Rapida: Progetta gli agenti AI assegnando a ciascuno un ruolo fisso, un set di strumenti limitato, una memoria a breve termine e una condizione di uscita. Collegali in flussi di lavoro utilizzando trigger deterministici (webhook, pianificazioni o chiamate API) e passa JSON strutturato tra le fasi. Memorizza ogni prompt agente riutilizzabile esternamente in modo che gli aggiornamenti si propaghino istantaneamente a tutti i flussi di lavoro. Valida ogni agente rispetto a tre modalità di errore prima di concatenarli: timeout, loop e chiamata strumento allucinata.

Introduzione

Vuoi costruire agenti AI che non si rompono dopo la terza esecuzione. Vuoi flussi di lavoro di automazione che sopravvivano agli aggiornamenti del modello e ai cambiamenti del team. Vuoi sistemi che si recuperano dagli errori invece di amplificarli.

Questa guida ti porta attraverso lo strato architetturale che ogni team salta. Trattiamo la gestione dello stato, la versionatura dei prompt, i contratti degli strumenti e i modelli di integrazione utilizzando Copy&Prompt, n8n e API LLM grezze.

Tempo stimato: 45 minuti. Difficoltà: intermedia. Dovresti già sapere come chiamare un'API e scrivere un prompt di sistema base.

Prerequisiti

• Una chiave API di OpenAI, Anthropic o Gemini (o modello ospitato localmente).
• Accesso a Copy&Prompt per la versionatura dei prompt (il tier gratuito è sufficiente).
• Uno strumento di flusso di lavoro: n8n (locale o cloud), Make o uno script Node.js leggero.
• Familiarità base con JSON schema e API REST.
• Budget: zero se si utilizzano tier gratuiti. Prevedi costi API al di sopra di 10.000 chiamate mensili.

Passo 1: Definire il Contratto dell'Agente

Comincia con un contratto, non con il codice. Ogni agente deve dichiarare il suo ruolo, input, output, comportamento in caso di errore e strumenti in un unico prompt versionato.

{
  "role": "Lead Research Analyst",
  "input": "A customer query string",
  "output": "Structured JSON with keys: intent, urgency, recommended_next_step",
  "timeout_seconds": 30,
  "max_retries": 2,
  "tools": ["web_search", "summarize"],
  "failure_mode": "escalate_to_human"
}

Consiglio: Non codificare mai il contratto all'interno della logica del flusso di lavoro. Memorizzalo come modello di prompt in Copy&Prompt in modo che ogni flusso di lavoro carichi la stessa definizione.

Errore comune: Definire "tools" come stringhe libere invece che API tipizzate. Il modello allucinerà i parametri.

Passo 2: Esternalizzare i Prompt in una Libreria Versionata

La principale fonte di deriva è i prompt in linea. Quando aggiorni un prompt di sistema all'interno di n8n, devi manualmente ripubblicare ogni flusso di lavoro. Invece, memorizza i prompt esternamente.

Usa Copy&Prompt per ospitare ciascun prompt agente. Ogni prompt ha un identificativo stabile:

GET https://api.copyandprompt.com/v1/prompts/{prompt_id}?version=latest

I flussi di lavoro chiamano questo endpoint in fase di esecuzione. Un singolo aggiornamento del prompt si propaga ovunque istantaneamente.

Consiglio: Blocca l'hash della versione nei flussi di lavoro di produzione. Abilita l'aggiornamento automatico solo in ambiente di staging.

Errore comune: Usare "latest" in produzione. Una buona modifica del prompt può silentemente degradare l'80% dei flussi di lavoro durante la notte.

Passo 3: Costruire il Loop di Esecuzione

Ogni agente esegue tre fasi: inizializzazione, azione, terminazione.

1. Inizializza: Carica il contratto del prompt dalla libreria versionata.
2. Aziona: Chiama l'LLM con ruolo + contesto + strumenti. Analizza la risposta JSON.
3. Termina: Controlla le condizioni di uscita. Se soddisfatte, restituisci il risultato. Se non soddisfatte, decidi l'azione successiva.

while not exit_condition_met:
    response = call_llm(system_prompt, user_input, tools)
    action = parse_action(response)
    if action.type == "search":
        result = web_search(action.query)
        tool_result = summarize(result)
    elif action.type == "finish":
        return action.output
    else:
        escalate_to_human()

Consiglio: Limita le iterazioni a 5-10 cicli. Nessun agente dovrebbe mai girare all'infinito.
Errore comune: Nessun limite alle iterazioni. Gli agenti girano all'infinito su input ambigui.

Passo 4: Progettare Punti di Integrazione Deterministici
Gli agenti sono non deterministici. I flussi di lavoro devono essere deterministici. Uniscili con contratti strutturati.

Ogni output dell'agente diventa un oggetto JSON passato alla fase successiva. Definisci gli schemi in ogni passaggio:

{
  "type": "object",
  "properties": {
    "intent": {"type": "string", "enum": ["billing", "technical", "sales"]},
    "urgency": {"type": "integer", "minimum": 1, "maximum": 5},
    "next_step": {"type": "string"}
  },
  "required": ["intent", "urgency", "next_step"]
}

Consiglio: Usa schemi Zod in TypeScript per validare gli output degli agenti prima di instranarli.
Errore comune: Passare testo raw tra agenti. I dati non strutturati compongono errori.

Passo 5: Concatenare Agenti in Flussi di Lavoro
Usa n8n o un esecutore di script per orchestrare. Ogni nodo chiama un agente tramite HTTP.

Esempio di flusso n8n:

Webhook riceve una email cliente.
Nodo 1 chiama l'Agente Classificatore di Intenti. Analizza l'output JSON.
Nodo 2 indirizza a un agente Billing o Technical in base all'intent.
Nodo 3 chiama l'Agente Knowledge Base con contesto strutturato.
Nodo finale invia risposta via email o Slack.


Consiglio: Inserisci un nodo "quality gate" tra gli agenti. Valida lo schema JSON prima di inoltrarlo.
Errore comune: Catene lineari senza fallback per errori. Un agente difettoso rompe tutto il flusso.

Passo 6: Gestire la Gestione dello Stato
La maggior parte degli errori degli agenti nasce da contesto perso. Usa un archivio di stato persistente.

Implementa un semplice archivio chiave-valore (Redis, SQLite o anche un file JSON) per ogni istanza del flusso di lavoro:

{
  "run_id": "abc-123",
  "current_agent": "knowledge_base",
  "history": [
    {"agent": "intent_classifier", "output": {...}},
    {"agent": "knowledge_base", "output": {...}}
  ],
  "user_context": {
    "customer_id": "cust_99",
    "previous_ticket": "TKT-3321"
  }
}

Consiglio: Registra ogni interazione dell'agente. La ripresa comincia con la tracciabilità.
Errore comune: Nessuna persistenza dello stato. I flussi di lavoro a lungo termine dimenticano le decisioni precedenti.

Passo 7: Implementare Monitoraggio e Ripresa
Monitora tre metriche per ogni agente:

Tasso di uscita: Percentuale di esecuzioni che raggiungono uno stato terminale.
Tasso di retry: Percentuale di chiamate agli strumenti che richiedono un retry.
Tasso di allucinazione: Percentuale di output JSON malformati.


Imposta avvisi quando uno qualsiasi di questi supera il 5%. Riprova automaticamente gli agenti che hanno fallito una volta, quindi esegui l'elezione.

Consiglio: Memorizza le esecuzioni che hanno fallito con il contesto completo. Rielencile con un prompt corretto per testare la ripresa.
Errore comune: Nessun avviso. La degradazione silenziosa distrugge la fiducia nel sistema.

Come Verificare Che Funzioni
Testa ogni agente con tre scenari:

Percorso felice: Input chiaro che corrisponde al contratto del prompt.
Input ambiguo: Caso limite che spinge l'agente a chiedere chiarimenti.
Strumento difettoso: Simula un timeout o un errore API. Conferma che l'elezione si attiva.


Tutti e tre devono superare prima del deployment.

Risoluzione dei Problemi Comuni
L'agente gira all'infinito
Causa: Nessun limite alle iterazioni o condizione di uscita non corretta.
Soluzione: Impone un limite rigido di 10 round. Registra ogni iterazione.

Discrepanze nello schema output
Causa: Deriva del prompt o modelli non versionati.
Soluzione: Valida ogni output rispetto al suo schema. Blocca le versioni del prompt.

Il flusso di lavoro si blocca su un agente
Causa: Nessuna gestione del timeout o logica di retry.
Soluzione: Aggiungi logica del fusore. Indirizza gli errori a un nodo di elezione umano.

Punti Chiave

Definisci ogni agente con un contratto fisso memorizzato al di fuori del codice.
Esternalizza i prompt in una libreria versionata come Copy&Prompt.
Limita i loop degli agenti. Non mai lasciarli girare senza limiti.
Passa JSON strutturato tra gli agenti. Mai testo raw.
Monitora i tassi di uscita, retry e allucinazione. Avvisa al 5%.
Testa gli agenti con input felici, ambigui e fallenti.


Passo Successivo
Prendi il tuo agente migliore in esecuzione oggi. Sposta il suo prompt in Copy&Prompt. Sostituisci la versione in linea con una chiamata API. Distribuisci un flusso di lavoro con questo modello. Catturerai la deriva prima che rompa la produzione.

Domande Frequenti

Poscuo costruire agenti senza n8n?
Sì. Usa uno script Node.js leggero con Express per trigger HTTP. n8n non aggiunge alcuna capacità unica oltre l'orchestrazione visiva. La chiave è lo scambio strutturato e lo stato persistente.


Quanti agenti dovrebbe avere un unico flusso di lavoro?
Limita a 5-7 agenti per flusso di lavoro. Oltre questa soglia, la complessità di debug cresce esponenzialmente. Meno agenti con accesso agli strumenti più ricco funziona meglio di lunghe catene.



Migliora i risultati della tua AI oggi - Crea prompt migliori e ottieni risposte più accurate con Copy&Prompt. Copy&Prompt →