Quick Start: Come avviare il tuo AI Agent in Dialfire

Benvenuto nel mondo dei Dialfire AI Agents!🎉

Non preoccuparti: non serve essere un ninja della tecnologia per mettere in funzione il tuo smart AI Agent. Con pochi clic, il tuo agente è pronto a supportare le tue chiamate.

È davvero semplice:

• Apri Voice Automation nel menu Dialfire: qui vengono creati e gestiti tutti gli AI Agents.
• Clicca su New IVR in alto a destra e seleziona il tuo AI Agent. Viene creato con un solo clic.
• Voilà: Il tuo AI Agent inizia con un template di esempio pronto all’uso. Questo template contiene già tutti gli elementi fondamentali per iniziare: perfetto per creare subito le tue personalizzazioni.

Prompting 1x1 – Inizia in modo semplice, cresci in modo intelligente 🎓

La cosa più importante nel prompting: Inizia in modo graduale e procedi passo dopo passo.

Come avere successo:

• Inizia con una versione minimale che spiega solo in modo generale all’agente cosa intendi fare. In senso figurato: Digli dove deve correre, non come deve muovere i piedi.
  Testa cosa l’agente riesce già a fare – rimarrai sorpreso.
• Poi crea una versione appena sufficiente per andare live.
• Vai live con un volume di chiamate gestibile che ti permetta di osservare ogni singola chiamata.
• Correggi i problemi che individui nell'operatività live – spesso sono molto diversi da quelli che ti hanno creato difficoltà nel “test a secco”. Questa è la parte in cui dovresti investire più tempo.

☝️Spesso meno è meglio:

• Imposta aspettative realistiche: le persone sbagliano, e anche l’AI – il 100% di correttezza non esiste.
• Formula in modo chiaro e semplice.
• Evita istruzioni contraddittorie.
• Quando dici cosa il bot non deve fare, dì anche cosa dovrebbe fare invece.
• Usa il discorso diretto solo dove è necessario (ad es. compliance). È meglio descrivere "Cosa" l’agente deve dire, non il "Come".
• Evita conoscenze aggiuntive inutili.
• Non fissarti su singoli errori e non cercare di compensarli.
• Istruzioni aggiuntive spesso peggiorano le prestazioni in altre aree che prima funzionavano bene. Cerca invece istruzioni che puoi eliminare, spesso molto più efficace.
• Descrivi il tuo piano all’agente, così capirà il significato dietro le singole istruzioni e potrà prendere decisioni migliori.
• L’AI Agent non è un alieno👽: Prima di spiegare il mondo all’agente, verifica se non conosce già il concetto.
  Esempio: “Sei un bot di assistenza in un autonoleggio” invece di “Ti chiamano clienti con problemi all’auto.”

Anche con queste semplici regole puoi creare AI Agents utili per l’uso pratico.

💡Attenzione: Man mano che aggiungi sempre più compiti, noterai che il tuo agente sembra un po’ meno brillante, perde spontaneità e commette errori. È del tutto naturale, perché anche l’AI, come un essere umano, ha un’attenzione limitata.

La buona notizia: Esistono soluzioni, che presenteremo più avanti – quindi non ci sono limiti. 🎉

Il primo prompt – Il cuore del tuo agente

Il prompt è il cervello del tuo AI Agent: qui definisci chi è, come parla e di cosa è capace.

☝️Importante: La struttura non è rigidamente prestabilita: creatività ed esperienza fanno la differenza. Tutto ciò che già sai sull’uso dell’AI rimane valido.

☝️Regola base: Scrivi il prompt come lo annoteresti per un nuovo dipendente prima di lasciarlo telefonare. Se segui questa regola, puoi saltare molti tutorial.

Struttura indicativa del prompt:

Contiene le descrizioni di base su come il bot dovrebbe comportarsi:

• Ruolo & scopo – Chi parla? Qual è l’obiettivo dell’agente?
• Compito – Cosa dovrebbe fare l’agente nella conversazione?
• Paletti – Cosa non deve assolutamente fare l’agente nella conversazione?
• FAQ / Modelli di risposta – Frasi brevi e chiare di esempio per l’LLM

Contiene istruzioni di controllo inserite direttamente nel testo per aggiungere ancora più dinamicità

