Conversational Agents
Conversational Agents é um canal que permite que seus usuários conversem com um agente de IA para concluir tarefas definidas por você. Você cria fluxos de trabalho conversacionais que descrevem o que o agente deve fazer pela sua marca. Por exemplo, um fluxo de trabalho pode ajudar um usuário a comprar itens com base nas preferências dele.

O Conversational Agents está atualmente em beta. Entre em contato com o gerente da sua conta Braze se tiver interesse em participar deste beta.
Antes de implantar em produção, consulte sua equipe jurídica sobre as implicações do uso de IA conversacional.
Como funciona
Um fluxo de trabalho conversacional é uma tarefa que você quer que um agente conclua. Cada fluxo de trabalho inclui um objetivo, configurações de canal, um público-alvo e etapas em linguagem natural. Em cada etapa, adicione ferramentas para que o agente possa pesquisar catálogos, definir atributos, registrar eventos ou chamar webhooks.
Depois de criar os fluxos de trabalho, consulte Configurações para definir as diretrizes da marca e o comportamento do canal. Use Visualizar uma prévia da conversa, Criar simulações e Revisar o histórico de conversas para testar a experiência e revisar as chamadas de ferramentas.
Configurar o widget de chat na web
Para exibir o widget de chat dos Agentes Conversacionais no seu site, siga as etapas abaixo no Web SDK da Braze.
Etapa 1: Configurar a autenticação do SDK
Ative a autenticação do SDK no seu app web.
Etapa 2: Instalar o Web SDK
Instale uma das seguintes opções:
| Opção | Detalhes |
|---|---|
| npm | Instale o pacote @braze/web-sdk mais recente. |
| CDN | Carregue a build conversacional: https://js.appboycdn.com/web-sdk/latest/braze.conversational.min.js |
Etapa 3: Inicializar com JavaScript fornecido pelo usuário ativado
Na sua chamada initialize, defina allowUserSuppliedJavascript: true:
braze.initialize("{YOUR_API_KEY}", {
baseUrl: "{YOUR_SDK_ENDPOINT}",
allowUserSuppliedJavascript: true
});
Substitua {YOUR_API_KEY} pela sua chave de API do Web SDK e {YOUR_SDK_ENDPOINT} pelo seu endpoint do SDK.
Etapa 4: Ativar o widget de chat
Antes de abrir uma sessão, chame braze.automaticallyManageChat():
braze.automaticallyManageChat();
braze.openSession();
Criar um fluxo de trabalho conversacional
Com um fluxo de trabalho conversacional, você define uma tarefa, escolhe canais e um público e diz ao agente o que fazer em cada etapa.
Etapa 1: Configurar os detalhes do fluxo de trabalho
Acesse Agentes > Agentes conversacionais e configure os detalhes do seu fluxo de trabalho:
- Insira um nome para o fluxo de trabalho.
- Insira um propósito que descreva o que esse fluxo de trabalho faz. O agente usa o propósito e o histórico da conversa para escolher qual fluxo de trabalho usar. Então, descreva quando o fluxo de trabalho se aplica. Por exemplo: “O usuário tem dúvidas sobre horários de eventos ou reembolsos.”
- Selecione os canais em que esse fluxo de trabalho fica ativo. Os canais compatíveis são SMS, RCS, WhatsApp e web.
- Para web, selecione em quais apps web esse fluxo de trabalho fica ativo.
- Para SMS, RCS e WhatsApp, selecione em quais grupos de inscrições esse fluxo de trabalho fica ativo.
- Selecione os Segments aos quais um usuário precisa pertencer para acessar esse fluxo de trabalho.

Os fluxos de trabalho não estão vinculados a um Canvas. Um grupo de inscrições ou app web pode ter vários fluxos de trabalho, e o agente alterna entre eles durante uma conversa. Para limitar um fluxo de trabalho aos usuários que receberam uma mensagem específica de um Canvas, crie um Segment com esses usuários e selecione-o para o fluxo de trabalho. Para testar primeiro com um público pequeno, use um Segment com um subconjunto reduzido de usuários.
Para SMS, RCS e WhatsApp, alguns gatilhos de mensagens recebidas podem bloquear o agente. Na página Configurações, revise os gatilhos que podem bloquear agentes em cada grupo de inscrições.
Etapa 2: Escrever as etapas do fluxo de trabalho
Adicione as etapas que o agente deve seguir para concluir o fluxo de trabalho. Um fluxo de trabalho pode ter até 10 etapas. Cada etapa precisa de uma instrução, que pode ter até 5.000 caracteres.
Para etapas com um único objetivo, escreva a instrução em uma a três frases curtas. Mantenha as regras claras e termine com uma pergunta ou confirmação explícita, para que o agente saiba como formular a próxima resposta ao usuário.
Etapa 3: Adicionar ferramentas às etapas
As etapas podem incluir ferramentas que o agente usa enquanto trabalha. Nas Instruções de uma etapa, você insere ferramentas digitando /, e elas aparecem como tags na instrução. Uma etapa pode referenciar até 10 ferramentas.

