🇮🇹 IT

🤖 Agent

Il nodo più potente di Flusso. Il nodo Agent invia un prompt a un modello linguistico di grandi dimensioni e ne restituisce la risposta. Supporta l'iniezione di contesto RAG, l'uso di strumenti tramite MCP, la memoria persistente, l'output JSON strutturato e la validazione dello schema — rendendolo la base di quasi tutti i workflow basati su AI.

Categoria: AI & Agenti · Identificatore tipo: agent

Panoramica

Alla base, il nodo Agent prende un prompt, lo invia a un modello AI configurato e restituisce la risposta del modello come output utilizzabile negli step successivi. Tuttavia, ci sono molte funzionalità aggiuntive che puoi sovrapporre a questo flusso di base:

Contesto RAG — inietta automaticamente estratti di documenti rilevanti da una Knowledge Base in modo che il modello possa rispondere a domande sui tuoi dati privati.
Memoria — mantiene una cronologia della conversazione tra più esecuzioni del workflow, permettendo all'agente di ricordare ciò che è stato detto nelle sessioni precedenti.
Strumenti (MCP) — in modalità grafo, collega nodi MCP Tool in modo che l'agente possa chiamare servizi esterni, API e script come parte del suo ciclo di ragionamento.
Modalità JSON + Schema — forza il modello a produrre JSON strutturato e lo valida rispetto a uno schema definito, così gli step successivi ricevono sempre dati con una struttura affidabile.

Il nodo Agent opera in due modalità. In modalità lineare, configuri il provider, il modello, la memoria e gli strumenti direttamente nel pannello delle impostazioni del nodo. In modalità grafo, colleghi nodi separati Model Config, Memory e MCP Tool alle porte di input tipizzate dell'agente, ottenendo un'immagine visiva chiara di come l'agente è assemblato.

Configurazione

Campo	Stato	Descrizione
Provider	Obbligatorio (lineare)	Il Provider AI da utilizzare. In modalità grafo, collega invece un nodo Model Config alla porta `model_in`.
Model	Obbligatorio	L'identificatore del modello, ad esempio `gpt-4o`, `claude-sonnet-4-6` o `llama3.2`. Deve essere un modello disponibile tramite il provider selezionato.
System Prompt	Opzionale	Istruzioni che definiscono il comportamento, la persona, i vincoli o il formato di output dell'agente. Questo testo viene inviato come ruolo di sistema prima del messaggio utente. Supporta riferimenti `{{ variable }}`.
User Prompt	Obbligatorio	Il messaggio di input su cui l'agente deve agire. Questo è il testo principale che il modello vede e a cui risponde. Supporta riferimenti `{{ variable }}` — tipicamente popolato con dati da uno step precedente o dal payload del trigger.
Temperature	Opzionale	Controlla quanto casuali o creative sono le risposte del modello. L'intervallo è 0–2. Un valore di `0` produce output altamente deterministico e coerente. Un valore di `0.7` (il valore predefinito) offre un mix equilibrato. Valori superiori a `1.0` producono risposte più variegate e creative.
Max Tokens	Opzionale	La lunghezza massima della risposta del modello, misurata in token (circa ¾ di una parola ciascuno). Lascia vuoto per usare il valore predefinito del modello. Imposta un limite se hai bisogno di risposte brevi e concise o stai gestendo i costi delle API.
JSON Mode	Opzionale	Quando abilitato, istruisce il modello a produrre solo JSON valido. La risposta viene automaticamente analizzata e resa disponibile come `output.json`. Usa questa opzione insieme al campo Output Schema per imporre una struttura specifica.
Output Schema	Opzionale	Un oggetto JSON Schema che definisce la struttura attesa dell'output JSON del modello. Flusso valida la risposta rispetto a questo schema dopo averla ricevuta. Se la validazione fallisce, lo step viene contrassegnato come fallito.
Context Sources	Opzionale	Seleziona uno o più step RAG precedenti nel workflow. Flusso antepone automaticamente gli estratti dei documenti recuperati da quegli step al contesto dell'agente prima di inviare il prompt. Il modo più diretto per dare all'agente accesso alla tua knowledge base.
History Source	Opzionale	Seleziona uno step precedente il cui output contiene la cronologia della conversazione da iniettare nel contesto di questo agente. Utile quando si passa la cronologia tra step manualmente.
Max History Turns	Opzionale	Il numero di turni di conversazione passati da leggere dal Memory Provider collegato e iniettare nel prompt. L'intervallo è 1–50. Il valore predefinito è 10. I turni più vecchi oltre questo limite vengono eliminati.
Memory Provider	Opzionale (lineare)	Seleziona un Memory Provider configurato nelle Impostazioni per abilitare la memoria persistente tra le esecuzioni. In modalità grafo, collega invece un nodo Memory alla porta `memory_in`.
Tools	Opzionale (lineare)	In modalità lineare, seleziona le definizioni MCP Tool da rendere disponibili a questo agente. In modalità grafo, collega invece i nodi MCP Tool alla porta `tool_in`.
Mode	Opzionale	`single` — il modello produce una risposta e lo step si completa. `graph` — l'agente entra in un ciclo di chiamata strumenti, invocando gli strumenti necessari fino a produrre una risposta finale.

