Agenti IA
Il nodo agent invoca un LLM con un contesto composto e un insieme di strumenti. È il building block IA centrale di betool.
La triade ruolo / missione / selezione
Un agent non sa da solo cosa fare. Tre cose lo guidano:
- Ruolo — come lavora (stile, vincoli, postura). Breve. Riutilizzabile tra agent.
- Missione — cosa deve fare per questo caso d'uso specifico. Più lunga. Specifica della pipeline.
- Selezione — quali dati di contesto riceve come input. Composta esplicitamente.
Un agent che si comporta male ha quasi sempre un problema di ruolo, missione o selezione — non un problema di modello. Prima di aggiornare il modello, controlla prima questi tre.
Configurare la selezione
La selezione determina esattamente ciò che il LLM vede. Cinque tipi:
| Tipo | Effetto |
|---|---|
key | Legge ctx.results[<key>] — ad es. exchange.intent |
prefix | Concatena tutte le chiavi sotto un prefisso — ad es. project.* |
literal | Testo grezzo con placeholder — ad es. "Question: {user_message}" |
file | Allega un file (multimodale) — ad es. webhook.payload._files |
history | Include gli N turni precedenti (multi-turno nativo) |
I primi quattro compongono lo user_message per il turno corrente. history è un canale ortogonale passato nell'array messages[] del LLM.
Nessun fallback a runtime. Se la selezione è vuota, il LLM riceve "" e registra un avviso. Devi includere esplicitamente tutto ciò di cui l'agent ha bisogno — non c'è magia.
Modello LLM
Scelto tra i modelli configurati in Amministrazione → Modelli. Puoi:
- Fissare un modello specifico (ad es.
claude-opus-4-7). - Usare il modello predefinito dell'organizzazione.
- Definire un fallback (se il primario fallisce, passa a un secondario).
Strumenti
Gli strumenti sono le funzioni che il LLM può chiamare. Li selezioni dal catalogo:
- Strumenti globali —
knowledge.search,web.fetch,compute.now… - Strumenti di canale — per una pipeline vocale:
voice.barge_in,voice.hangup,voice.transfer… - Strumenti di dominio — creati dai tuoi operatori (ad es.
crm.create_ticketesposto tramite un nodo operator).
Un agent vede solo gli strumenti realmente raggiungibili all'interno del suo contesto di esecuzione. A un agent in una pipeline email non verrà offerto uno strumento vocale.
Formato di output
Tre opzioni:
- Testo libero — per risposte rivolte all'utente.
- JSON strutturato — l'agent deve produrre JSON conforme a uno schema definito (validato in modo rigoroso).
- Solo chiamata di strumento — l'agent non scrive nulla: o chiama uno strumento o non fa nulla.
La modalità JSON è obbligatoria per gli agent il cui output alimenta una condition a valle o un altro agent.
Buone pratiche
- Descrivi gli strumenti con precisione. La descrizione che il LLM vede deve coprire: COSA, QUANDO USARLO, QUANDO EVITARLO, FORMATO. Una descrizione troppo breve significa che il LLM indovina — il che significa bug invisibili.
- Testa con un benchmark. Vedi Benchmark.
- Mantieni la missione coerente. Una missione che cambia attraverso 3 versioni significa un agent che regredisce. Versiona le tue missioni.
Costi
Consulta Prezzi. Con BYOK, paghi direttamente il tuo provider LLM. Altrimenti, aspettati circa 30 crediti per 1K token di input e 90 per 1K token di output.