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 gestiti della piattaforma o gli account LLM configurati in Impostazioni → Provider (vedi Collegare una chiave LLM). Puoi:
- Fissare un modello specifico del catalogo (gestito o sul tuo account).
- 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.searcheknowledge.semantic_search(knowledge base),web_search.search(ricerca web),web_scrape.fetch_page(lettura di una pagina web)… - Strumenti di canale — per una pipeline vocale:
phone_gateway.transfer_call,phone_gateway.hangup_call,phone_gateway.set_call_disposition. - Strumenti di connettore — quelli delle integrazioni collegate dalla tua organizzazione (ad es.
jira.create_issue,hubspot.search_contacts).
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 telefonico.
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. Su un modello gestito, i token di input e di output vengono addebitati in crediti secondo la tariffa del modello scelto.