Ferramentas
Você pode adicionar qualquer uma destas ferramentas a uma etapa:
| Ferramenta | Descrição |
|---|---|
| Pesquisar fontes de conhecimento | Consulte um catálogo por meio de uma fonte de conhecimento. |
| Definir atributo de fluxo de trabalho | Armazene um valor com escopo neste fluxo de trabalho. |
| Obter atributo de fluxo de trabalho | Recupere um atributo de fluxo de trabalho definido em uma etapa anterior. |
| Registrar evento personalizado | Registre um evento personalizado da Braze. |
| Definir atributo personalizado | Defina um atributo personalizado no usuário. |
| Obter atributo personalizado | Recupere um atributo personalizado do usuário. |
| Obter atributo do usuário | Recupere um campo padrão do perfil de usuário. |
| Chamar webhook | Envie uma solicitação HTTP para um endpoint externo. |
| Obter resposta do webhook | Recupere um campo extraído de uma resposta de webhook anterior. |
Pesquisar fontes de conhecimento
Use esta ferramenta para ajudar o agente a consultar e entender um catálogo da Braze. Crie fontes de conhecimento para catálogos como:
- Catálogo de produtos
- Perguntas frequentes
- Tabelas de tamanhos
Primeiro, crie a fonte de conhecimento na página Fontes de conhecimento. Depois, na caixa de texto de instruções, digite / e selecione Pesquisar fontes de conhecimento. Selecione uma ferramenta de fonte de conhecimento conversacional existente ou selecione Criar nova ferramenta de pesquisa.
Ao criar uma nova ferramenta, insira um nome e uma descrição e selecione uma fonte de conhecimento. Depois de selecionar a fonte de conhecimento, escolha quais campos o agente pode acessar.
Definir um atributo de fluxo de trabalho
Use esta ferramenta para definir um atributo que o agente pode reutilizar mais adiante no mesmo fluxo de trabalho. Os atributos de fluxo de trabalho têm escopo no fluxo de trabalho em que são definidos. Use-os como propriedades de eventos personalizados, valores de atributos personalizados e parâmetros de webhook.
Ao criar o atributo, você pode adicionar Valores permitidos, se quiser:
- Deixe os valores permitidos em branco para que o agente possa definir qualquer valor daquele tipo com base na conversa.
- Adicione valores permitidos para limitar o agente a um subconjunto definido por você. Faça isso quando ferramentas posteriores (como Chamar webhook, Registrar evento personalizado ou Definir atributo personalizado) precisarem reutilizar um valor controlado em vez de uma escolha livre do agente.
Em Instrução, digite / e selecione Definir atributo de fluxo de trabalho. Selecione um atributo de fluxo de trabalho existente ou selecione Criar novo atributo.
Ao criar um novo atributo, insira um nome e uma descrição e selecione o tipo. Depois de selecionar o tipo, adicione valores permitidos, se quiser. Cada valor permitido precisa de um valor com até 100 caracteres e uma descrição com até 250 caracteres. Os valores devem ser únicos, e um atributo pode ter até 250 valores permitidos.
Com valores permitidos, o agente escolhe um dos seus valores mesmo quando o usuário se expressa de outra forma. Por exemplo, se um atributo skin_type permite apenas dry e oily, e um usuário descreve a pele com um sinônimo de seca, o agente define dry. Sem valores permitidos, o agente escolhe um valor com base na descrição do atributo e nas instruções da etapa. Normalmente ele segue essas orientações, mas pode não seguir à risca.
Para salvar um valor controlado em um perfil de usuário, use duas ferramentas na mesma etapa:
- Use Definir atributo de fluxo de trabalho para definir o atributo depois que o usuário confirmar a resposta.
- Use Definir atributo personalizado e selecione Atributo de fluxo de trabalho como a origem do valor do atributo personalizado.
Obter um atributo de fluxo de trabalho
Use esta ferramenta para recuperar o valor de um atributo de fluxo de trabalho definido em uma etapa anterior.
Registrar um evento personalizado
Use esta ferramenta para registrar um evento personalizado da Braze. Na caixa de texto de instruções, digite / e selecione Registrar evento personalizado. Selecione uma ferramenta de registro de evento personalizado existente ou selecione Criar nova ferramenta de evento personalizado.
Ao criar uma nova ferramenta, selecione o evento personalizado e insira um nome e uma descrição. Escolha as propriedades do evento que serão enviadas com o evento personalizado. Cada propriedade de evento personalizado pode usar uma das seguintes origens:
| Origem | Descrição |
|---|---|
| Agente | O agente decide o valor com base nas instruções e na descrição da ferramenta. |
| Atributo de fluxo de trabalho | A propriedade usa um atributo de fluxo de trabalho que o agente definiu em uma etapa anterior. |
| Atributo personalizado | A propriedade usa um atributo personalizado do usuário. |
Você não precisa definir um valor para cada propriedade. Alguns tipos de propriedade não são compatíveis.
Selecione Obrigatório se a ferramenta precisar falhar quando o valor da propriedade estiver em branco.
Para enviar um usuário para um Canvas, registre um evento personalizado que o Canvas usa como propriedade de entrada.
Definir um atributo personalizado
Use esta ferramenta para definir um atributo personalizado no usuário. Na caixa de texto de instruções, digite / e selecione Definir atributo personalizado. Selecione uma ferramenta de definição de atributo personalizado existente ou selecione Criar nova ferramenta de atributo personalizado.
Ao criar uma nova ferramenta, insira um nome e uma descrição e selecione o atributo personalizado que a ferramenta deve definir. Um atributo personalizado pode usar uma das seguintes origens:
| Origem | Descrição |
|---|---|
| Agente | O agente decide o valor com base nas instruções e na descrição da ferramenta. |
| Atributo de fluxo de trabalho | O atributo do usuário usa um atributo de fluxo de trabalho que o agente definiu em uma etapa anterior. |