A parte le istruzioni di controllo opzionali, non esiste un formato specifico che tu debba seguire. Consigliamo di usare Markdown per la formattazione: l’AI lo comprende molto bene.

Esempio di un prompt di partenza semplice:

# Your Role
You are Helena Fisher, a friendly AI phone agent from GreatProducts. You always speak politely, confidently, and in a natural tone.
 
# Your Task
Greet the customer and ask them to briefly explain their request.
$customer_request Customer's inquiry
 
Answer questions from the FAQ. For unknown requests, transfer the call using function "connect_agent". If resolved, say goodbye and use function "hangup".
 
@connect_agent Transfers the call to a human agent.
@hangup Ends the call.
 
# FAQ
Q: Wants to return product  
A: They can return products within 30 days if unused and in original packaging. 
  
Q: Delivery times  
A: Standard: 3–5 business days. Express: 1–2 business days.  
 
Q: Opening hours  
A: Mon–Fri: 8:00–18:00, Sat: 9:00–14:00. 
 

Nell’esempio vedi # Your Task come intestazione di sezione in formato Markdown, così come $customer_request e @connect_agent come istruzioni di controllo. Tra poco entreremo più nel dettaglio su questi due elementi… resta con noi 😉

Testare il prompt – Prova, sperimenta, ottimizza 🧪

Prima che il tuo AI Agent dia il meglio di sé nell’uso reale, testa il prompt direttamente nel menu Voice Automation. Qui puoi verificare facilmente come reagisce l’agente – sia tramite Call sia tramite Chat.

Come funziona:

• Apri il menu: vai su Voice Automation →Test.
• Scegli la modalità di test: decidi tra Call (chiamata simulata) o Chat (interazione testuale).
• Avvia l’interazione: parla o scrivi le tue richieste di prova esattamente come farebbero i tuoi clienti.
• Osserva i risultati: controlla se l’agente compila correttamente le variabili ed esegue in modo affidabile i Function Calls.

💡Suggerimento: Piccole modifiche in un punto possono avere un grande impatto sull’intero flusso. Testa di nuovo subito.

Si parte – il tuo AI Agent è pronto al lancio! 🚀

🎉 Congratulazioni!

Ce l’hai fatta: hai configurato e testato il tuo AI Agent, e ora è pronto a portare l’esperienza di customer service a un nuovo livello! Prima che l’agente possa partire, devi assegnarlo alla linea inbound corretta:

1️⃣ Nel menu Voice Automation, vai nell’area test e attiva la tua versione finale del bot.

2️⃣ Attiva sulla tua inbound line:

• Apri il menu Phone numbers e seleziona la linea desiderata.
• In IVR Settings, seleziona il titolo del tuo bot nel menu a tendina IVR.
• Spunta la casella Enabled e salva – fatto!

E voilà – il tuo AI Agent è live e pronto a entusiasmare i tuoi clienti. Mettiti comodo, goditi lo spettacolo e guarda come il tuo nuovo collega virtuale dà una marcia in più al customer service! 🤘

La fatturazione del tuo AI Agent è semplice e trasparente:

• Tutti i minuti di connessione dell’AI Agent vengono fatturati alla tariffa Conversational AI C – in aggiunta ai normali costi di connessione.
• Inoltre, anche la durata dell'output vocale generato viene fatturata alla tariffa letterale (Conversational AI C).
• 💡Smart-Saving: L'output vocale che si ripete esattamente viene memorizzato automaticamente nella cache. Nella chiamata successiva non vengono addebitati costi aggiuntivi.

Cosa non abbiamo ancora spiegato... 🤔

Nel prompt di esempio sono comparsi due elementi che non vogliamo lasciare lì così:

• Segnaposto variabili come $customer_request
• Chiamate di funzione come @connect_agent

Entrambi sono strumenti centrali che rendono il tuo agente ancora più potente.

Nel prossimo passo ti mostreremo come funzionano i segnaposto variabili e le chiamate di funzione – e perché sono la chiave per conversazioni davvero intelligenti.

Segnaposto variabili

Con segnaposto variabili inseriti, il tuo agente diventa un professionista degli appunti: salva automaticamente le informazioni dalla conversazione direttamente nel record dati, che potrai poi elaborare ulteriormente in Dialfire.

Sintassi:

$Nome_campo Descrizione del campo → definisce un campo previsto

Esempio:

