Funzioni Callable nel Nodo AI Agent - ConvyAI
Panoramica
Il nodo AI Agent supporta i Function Tools - funzioni JavaScript definite dall'utente che il modello può invocare durante l'esecuzione. Le funzioni estendono ciò che l'AI può fare all'interno di un flusso: validare dati, eseguire calcoli, estrarre valori strutturati, chiamare servizi esterni o trasformare l'input prima di generare una risposta finale.
Le funzioni:
- Accettano parametri definiti tramite JSON Schema
- Possono eseguire logica personalizzata (validazioni, calcoli, estrazione dati)
- Restituiscono output che l'AI utilizza nella risposta finale
- Supportano funzioni standard e
async - Consentono
fetchper chiamate HTTP econsole.logper il debug
Configurazione della funzione
Apri la sezione Function Tools List nel nodo AI Agent e aggiungi una nuova funzione.

Ogni funzione viene configurata tramite una modale con i seguenti campi:
| Campo | Obbligatorio | Descrizione |
|---|---|---|
| Name | Sì | Identificatore univoco della funzione. |
| Description | Sì | Descrizione in linguaggio naturale usata dal modello per decidere quando invocare la funzione. |
| Code JS | Sì | L'implementazione JavaScript. |
| Input schema JSON | No | Definizione JSON Schema dei parametri di input della funzione. |
Editor di codice
L'editor di codice delle funzioni è basato su CodeMirror e include le seguenti funzionalità:
| Funzionalità | Descrizione |
|---|---|
| Syntax highlighting | Il codice è evidenziato secondo la sintassi JavaScript. |
| Hint & autocompletamento | Digitando $ si apre un menu di autocompletamento con le variabili e gli oggetti disponibili. Continua a digitare per filtrare (es. $.vars mostra solo i valori compatibili con vars). |
| Validazione automatica | Il codice viene validato in tempo reale. Errori sintattici e strutturali vengono rilevati immediatamente. |
| Segnalazione errori | Gli errori appaiono come marker nel margine sinistro. Passando sopra un marker viene mostrato un tooltip con la descrizione dell'errore (es. Unexpected token, Missing bracket). |
| Blocco salvataggio | Il salvataggio viene bloccato se sono presenti errori bloccanti. La funzione può essere salvata solo quando il codice è valido. |
Autocompletamento variabili
L'editor fornisce un sistema di autocompletamento attivato digitando $. Un suggerimento sotto il blocco di codice ricorda all'utente questa scorciatoia. Premendo $ si apre un menu contestuale con tutte le variabili disponibili e una casella di ricerca; selezionando una variabile viene inserita nella posizione del cursore.
Categorie di variabili disponibili:
| Variabile | Descrizione |
|---|---|
$.args | Oggetto contenente gli argomenti passati alla funzione al momento dell'invocazione, come definiti nello schema di input. |
$.input | Oggetto contenente la domanda dell'utente (campo question) e i file passati come input (campo attachments). |
$.context | Contesto di esecuzione: ID e nome del bot corrente, canale di comunicazione, ID conversazione e metadati correlati. |
$.entities | Oggetto contenente le variabili di flusso definite nell'ambiente di esecuzione corrente. |
Definizione input con JSON Schema
I parametri di input sono definiti tramite JSON Schema. Le variabili dichiarate nello schema sono accessibili all'interno della funzione tramite l'oggetto $.args.
{
"type": "object",
"properties": {
"orderId": {
"type": "string",
"description": "L'ID dell'ordine da cercare."
},
"language": {
"type": "string",
"enum": ["en", "it", "fr"]
}
},
"required": ["orderId"]
}
All'interno della funzione, accedi a questi valori come $.args.orderId e $.args.language.