Nodo AI Agent - Integrazione LLM e Tool Calling in ConvyAI Agentic Flow
Overview
Il nodo AI Agent è il punto principale di integrazione con i Large Language Model (LLM) all'interno di un Agentic Flow. Quando il flusso raggiunge questo nodo, viene composta e inviata una chiamata al provider LLM configurato, utilizzando un System Prompt e uno User Message che possono contenere riferimenti dinamici a variabili del flusso. La risposta del modello è resa disponibile come output per i nodi successivi.
Il nodo estende le capacità LLM tramite tool: MCP Server esterni, funzioni JavaScript definite inline e analisi di immagini tramite il Visioning Tool. L'agente opera in un loop di ragionamento - può invocare più tool in sequenza prima di produrre la risposta finale. Più nodi AI Agent possono essere concatenati, ciascuno costruendo sull'output del precedente.
La sequenza seguente mostra il loop di ragionamento quando sono configurati dei tool:
Posizionamento
Il nodo AI Agent ha un ingresso e un'uscita. Può essere posizionato in qualsiasi punto del flusso dopo un nodo trigger.
Configurazione
| Campo | Descrizione |
|---|---|
| Provider / Modello | Il provider LLM e il modello da utilizzare (es. OpenAI, Anthropic). Deve essere configurato nella sezione AI Models del tenant. |
| System Prompt | Istruzioni che definiscono il comportamento dell'agente. Supporta riferimenti $. |
| User Message | Input inviato al modello. Supporta riferimenti $ agli output dei nodi precedenti e alle variabili di contesto del flusso. |
Se una variabile referenziata non esiste al momento dell'esecuzione, il suo valore viene sostituito con null.
Output
| Campo | Tipo | Descrizione |
|---|---|---|
response | string | Testo generato dall'LLM. |
usage.input_token | number | Token consumati in input. |
usage.output_token | number | Token generati in output. |
usage.thinking_token | number | Token di ragionamento (disponibilità dipende dal modello selezionato). |
Tool: MCP Server
Collega uno o più MCP Server esterni per estendere le capacità dell'agente:
- Specifica l'URL del server e la modalità di autenticazione (nessuna, Bearer token, header custom).
- Dopo la connessione, seleziona quali metodi esposti dal server rendere disponibili all'agente. Se nessuno è selezionato, tutti i metodi sono disponibili.
- Ogni metodo mostra la sua firma: nome, descrizione, parametri di input con tipo.
L'agente può invocare solo i metodi inclusi nella selezione configurata (whitelist). In caso di errore di connessione, la configurazione del nodo può comunque essere salvata.
Tool: Funzioni JavaScript
Definisci una o più funzioni JavaScript inline nel nodo:
| Campo | Descrizione |
|---|---|
| Descrizione | Descrizione in linguaggio naturale usata dall'LLM per decidere quando invocare la funzione. |
| Codice | Corpo JavaScript della funzione. L'editor supporta syntax highlighting. |
| Parametri di input | Parametri in formato JSON Schema che l'LLM deve fornire alla chiamata. |
Accedi ai parametri di input della funzione tramite l'oggetto $args.
Le funzioni vengono eseguite in una sandbox isolata con gli stessi vincoli del nodo Code: timeout 10 secondi, limite memoria 8 MB. Un errore in una funzione JavaScript non interrompe il flusso - l'errore viene comunicato all'agente che prosegue il ragionamento.
Tool: Visioning (analisi immagini)
Il Visioning Tool non è un nodo autonomo - è configurabile esclusivamente come tool collegato al nodo AI Agent. Permette all'agente di analizzare immagini tramite un LLM multimodale.
Configurazione:
Censisci una o più immagini da passare all'agente, specificando per ciascuna:
- URL dell'immagine (URL statico o riferimento a variabile
$) - Livello di qualità di elaborazione
Le immagini censite nel Visioning Tool sono visibili nel corpo del nodo nel canvas e modificabili o eliminabili.
Regole di validazione URL:
| Scenario | Comportamento |
|---|---|
| URL sintatticamente non corretto | Il salvataggio è bloccato. |
URL contiene un riferimento a variabile (es. $('MyNode').output.imageUrl) | La validazione formale non viene eseguita; il salvataggio è sempre consentito. |
| URL corretto ma non raggiungibile al salvataggio | Il salvataggio è consentito; viene mostrato un warning. |
| Estensione immagine non supportata dal modello selezionato | Viene segnalato l'errore. |
Comportamento in esecuzione:
- Le immagini vengono scaricate dal backend prima di invocare il modello LLM - il provider non effettua il fetch diretto dell'URL.
- Le immagini vengono inviate al modello come contenuto binario (non come URL), abilitando il visioning anche in ambienti senza accesso diretto alle sorgenti.
- Le immagini non vengono persistite - vengono usate solo per la singola invocazione e poi scartate.
- Se il download di una o più immagini fallisce (URL non raggiungibile, timeout, formato non supportato, dimensione eccessiva), il nodo degrada automaticamente a modalità solo testuale senza interrompere il flusso.
La funzionalità richiede un LLM con capacità multimodale.
Concetti chiave
| Termine | Definizione |
|---|---|
| System Prompt | Istruzione di sistema fornita all'LLM che definisce il comportamento dell'agente. |
| User Message | Messaggio utente inviato all'LLM; supporta riferimenti dinamici a variabili del flusso. |
| MCP Server | Server esterno compatibile con il protocollo MCP, collegabile al nodo AI Agent come tool. |
| Whitelist metodi | Insieme dei metodi MCP selezionati e autorizzati per un nodo; l'agente non può invocare metodi fuori da questa lista. |
| Visioning | Capacità del nodo AI Agent di analizzare immagini tramite modelli LLM multimodali. |
| Loop di ragionamento | Ciclo di ragionamento dell'agente, che può includere più invocazioni di tool prima della risposta finale. |