$customer_request Richiesta del cliente → registra quale richiesta nomina il cliente

☝️Importante:

• Posiziona il campo con il simbolo $ davanti, su una riga dedicata, vicino al tema a cui si riferisce. Così l’agente capisce dal contesto quando deve compilare il campo. Tuttavia, non fare riferimento alla variabile nel resto del prompt, cioè non scrivere: “Non dimenticare di compilare la variabile XYZ”
• Dai alla variabile un nome che abbia senso per l’agente – ad es. “Nome cliente” invece di “Campo15” e aggiungi una breve descrizione dopo il nome del campo: funziona in modo molto più affidabile.

Variabile con opzioni di selezione

Scrivi una riga di options: direttamente sotto la variabile con i valori consentiti, separati da virgole. L’agente potrà usare solo questi. Ad esempio:

$will_newsletter Il cliente accetta di ricevere la newsletter
options: sì, no

Function Calls – Attivare azioni

Function Calls sono i pulsanti d’azione del tuo agente. Attivano azioni dirette quando qualcosa deve accadere subito.

Le funzioni vere e proprie si vedono nella finestra Script. Si tratta di funzioni Javascript che puoi estendere come vuoi.

Per poter usare queste funzioni, devono essere resi noti all’agente nel prompt. Questo avviene su una nuova riga con @ seguita dal nome della funzione e da una descrizione. A differenza delle variabili, la posizione nel prompt non è importante.

In linea di massima l’agente decide da solo, in base al contesto della conversazione quando usare le funzioni. Ma puoi influenzarlo nel prompt e far sì che l’agente ne annunci l’uso. Questo garantisce transizioni molto naturali nella conversazione.

Esempio:

• Nella finestra Script c’è la funzione:

  function connect_{
   ...
  }

• Nel prompt rendi nota questa funzione con:

  @connect_agent Collega il cliente a una persona.

• E nel testo scrivi, ad esempio:

  Se non sai la risposta alla domanda, allora di’ che stai collegando con un collega che potrà sicuramente aiutare e allo stesso tempo usa la funzione "connect agent".

Advanced – Fuori dalla gabbia

Benvenuto al livello successivo! 🎮

I tuoi primi AI agent sono già in funzione – ora ti mostriamo i segreti per collegare il tuo agente al mondo esterno. Niente paura: anche se si chiama “Advanced”, non serve un dottorato in informatica – anche se non guasta. 🙂 Consideralo una cassetta degli attrezzi piena, pronta per costruire grandi cose.

💡 Riesci a mantenere un segreto?

Quello che finora abbiamo chiamato “prompt” in realtà non è affatto un prompt statico. È un template dinamico che viene ricomposto a ogni turno.

Per un informatico suona subito familiare: non un testo rigido, ma un sistema di rendering flessibile – simile a VueJS o Angular, ma per AI Agents.

Ed è proprio qui che entrano in gioco le funzioni avanzate di template…

Funzioni avanzate di template – I superpoteri del tuo prompt 🦸‍♂️

Il prompt template può fare molto di più di semplici sostituzioni di valori. Gestisce una sintassi di template complessa che puoi annidare come vuoi. Così il prompt diventa un sistema modulare flessibile che rappresenta in modo pulito anche logiche conversazionali complesse.

Sostituzioni di valori con {{expression}}

Il caso più semplice: {{data.feldname}}

Ma attenzione: non ci sono solo nomi di campi – sono possibili anche function calls. Così puoi inserire contenuti dinamici direttamente nel template.

Blocchi condizionali con IF

Con la direttiva IF controlli quali contenuti finiscono davvero nel prompt. O nel mezzo del testo:

