Raccolta e analisi dei dati con Agents Platform in Next.js
Raccogli e analizza i dati nei webhook post-chiamata con Agents Platform e Next.js.
Tutorial · Presuppone che tu abbia completato la guida rapida di ElevenAgents e configurato un progetto Next.js.
Introduzione
In questo tutorial imparerai a creare un agente vocale che raccoglie informazioni dall’utente tramite la conversazione, quindi analizza ed estrae i dati in modo strutturato e li invia alla tua applicazione tramite il webhook post-chiamata.
Requisiti
- Un account ElevenLabs con una chiave API.
- Node.js v18 o versione successiva installato sul tuo computer.
Configurazione
Crea un nuovo progetto Next.js
Ti consigliamo di usare il nostro template Agents Platform per v0.dev come punto di partenza per la tua applicazione. Questo template è un’applicazione Next.js pronta per la produzione con l’agente ElevenLabs già integrato.
Configura Agents Platform
Segui la nostra guida a Next.js per i passaggi di installazione e configurazione. Poi torna qui per sviluppare le funzionalità avanzate.
Configurazione dell’agente
Imposta il primo messaggio
Imposta il primo messaggio e specifica la variabile dinamica per la piattaforma.
Imposta il prompt di sistema
Imposta il prompt di sistema. Puoi includere anche qui le variabili dinamiche.
Configura gli strumenti client
Configura il seguente strumento client per navigare tra i passaggi:
- Nome:
set_ui_state- Descrizione: Usa questo strumento lato client per navigare tra i diversi stati dell’interfaccia utente.
- Attendi risposta:
true - Timeout della risposta (secondi): 1
- Parametri:
- Tipo di dati: string
- Identificatore: step
- Obbligatorio: true
- Tipo di valore: LLM Prompt
- Descrizione: Il passaggio a cui passare nell’interfaccia utente. Usa esclusivamente i passaggi definiti nel prompt di sistema.
Imposta la voce dell'agente
Vai alla scheda Voice e imposta la voce del tuo agente. Puoi trovare un elenco di voci consigliate per Agents Platform nella documentazione sulla progettazione di voci conversazionali.
Imposta i criteri di valutazione
Vai alla scheda Analysis e aggiungi un nuovo criterio di valutazione.
- Nome:
all_data_provided- Prompt: Valuta se l’utente ha fornito una descrizione dell’agente che desidera generare e una descrizione della voce che l’agente dovrebbe avere.
Configura la raccolta dati
Puoi usare l’analisi post-chiamata per estrarre dati dalla conversazione. Nella scheda Analysis, in Data Collection, aggiungi i seguenti elementi:
- Identificatore:
voice_descriptiondata-type:String- Descrizione: In base alla descrizione della voce che l’utente desidera per l’agente, genera una descrizione concisa della voce, includendo età, accento, tono e carattere, se disponibili.
- Identificatore:
agent_descriptiondata-type:String- Descrizione: In base alla descrizione dell’agente che l’utente desidera progettare, genera un prompt utilizzabile per addestrare un modello ad agire come l’agente.
Configura il webhook post-chiamata
I webhook post-chiamata vengono usati per avvisarti quando una chiamata termina e i passaggi di analisi ed estrazione dei dati sono stati completati.
In questo esempio, il webhook post-chiamata esegue alcuni passaggi:
- Crea un design vocale personalizzato in base a
voice_description. - Crea un agente ElevenLabs per gli utenti in base a
agent_descriptionfornito. - Recupera i documenti della knowledge base dallo stato della conversazione archiviato in Redis e associa la knowledge base all’agente.
- Invia un’email all’utente per informarlo che il suo agente ElevenLabs personalizzato è pronto a conversare.
Quando esegui l’app in locale, ti serve uno strumento come ngrok per esporre il server locale a Internet.
Vai alle impostazioni di Agents Platform e, in Post-Call Webhook, crea un nuovo webhook e incolla il tuo URL ngrok: https://<your-url>.ngrok-free.app/api/convai-webhook.
Dopo aver salvato il webhook, riceverai un segreto per i webhook. Assicurati di conservarlo in modo sicuro, poiché dovrai impostarlo in seguito nel file .env.
Integra le funzionalità avanzate
Configura un database Redis per archiviare lo stato della conversazione
In questo esempio usiamo Redis per archiviare lo stato della conversazione. Questo ci consente di recuperare i documenti della knowledge base dallo stato della conversazione al termine della chiamata.
Se esegui il deployment su Vercel, puoi configurare l’integrazione Upstash for Redis oppure registrarti a un account Upstash gratuito e creare un nuovo database.
Configura Resend per inviare email post-chiamata
In questo esempio usiamo Resend per inviare all’utente l’email post-chiamata. Per farlo, devi creare un account Resend gratuito e configurare una nuova chiave API.
Imposta le variabili d’ambiente
Nella root del progetto, crea un file .env e aggiungi le seguenti variabili:
Configura sicurezza e autenticazione
Per proteggere il tuo agente ElevenLabs, devi abilitare l’autenticazione nella scheda Security della configurazione dell’agente.
Una volta abilitata l’autenticazione, per avviare una conversazione con l’agente devi creare un URL firmato in un ambiente server-side sicuro. In Next.js, puoi farlo configurando una nuova route API.
Avvia la sessione di conversazione
Per avviare la conversazione, chiama prima la route API per ottenere l’URL firmato, quindi usa l’hook useConversation per configurare la sessione di conversazione.
Strumento client e variabili dinamiche
Nella configurazione dell’agente precedente, hai registrato lo strumento client set_ui_state per consentire all’agente di navigare tra i diversi stati dell’interfaccia utente. Per completare l’integrazione, devi passare l’implementazione dello strumento client alle opzioni di conversation.startSession.
Qui puoi anche passare le variabili dinamiche alla conversazione.
Caricamento di documenti nella knowledge base
Nel passaggio Training, l’agente chiederà all’utente di caricare documenti o inviare URL di siti web pubblici contenenti informazioni che dovrebbero essere disponibili al proprio agente. Qui puoi usare la nuova funzione after di Next.js 15 per consentire il caricamento dei documenti in background.
Crea una nuova server action upload per gestire la creazione della knowledge base all’invio del modulo. Una volta creati tutti i documenti della knowledge base, archivia l’ID della conversazione e gli ID della knowledge base nel database Redis.
Gestione del webhook post-chiamata
Il webhook post-chiamata viene attivato quando una chiamata termina e i passaggi di analisi ed estrazione dei dati sono stati completati.
Qui vengono eseguiti alcuni passaggi:
- Verifica il segreto del webhook e costruisce il payload del webhook.
- Crea un design vocale personalizzato in base a
voice_description. - Crea un agente ElevenLabs per gli utenti in base a
agent_descriptionfornito. - Recupera i documenti della knowledge base dallo stato della conversazione archiviato in Redis e associa la knowledge base all’agente.
- Invia un’email all’utente per informarlo che il suo agente ElevenLabs personalizzato è pronto a conversare.
Esaminiamo ogni passaggio nel dettaglio.
Verifica il segreto del webhook e costruisci il payload del webhook
Quando riceviamo la richiesta del webhook, verifichiamo prima il segreto del webhook e costruiamo il payload del webhook.
Crea un design vocale personalizzato in base a voice_description
Usando voice_description dal payload del webhook, creiamo un design vocale personalizzato.
Recupera i documenti della knowledge base dallo stato della conversazione archiviato in Redis
Il caricamento dei documenti potrebbe richiedere più tempo dell’analisi dei dati del webhook, quindi dovremo interrogare periodicamente lo stato della conversazione in Redis finché i documenti non saranno stati caricati.
Crea un agente ElevenLabs per gli utenti in base a agent_description fornito
Crea l’agente ElevenLabs per l’utente in base a agent_description fornito e associa all’agente il design vocale e la knowledge base appena creati.
Invia un’email all’utente per informarlo che il suo agente ElevenLabs personalizzato è pronto a conversare
Dopo aver creato l’agente, puoi inviare un’email all’utente per informarlo che il suo agente ElevenLabs personalizzato è pronto a conversare.
Puoi usare new.email, un pratico strumento del team di Resend, per progettare liberamente i template delle tue email. Quando il template ti soddisfa, crea un nuovo componente e aggiungi l’ID dell’agente come prop.
Avvia l’app
Per eseguire l’app in locale end-to-end, devi prima avviare il server di sviluppo Next.js, quindi eseguire il tunnel ngrok in un terminale separato per esporre a Internet l’handler del webhook.
- Terminale 1:
- Esegui
pnpm devper avviare il server di sviluppo Next.js.
- Esegui
- Terminale 2:
- Esegui
ngrok http 3000per esporre a Internet l’handler del webhook.
- Esegui
Ora apri http://localhost:3000 e inizia a progettare il tuo agente ElevenLabs personalizzato, con la tua voce!