Os atributos personalizados são definidos de forma assíncrona. Se o agente ler um atributo personalizado logo depois de defini-lo, o valor ainda pode estar desatualizado.
Obter um atributo personalizado
Use esta ferramenta para recuperar um atributo personalizado.
Obter um atributo de usuário
Use esta ferramenta para recuperar um campo padrão do perfil de usuário. Na caixa de texto de instruções, digite uma barra (/) e selecione Obter atributo de usuário. Escolha um dos seguintes campos:
- ID externo
- ID da Braze
- Nome
- Sobrenome
- Telefone
Chamar um webhook
Use esta ferramenta para chamar um webhook. Na caixa de texto de instruções, digite / e selecione Chamar webhook. Selecione uma ferramenta de webhook existente ou selecione Criar novo webhook.
Ao criar uma nova ferramenta, insira um nome e uma descrição e adicione variáveis. As variáveis permitem incluir valores personalizados no URL, no corpo ou nos cabeçalhos do webhook.
Uma variável pode usar uma das seguintes origens:
| Origem | Descrição |
|---|---|
| Agente | O agente decide o valor com base nas instruções e na descrição. |
| Atributo de fluxo de trabalho | A variável usa um atributo de fluxo de trabalho que o agente definiu em uma etapa anterior. |
| Atributo personalizado | A variável usa um atributo personalizado do usuário. |
| Perfil de usuário | A variável usa um campo do perfil de usuário: ID externo, ID da Braze, e-mail, nome, sobrenome ou telefone. |
Depois de definir as variáveis, escolha o método de solicitação. Os seguintes métodos de solicitação são compatíveis:
GETPOSTPUTPATCHDELETE
Em seguida, insira o URL. Para usar variáveis no URL, faça referência a elas com a sintaxe {{variable_name}}. Por exemplo:
https://myurl.com/create/{{user_id}}
Depois, defina o corpo da solicitação. Deixe o corpo em branco ou insira uma string que pode incluir espaços reservados {{variable_name}}. Para a maioria das APIs, envie um corpo JSON. Por exemplo:
{
"user": {
"id": "{{external_id}}",
"favorite_color": "{{favorite_color}}",
"is_called_by_agent": true
}
}
Você também pode definir cabeçalhos usando variáveis. Para credenciais, crie credenciais de Conteúdo Conectado no dashboard e faça referência a elas nesta ferramenta.
As respostas de webhook podem ser grandes, então você pode extrair apenas os campos de que o fluxo de trabalho precisa. Crie campos de resposta com uma expressão JMESPath que aponte para um valor no corpo da resposta. O corpo da resposta precisa ser um JSON válido para que esses campos sejam extraídos com sucesso. Faça referência a esses campos mais tarde com a ferramenta Obter resposta do webhook.
Obter uma resposta de webhook
Use esta ferramenta para fazer referência a um campo de resposta de webhook extraído de uma etapa anterior de Chamar webhook.
Configurações
Configure diretrizes da marca e o comportamento dos canais para os agentes conversacionais. Acesse Agentes > Agentes conversacionais e selecione Configurações.
Diretrizes da marca
Selecione as diretrizes da marca que o agente deve seguir nas respostas. Crie e gerencie as diretrizes em Conteúdo > Diretrizes da marca e depois escolha uma aqui.
Configurações da web
Defina uma Mensagem de abertura. Essa é a primeira mensagem que os usuários veem quando iniciam uma conversa na web.
Configurações de SMS, RCS e WhatsApp
Configure o seguinte:
| Configuração | Descrição |
|---|---|
| Limite diário de turnos | O número máximo de turnos por usuário por dia nos canais de envio de mensagens. |
| Mensagem de divulgação de IA | Texto que abre a primeira resposta do agente em toda conversa por SMS, RCS e WhatsApp. Você pode reescrever o texto, mas não pode desativá-lo. Deixe o campo em branco para usar a mensagem padrão. |
| Gatilhos que podem bloquear agentes | Uma lista de gatilhos de mensagens recebidas em cada grupo de inscrições ativado em um fluxo de trabalho. Se uma mensagem recebida ativar um desses gatilhos, o agente conversacional não responde. |
Os gatilhos que podem ter prioridade incluem:
- Gatilhos de palavras-chave
- Campaigns baseadas em ação
- Entrada de Canvas baseada em ação
- Jornada de ação do Canvas
- Saída do Canvas
Prévia de uma conversa
Existem duas formas de visualizar a prévia:
- Ao editar um fluxo de trabalho salvo, visualize a prévia apenas desse fluxo de trabalho. A prévia não fica disponível até você salvar um novo fluxo de trabalho.
- Na página Configurações, visualize a prévia da experiência para um app web ou grupo de inscrições. Se quiser, selecione Incluir fluxos de trabalho em rascunho para testar fluxos de trabalho em rascunho antes de ativá-los.
Em ambos os casos, visualize a prévia como um usuário específico.