({{#if condition}} Here is an optional text {{/if}})

oppure con più alternative, racchiudendo blocchi grandi:

{{#if condition}}
{{#elif alternative_condition}}
{{#else}}
{{/if}}

Utilizzo: mostrare componenti del prompt alternativi/opzionali

Cicli con EACH

Per elementi ripetitivi usa EACH:

{{#each itemVar @ array-expression}}
{{/each}}

Perfetto quando le cose si ripetono un numero arbitrario di volte – ad es. una lista di prodotti o contratti.

Con queste funzioni avanzate di template dai dinamicità ai tuoi agenti.

💡E l’hai già notato? Nei Logs trovi anche un piccolo link a next prompt accanto alle risposte dell’agente. Così puoi controllare facilmente se il prompt generato era davvero corretto.

Definire funzioni personalizzate

Abbiamo già parlato di funzioni, ma non ancora della sintassi completa. Nella finestra Script definisci una funzione in Javascript, ad esempio così:

function args{
}

L’oggetto args contiene i parametri che l’agente ha passato durante la chiamata.

Nel prompt vero e proprio dichiari la funzione, ad esempio così:

@funktionsname Descrizione dello scopo della funzione
-argument1: Descrizione del parametro
options: value1,value2
optional: true
-argument2: Descrizione del 2° parametro

Con options specifichi i valori consentiti se vuoi permettere solo alcune possibilità. E con optional indichi che questo parametro non deve necessariamente essere presente.

E cosa restituisce la funzione?

Il valore di ritorno non deve seguire un formato specifico. Puoi restituire qualsiasi struttura di oggetti oppure anche una semplice stringa con un’istruzione su come l’agente dovrebbe proseguire.
L’unica cosa importante è che l’agente ne capisca il senso.

💡Consigli

• Funzioni e parametri ben scelti, con una descrizione adeguata, sono fondamentali per un uso affidabile da parte dell’agente.
• Usa le funzioni con parsimonia. Se l’agente ha molte funzioni tra cui scegliere, consuma molto budget di attenzione.

Segnaposto variabili vs Function Calls — cosa, quando, perché? 🤔

I segnaposto variabili lavorano silenziosamente in background e scrivono valori riconosciuti (es. nome, CAP) nell’oggetto data.

• Vantaggio: risparmia il budget di attenzione dell’LLM.
• Svantaggio: il valore non può essere verificato prima che il bot risponda.

Function Calls sono gli attori principali: l’LLM chiama una funzione che esegue controlli runtime o validazioni.

• Ambito d’uso: ovunque servano risultati immediati – ad es. validazioni o query CRM.

💡Regola pratica:

• Segnaposto variabili → per campi non critici
• Function Calls → per tutto ciò che deve essere validato o elaborato immediatamente

L’ambiente Javascript 💻

Con Javascript hai a disposizione un ambiente LowCode con cui realizzare funzioni avanzate.

Oggetti globali

Nell’ambiente Javascript trovi alcuni oggetti globali che puoi usare da qualsiasi funzione.

data {} - l’oggetto centrale, i cui campi vengono trasferiti direttamente nel record dati del contatto per l’elaborazione successiva

temp {} - un oggetto temporaneo in cui puoi salvare dati serializzabili tra i turni

• actions [] - per attivare comandi di controllo
• tts_translation {} - una mappa delle espressioni regolari in formato stringa alle sostituzioni fonetiche per forzare la pronuncia corretta di determinati termini
• LOG () - una funzione per output di log che puoi poi vedere nel log della conversazione

Attivare API Calls via HTTP

Per API calls verso sistemi esterni sono disponibili funzioni globali:

GET​(url, options)
POST​(url, payload, options)
PUT​(url, payload, options)
DELETE​(url, options)

Il risultato è un oggetto Response con le seguenti funzioni:
status(), text(), json()

La request funziona in modo asincrono. Puoi quindi avviare più request in parallelo e lo script attende la fine della request solo quando accede a una delle funzioni della Response.

Utilizzo degli Script Hooks

Puoi implementare i seguenti hook come funzione per reagire a determinati eventi:

• onLoad() - all’avvio dell’agente
• onUpdate() → dopo ogni turno
• onClose() → alla fine della conversazione (ad es. task di chiusura, operazioni di scrittura)
• onFieldUpdate(fieldname,value) - se definito, i segnaposto variabili non vengono semplicemente aggiunti all’oggetto data, ma vengono elaborati tramite questa funzione
• onFunctionCall(name,arguments) → se l’agente chiama una funzione non definita… così si possono implementare funzioni dinamiche

Aiuto, il mio agente sta diventando più stupido - oppure - l'utilità di tenere il segno con il dito 🤔

Il tuo agente era partito bene? E ora semplicemente non fa più quello che dovrebbe?

Hai già implementato tutti i nostri consigli – eppure – è snervante!

Allora probabilmente sei arrivato al punto in cui ti serve la nostra soluzione promessa per agenti davvero grandi.

Perché i prompt statici raggiungono i loro limiti

Gli AI agent, come gli esseri umani, hanno un budget di attenzione limitato. Ma un nuovo dipendente potrebbe lavorare benissimo con il tuo prompt, no? L’AI è davvero così stupida? Perché può scrivere testi lunghissimi ma fallisce in una conversazione del genere?

💡 Risposta semplice: Il tuo dipendente tiene il segno con il dito, ma l’AI di oggi no!

Un essere umano può ricordare (o tenere il segno con il dito) nel punto esatto in cui si trova nello script della conversazione; l’AI deve ricostruirlo a ogni risposta dal contesto della conversazione. Questo richiede molta attenzione e ne rimane poca per la risposta vera e propria.

Benvenuto nel Context-Engineering!

Sei sulla soglia dal prompt engineer al context engineer. L’idea è adattare dinamicamente il contesto (prompt) in modo che per la prossima risposta restino solo le parti rilevanti. Ed è qui che i prompt template danno il meglio.

Tutto ciò che può essere utile per la risposta successiva nella conversazione in corso deve essere incluso, tutto il resto deve essere eliminato.

Information Agents

Se lavori su un agente che deve solo fornire informazioni, ha senso mettere a disposizione solo la parte attualmente rilevante della knowledge base. Quindi, fai avviare prima all’agente un function call con cui recuperare la parte corretta della knowledge base.

Per knowledge base piccole potresti semplicemente scegliere da una lista di argomenti; per knowledge base molto grandi serve un sistema RAG.

Poi includi il documento relativo all’argomento nel prompt tramite il template. E a quel punto l’agente può concentrarsi completamente sulla domanda reale.

Transactional Agents

Se il tuo agente deve attraversare un processo complesso, dovresti dividerlo in fasi. Passi da una fase all’altra tramite function calls.

💡Questo risolve molti problemi in una volta sola:

• piena attenzione nelle singole fasi
• altissima aderenza al processo - segue esattamente le istruzioni
• il processo può essere controllato in modo deterministico - l’agente non può semplicemente saltare le fasi
• le singole fasi possono essere ottimizzate e testate in modo indipendente, senza interferenze tra fasi
• non solo risposte migliori ma anche più rapide grazie a un contesto più piccolo
• il tuo agente può crescere indefinitamente

Esempio di Prompt Template

# Role
You are a phone ordering bot at GreatProducts.
 
# General Process
You guide the customer through the ordering process:
- Greeting
- Capturing the shopping cart
- Capturing customer data
- Capturing payment data
- Saying goodbye
Focus completely on the current task.
 
# Current Task
{{#if !temp.phase}}
Greet the customer.
Tell the customer that we will first take down the desired items and at the same time activate the function “Neuer_Warenkorb”
@Neuer_Warenkorb Create a new shopping cart for order entry
{{#elif temp.phase===10}}
Ask the customer for the desired items
….
When all items are captured, then say that you now need the customer data and at the same time activate the function “Daten_Erfassen”
@Daten_Erfassen Prepare for capturing customer data.
{{#elif temp.phase===20}}
…
{{#elif temp.phase===30}}
….
{{#elif temp.phase===40}}
Say goodbye to the customer and end the conversation.
{{/if}}
 
#FAQ
Q: Why?  
A: Because!
 
@hangup ends the call

Spiegazione

Definisci una funzione in ogni fase che porta l’agente alla fase successiva. All’interno di questa funzione imposti il campo temp.phase al valore della fase successiva.

Non si crea una strana pausa tra le fasi? No, per niente.

L’agente prepara verbalmente il cliente alla nuova fase. Dopo di che però non aspetta una reazione del cliente, ma reagisce immediatamente al risultato del function call con il prompt modificato, così avvia subito la fase successiva senza che si crei una pausa nella conversazione.

Le dichiarazioni di funzione vengono anch’esse mostrate o nascoste dal template, così l’agente vede solo le funzioni rilevanti di volta in volta. Questo fa una grande differenza.

Poiché durante la conversazione modifichi dinamicamente il prompt, assicurati che attorno alle fasi rimanga abbastanza contesto perché lo storico della conversazione continui ad avere senso anche con il nuovo prompt. Nell’esempio viene modificata dinamicamente solo la sezione # Current Task. La descrizione generale del processo e le FAQ invece restano uguali.