Dati di Output

Il nodo Agent produce i seguenti campi di output, accessibili in qualsiasi step successivo tramite riferimenti a variabili:

Campo	Tipo	Descrizione
`text`	string	La risposta testuale grezza dal modello. Sempre presente.
`json`	object	L'oggetto JSON analizzato. Presente solo quando la modalità JSON è abilitata e il modello restituisce JSON valido.
`usage.input_tokens`	number	Numero di token consumati dal prompt (inclusi system prompt e contesto).
`usage.output_tokens`	number	Numero di token nella risposta del modello.
`tool_calls`	array	Dettagli delle chiamate a strumenti effettuate dall'agente. Presente solo quando gli strumenti sono collegati e l'agente li ha utilizzati.

// Riferimento alla risposta testuale dell'agente {{ my_agent.output.text }} // Riferimento a un campo da una risposta in modalità JSON {{ my_agent.output.json.customer_name }} {{ my_agent.output.json.total_amount }} // Verifica dell'utilizzo dei token {{ my_agent.output.usage.input_tokens }} {{ my_agent.output.usage.output_tokens }}

Esempio di Utilizzo

Agente di risposta con RAG di base

Questo esempio costruisce un agente di supporto clienti che risponde alle domande sul tuo prodotto utilizzando una knowledge base. La domanda dell'utente arriva tramite un webhook trigger.

Aggiungi un nodo RAG prima dell'Agent. Imposta la Knowledge Base sulla documentazione del tuo prodotto. Imposta Query su {{ trigger.output.question }}. Imposta Limit a 5 e lascia Threshold al valore predefinito 0.7.
Aggiungi un nodo Agent. Imposta Provider e Model. Nel System Prompt, definisci la persona:
You are a helpful customer support agent for Acme Corp. Answer the user's question clearly and concisely. Use only the provided context. If the answer is not in the context, say so.
Imposta lo User Prompt.
{{ trigger.output.question }}
Aggiungi lo step RAG alle Context Sources. Seleziona lo step RAG dal menu a tendina Context Sources. Flusso inietterà automaticamente gli estratti recuperati nel contesto dell'agente.
Usa la risposta in uno step successivo. Fai riferimento a {{ my_agent.output.text }} in un nodo Webhook Response per inviare la risposta al chiamante.

Estrazione dati strutturati con modalità JSON

Questo esempio estrae un riepilogo strutturato da un articolo lungo. L'agente è forzato a restituire JSON conforme a uno schema definito.

// System Prompt Extract a structured summary from the provided article. Return only valid JSON matching the schema exactly. // User Prompt Article: {{ fetch_article.output.body }} // Output Schema (incolla nel campo Output Schema come JSON) { "type": "object", "properties": { "title": { "type": "string" }, "summary": { "type": "string" }, "topics": { "type": "array", "items": { "type": "string" } }, "sentiment": { "type": "string", "enum": ["positive", "neutral", "negative"] } }, "required": ["title", "summary", "topics", "sentiment"] } // Accesso al risultato in uno step successivo {{ summarise.output.json.title }} {{ summarise.output.json.topics }}

Suggerimenti & Note

Guida alla temperatura. Usa 0.0–0.3 per attività che richiedono output coerente e fattuale (estrazione dati, classificazione, sintesi). Usa 0.7 per assistenti generici. Usa 1.0+ solo per scrittura creativa o brainstorming dove la varietà è desiderabile.
Usa sempre JSON Mode con un Output Schema. La modalità JSON da sola dice al modello di produrre JSON, ma non garantisce le chiavi o la struttura di cui hai bisogno. Aggiungere uno schema intercetta le risposte malformate prima che causino errori negli step successivi.
Context Sources vs. iniezione manuale. L'uso delle Context Sources è l'approccio raccomandato per il RAG perché Flusso gestisce automaticamente la formattazione e il budget dei token. Inietta il contesto manualmente tramite lo User Prompt solo se hai bisogno di un controllo preciso su come il contesto viene presentato.
Memoria in modalità lineare. Quando usi un Memory Provider in modalità lineare, ogni esecuzione legge i turni precedenti e scrive il nuovo turno automaticamente. Imposta Max History Turns con attenzione — iniettare troppi turni aumenta la lunghezza del prompt e i costi delle API.
La modalità grafo richiede un nodo Model Config. In modalità grafo, ogni nodo Agent deve avere esattamente un nodo Model Config collegato alla sua porta model_in. Il workflow fallirà la validazione pre-esecuzione se questa connessione manca.

Nodi Correlati

Model Config — specifica il modello AI per un nodo Agent in modalità grafo.
Memory — collega un backend di memoria a un nodo Agent in modalità grafo.
MCP Tool — definisce uno strumento esterno che l'agente può chiamare in modalità grafo.
RAG — nodo di ricerca semantica i cui risultati possono essere iniettati come contesto dell'agente.
Schema Extractor — un'alternativa specializzata per l'estrazione strutturata di dati dal testo.