Coleta e análise de dados com a Plataforma de agentes no Next.js
Coleta e análise de dados com a Plataforma de agentes no Next.js
Colete e analise dados em webhooks pós-chamada usando a Plataforma de agentes e o Next.js.
Tutorial · Pressupõe que você concluiu o início rápido do ElevenAgents e configurou um projeto Next.js.
Introdução
Neste tutorial, você aprenderá a criar um agente de voz que coleta informações do usuário por meio de uma conversa, depois analisa e extrai os dados de forma estruturada e os envia ao seu aplicativo pelo webhook pós-chamada.
Requisitos
- Uma conta da ElevenLabs com uma chave de API.
- Node.js v18 ou superior instalado na sua máquina.
Configuração
Crie um novo projeto Next.js
Recomendamos usar nosso modelo da Plataforma de agentes no v0.dev como ponto de partida para seu aplicativo. Este modelo é um aplicativo Next.js pronto para produção com o agente da ElevenLabs já integrado.
Configure a Plataforma de agentes
Siga nosso guia do Next.js para ver as etapas de instalação e configuração. Depois, volte aqui para criar os recursos avançados.
Configuração do agente
Defina a primeira mensagem
Defina a primeira mensagem e especifique a variável dinâmica da plataforma.
Defina o prompt do sistema
Defina o prompt do sistema. Você também pode incluir variáveis dinâmicas aqui.
Configure as ferramentas do cliente
Configure a ferramenta de cliente a seguir para navegar entre as etapas:
- Nome:
set_ui_state- Descrição: Use esta ferramenta do lado do cliente para navegar entre os diferentes estados da interface.
- Aguardar resposta:
true - Tempo limite de resposta (segundos): 1
- Parâmetros:
- Tipo de dados: string
- Identificador: step
- Obrigatório: true
- Tipo de valor: LLM Prompt
- Descrição: A etapa para a qual navegar na interface. Use apenas as etapas definidas no prompt do sistema!
Defina a voz do seu agente
Acesse a aba Voice e defina a voz do seu agente. Você pode encontrar uma lista de vozes recomendadas para a Agents Platform na documentação sobre Design de Voz Conversacional.
Defina os critérios de avaliação
Acesse a aba Analysis e adicione um novo critério de avaliação.
- Nome:
all_data_provided- Prompt: Avalie se o usuário forneceu uma descrição do agente que deseja gerar e uma descrição da voz que o agente deve ter.
Configure a coleta de dados
Você pode usar a análise pós-chamada para extrair dados da conversa. Na aba Analysis, em Data Collection, adicione os itens a seguir:
- Identificador:
voice_descriptiondata-type:String- Descrição: Com base na descrição da voz que o usuário quer que o agente tenha, gere uma descrição concisa da voz, incluindo idade, sotaque, tom e personalidade, se disponível.
- Identificador:
agent_descriptiondata-type:String- Descrição: Com base na descrição do agente que o usuário deseja criar, gere um prompt que possa ser usado para treinar um modelo para atuar como o agente.
Configure o webhook pós-chamada
Os webhooks pós-chamada são usados para avisar você quando uma chamada termina e as etapas de análise e extração de dados foram concluídas.
Neste exemplo, o webhook pós-chamada realiza algumas etapas:
- Cria um design de voz personalizado com base em
voice_description. - Cria um agente da ElevenLabs para os usuários com base no
agent_descriptionfornecido. - Recupera os documentos da base de conhecimento do estado da conversa armazenado no Redis e anexa a base de conhecimento ao agente.
- Envia um e-mail ao usuário avisando que seu agente personalizado da ElevenLabs está pronto para conversar.
Ao executar localmente, você precisará de uma ferramenta como o ngrok para expor seu servidor local à internet.
Acesse as configurações da Agents Platform e, em Post-Call Webhook, crie um novo webhook e cole sua URL do ngrok: https://<your-url>.ngrok-free.app/api/convai-webhook.
Após salvar o webhook, você receberá um segredo de webhooks. Armazene esse segredo com segurança, pois será necessário defini-lo posteriormente no arquivo .env.
Integre os recursos avançados
Configure um banco de dados Redis para armazenar o estado da conversa
Neste exemplo, usamos o Redis para armazenar o estado da conversa. Isso permite recuperar os documentos da base de conhecimento do estado da conversa após o término da chamada.
Se você estiver fazendo deploy na Vercel, poderá configurar a integração Upstash for Redis ou, como alternativa, criar uma conta gratuita na Upstash e criar um novo banco de dados.
Configure o Resend para enviar e-mails pós-chamada
Neste exemplo, usamos o Resend para enviar o e-mail pós-chamada ao usuário. Para isso, você precisará criar uma conta gratuita no Resend e configurar uma nova chave de API.
Defina as variáveis de ambiente
Na raiz do seu projeto, crie um arquivo .env e adicione as seguintes variáveis:
Configure a segurança e a autenticação
Para proteger seu agente da ElevenLabs, você precisa habilitar a autenticação na aba Security da configuração do agente.
Quando a autenticação estiver habilitada, você precisará criar uma URL assinada em um ambiente seguro do lado do servidor para iniciar uma conversa com o agente. No Next.js, você pode fazer isso configurando uma nova rota de API.
Inicie a sessão de conversa
Para iniciar a conversa, primeiro chame sua rota de API para obter a URL assinada e depois use o hook useConversation para configurar a sessão de conversa.
Ferramenta de cliente e variáveis dinâmicas
Na configuração do agente anterior, você registrou a ferramenta de cliente set_ui_state para permitir que o agente navegue entre os diferentes estados da interface. Para reunir tudo, você precisa passar a implementação da ferramenta de cliente para as opções de conversation.startSession.
É também aqui que você pode passar as variáveis dinâmicas para a conversa.
Envio de documentos para a base de conhecimento
Na etapa Training, o agente pedirá ao usuário que envie documentos ou URLs de sites públicos com informações que devem estar disponíveis para seu agente. Aqui, você pode usar a nova função after do Next.js 15 para permitir o envio de documentos em segundo plano.
Crie uma nova ação de servidor upload para processar a criação da base de conhecimento quando o formulário for enviado. Depois que todos os documentos da base de conhecimento forem criados, armazene o ID da conversa e os IDs da base de conhecimento no banco de dados Redis.
Processar o webhook pós-chamada
O webhook pós-chamada é acionado quando uma chamada termina e as etapas de análise e extração de dados são concluídas.
Aqui acontecem algumas etapas:
- Verificar o segredo do webhook e criar o payload do webhook.
- Criar um design de voz personalizado com base em
voice_description. - Criar um agente da ElevenLabs para os usuários com base na
agent_descriptionfornecida por eles. - Recuperar os documentos da base de conhecimento do estado da conversa armazenado no Redis e anexar a base de conhecimento ao agente.
- Enviar um e-mail ao usuário para avisar que seu agente personalizado da ElevenLabs está pronto para conversar.
Vamos analisar cada etapa em detalhes.
Verificar o segredo do webhook e criar o payload do webhook
Quando a solicitação do webhook é recebida, primeiro verificamos o segredo do webhook e criamos o payload do webhook.
Criar um design de voz personalizado com base em voice_description
Usando voice_description do payload do webhook, criamos um design de voz personalizado.
Recuperar os documentos da base de conhecimento do estado da conversa armazenado no Redis
O upload dos documentos pode levar mais tempo do que a análise dos dados do webhook. Por isso, precisamos consultar o estado da conversa no Redis até que os documentos sejam enviados.
Criar um agente da ElevenLabs para os usuários com base na agent_description fornecida
Crie o agente da ElevenLabs para o usuário com base na agent_description fornecida e anexe o design de voz e a base de conhecimento recém-criados ao agente.
Enviar um e-mail ao usuário para avisar que seu agente personalizado da ElevenLabs está pronto para conversar
Depois que o agente é criado, você pode enviar um e-mail ao usuário para avisar que seu agente personalizado da ElevenLabs está pronto para conversar.
Você pode usar o new.email, uma ferramenta prática da equipe da Resend, para criar visualmente seus templates de e-mail. Quando estiver satisfeito com o template, crie um novo componente e adicione o ID do agente como uma prop.
Executar o app
Para executar o app localmente de ponta a ponta, primeiro você precisará iniciar o servidor de desenvolvimento do Next.js e, em seguida, em outro terminal, iniciar o túnel do ngrok para expor o manipulador de webhooks à internet.
- Terminal 1:
- Execute
pnpm devpara iniciar o servidor de desenvolvimento do Next.js.
- Execute
- Terminal 2:
- Execute
ngrok http 3000para expor o manipulador de webhooks à internet.
- Execute
Agora, abra http://localhost:3000 e comece a criar seu agente personalizado da ElevenLabs, com a sua voz!