O modo de prévia não registra atributos personalizados nem eventos personalizados.
Criar simulações
Uma simulação testa os fluxos de trabalho conversacionais do seu espaço de trabalho sem um usuário real. Crie casos que descrevem um cenário e os resultados que você espera. Um usuário simulado segue esse cenário. Quando a conversa termina, um avaliador compara a conversa e as chamadas de ferramentas com esses resultados. Simule as respostas de webhook para que os casos continuem previsíveis.
Acesse Agentes > Agentes conversacionais e selecione Simulações.
Criar um caso
Na guia Casos, selecione Criar caso e configure os seguintes campos:
| Campo | Descrição |
|---|---|
| Nome do caso | Um nome exclusivo para o caso. |
| Fluxos de trabalho | Os fluxos de trabalho em que a conversa pode entrar. Selecione pelo menos um. |
| Usuário | O usuário em nome do qual a conversa é executada, no modo de teste. Pesquise por e-mail, número de telefone ou ID externo do usuário. |
| Primeira mensagem do usuário | A primeira mensagem que o usuário simulado envia. |
| O que o usuário quer, como se comporta e o que sabe | O cenário. O usuário simulado sabe apenas o que você escrever aqui. Por exemplo, um usuário frustrado com um reembolso ou um usuário que quer agendar um horário. |
| Resultados esperados | Uma afirmação verificável para cada coisa que o agente deve fazer ou dizer, como “O agente fornece ao usuário um endereço de e-mail de suporte.” Você pode adicionar até 10. |
| Respostas de webhook | Opcional. Ative Resposta simulada para um webhook e insira valores fixos a serem retornados em vez de chamar seu endpoint. |
Crie um caso para cada cenário que você quer testar, como um usuário frustrado, um usuário que quer fazer um agendamento e um usuário com uma dúvida sobre reembolso.
Executar uma simulação e analisar os resultados
Selecione Executar simulação, escolha os casos a serem executados e selecione Iniciar execução. Confira as execuções anteriores na guia Execuções.

A Braze chama qualquer webhook que um caso não simula. Para evitar chamadas aos seus endpoints, simule cada webhook usado pelos fluxos de trabalho.
Cada caso de uma execução mostra a conversa entre o usuário simulado e o agente, além de um resultado com explicação para cada resultado esperado:
- Aprovado
- Reprovado
- Inconclusivo, quando a conversa não tem evidências suficientes para uma decisão
Um caso é reprovado se qualquer resultado for reprovado. Se nenhum resultado for reprovado, mas algum for inconclusivo, o caso é inconclusivo. Caso contrário, o caso é aprovado.
Revisar histórico de conversas
Na página Agentes conversacionais, selecione Histórico de conversas. Esta página exibe conversas com usuários reais e conversas da prévia.
Use o histórico de conversas para revisar chamadas de ferramentas e confirmar que o agente se comporta como esperado.

Exemplo
A Flash & Thread, uma marca fictícia de varejo de roupas, pode usar este fluxo de trabalho de compras em duas etapas.
- Etapa 1: Pergunta ao usuário qual categoria de produto ele está procurando.
- Etapa 2: Usa a ferramenta Definir atributo do fluxo de trabalho para capturar um atributo product_category como string. Esse atributo registra a categoria de produto que o usuário informou na Etapa 1 que está procurando hoje.
