Etapa de agente
A etapa de agente permite adicionar decisões baseadas em IA e geração de conteúdo diretamente no fluxo de trabalho do seu Canvas. Para informações mais gerais, consulte Agentes da Braze.

Pré-requisitos
As etapas de agente usam variáveis de contexto do Canvas para ingerir o contexto relevante e gerar como saída uma variável que pode ser usada no Canvas.
Como funciona
Quando um usuário chega a uma etapa do agente em um Canvas, a Braze envia os dados de entrada configurados (contexto completo ou campos selecionados) para o agente escolhido. Em seguida, o agente processa a entrada usando seu modelo e suas instruções e retorna uma saída. Essa saída fica armazenada na variável de saída que você definiu na etapa.
Depois, você pode usar essa variável de três maneiras principais:
- Tomada de decisões: Direcione os usuários para diferentes jornadas do Canvas com base na resposta do agente. Por exemplo, um agente de pontuação de leads pode retornar a categoria de lead “Pronto para vendas”, “Qualificado para marketing” ou “Desqualificado”. Você pode usar essa atribuição para disparar um alerta no Slack ou uma mensagem automatizada para leads “Pronto para vendas” e remover os leads “Desqualificado” da jornada.
- Personalização: Insira a resposta do agente diretamente em uma mensagem. Por exemplo, um agente pode analisar o feedback de clientes e gerar um e-mail de acompanhamento empático que faça referência ao comentário do cliente e sugira uma solução.
- Processamento de dados de usuários: Analise e padronize seus dados de usuários e, depois, armazene-os no perfil do usuário ou envie-os por meio de um webhook. Por exemplo, um agente pode retornar uma pontuação de sentimento ou uma atribuição de afinidade com produtos. Você pode armazenar esses dados em um perfil de usuário para uso futuro.
Criação de uma etapa de agente
Etapa 1: Adicione uma etapa
Arraste e solte o componente Agente da barra lateral ou selecione o botão de adição na parte inferior de uma etapa e selecione Agente.
Etapa 2: Escolha seu agente
Selecione o agente que vai processar os dados nesta etapa. Para orientações de configuração, consulte Criar agentes personalizados.
Na lista de agentes, cada agente aparece com seu limite diário de invocações. Passe o mouse sobre o limite para ver o progresso de hoje em relação a ele, incluindo a porcentagem usada e o número de invocações feitas hoje em comparação com o limite.

Etapa 3: Defina a saída do seu agente
As saídas do agente são chamadas de “variáveis de saída” e ficam armazenadas em uma variável de contexto para facilitar o acesso. Para definir a variável de saída, dê um nome a ela.
O tipo de dado da variável de saída é definido no Agent Console. As saídas do agente podem ser salvas como strings, números, booleanos ou objetos. Isso as torna flexíveis tanto para personalização de texto quanto para lógica condicional no seu Canvas. Veja alguns usos comuns de cada tipo:
| Tipo de dado | Usos comuns |
|---|---|
| String | Personalização de mensagens (linhas de assunto, textos, respostas) |
| Número | Pontuação, limites, direcionamento em Jornadas de público |
| Booleano | Ramificação Sim/Não em Divisões de decisão |
| Objeto | Aproveite um ou mais dos tipos de dados anteriores desta seção com uma única chamada de LLM em uma estrutura de dados previsível |
Você pode usar uma variável de saída em todo o Canvas com a mesma sintaxe de modelo que usaria com uma variável de contexto. Use o filtro de Segment Variável de contexto ou insira as respostas do agente diretamente com Liquid: {{context.${response_variable_name}}} .
Para usar uma propriedade específica de uma variável de saída do tipo objeto, use a notação de ponto para acessar essa propriedade com Liquid: {{context.${response_variable_name}.field_name}}

Etapa 4: Adicione instruções opcionais para a etapa
Você pode incluir instruções opcionais com qualquer informação que seu agente precise saber e que seja específica desta etapa, sem já estar coberta nas instruções principais do agente.
Você pode inserir quaisquer valores com modelo Liquid que normalmente usaria em um Canvas. As instruções da etapa não podem incluir abort_message.
Etapa 5: Teste o agente
Você pode testar uma etapa de agente de duas maneiras:
Prévia na etapa (criador de Canvas): Depois de configurar a etapa, use a prévia da etapa para ver a saída do agente para um usuário aleatório, um usuário existente ou um usuário personalizado. Isso testa a etapa de forma isolada, sem percorrer toda a jornada do Canvas.
Testar Canvas (jornada completa): Selecione Testar Canvas no rodapé do Canvas para visualizar a jornada do usuário de ponta a ponta. Quando o teste chega à sua etapa de agente, a Braze pergunta Deseja executar o agente “{agentName}”?
- Selecione Sim para adicionar contexto, se quiser, e depois selecione Simular resposta para invocar o agente para o usuário da prévia. Você pode descrever entradas de exemplo em linguagem simples (por exemplo, o conteúdo do carrinho ou o texto de uma mensagem) para complementar o perfil do usuário teste e qualquer contexto do Canvas já definido nas etapas anteriores.
- Selecione Não para pular a invocação em tempo real e usar a saída de fallback configurada para o agente no Agent Console.
As invocações feitas com Simular resposta contam para o limite diário de invocações do agente e aparecem na guia Logs do agente. Para conhecer o comportamento completo de Testar Canvas, consulte Prévia das jornadas do usuário.

Tratamento de erros
Para saber como a Braze lida com falhas de agentes, erros de limite de frequência e controles de fluxo de invocação, consulte Tratamento de erros e comportamento de fallback em Implantar agentes e Tratamento de erros em Agentes da Braze.
- Se o modelo conectado retornar um erro de limite de frequência do provedor de LLM, a Braze tenta novamente a solicitação de forma contínua usando backoff exponencial até que a chamada seja bem-sucedida ou a Braze determine que ela não pode ser concluída; os usuários então avançam para a próxima etapa do Canvas.
- Para outras falhas (como erro de timeout ou chave de API inválida), ou quando um agente atinge seu limite diário de invocações, a variável de saída é definida como
null, a menos que o agente tenha valores de fallback configurados no Console do agente. Quando valores de fallback estão configurados, a Braze renderiza o fallback com Liquid por usuário e armazena o resultado na variável de saída, inclusive quando o limite diário bloqueia uma invocação. - Se você não configurar valores de fallback, use valores padrão de Liquid nas etapas de mensagem subsequentes para lidar com saídas nulas. Por exemplo, no modal Add Personalization, você pode inserir um valor padrão de Liquid como
{{context.${response_variable_name}.push_title | default: 'Hello friend!'}}ou{{context.${response_variable_name}.push_body | default: 'Open our app to get your prize!'}}. - Se a saída de fallback chamar
abort_messagepara um usuário, a Braze trata esse usuário como se nenhum fallback estivesse configurado. Quando o agente é bem-sucedido, o fallback não é usado, então uma chamadaabort_messageno fallback não tem efeito. - As respostas são armazenadas em cache para entradas idênticas e podem ser reutilizadas para invocações idênticas repetidas dentro de alguns minutos.
- Respostas que usam valores em cache ainda contam para o total e as invocações diárias.
- As etapas de agente podem levar tempo para processar um grande lote de usuários. A Braze enfileira as invocações de acordo com os controles de fluxo de invocação, então os usuários podem permanecer pendentes durante envios de alto volume. Verifique seus registros para confirmar que as invocações estão acontecendo.
Análise de dados
Use as métricas a seguir para acompanhar o desempenho das suas etapas do agente:
| Métrica | Descrição |
|---|---|
| Entrou | O número de vezes que os usuários entraram na etapa do agente. |
| Prosseguiu para a próxima etapa | O número de usuários que seguiram para a próxima etapa do fluxo depois de passar pela etapa do agente. |
| Saiu do Canvas | O número de usuários que saíram do Canvas depois de passar pela etapa do agente. |
Melhores práticas
Divida as tarefas entre agentes em casos de uso complexos
Se perceber que um agente está com dificuldade para lidar com a complexidade das tarefas que você pede, divida o trabalho entre mais de uma etapa de Agente. Quando um único prompt mistura limpeza de dados, lógica de direcionamento e redação completa da mensagem, esses objetivos competem entre si. Então, a qualidade do resultado pode variar.
O padrão a seguir usa três agentes em um exemplo de viagem: alguém pesquisou no seu app recentemente, mas não fez a reserva, e você quer um texto de redirecionamento que incentive essa pessoa a finalizar a compra.
- O agente 1 resume o contexto do Canvas. Ele lê campos como nível de fidelidade, última cidade pesquisada e comportamento de pesquisa com alta intenção de compra. Depois, retorna um resumo curto e estruturado como uma variável de saída que as etapas seguintes podem reutilizar.
- O agente 2 retorna um valor de direcionamento que seu Canvas pode usar para criar ramificações. Use um número, um booleano ou um objeto estruturado para que a saída corresponda à forma como você cria as ramificações. Mapeie esse valor para uma etapa de Jornadas do público ou Divisão de decisão. Por exemplo, considere jornadas separadas para mensagens focadas em fidelidade e mensagens focadas em ofertas.
- O agente 3 redige o texto gerado da mensagem apenas nas ramificações em que você quiser. Passe o resumo do agente 1 (e qualquer contexto específico da ramificação) para que esse agente se concentre no tom e nos limites do canal, em vez de normalizar entradas e escolher a estratégia no mesmo prompt.
Use a etapa da jornada experimental para testar jornadas com agentes em pequena escala
Para testar o desempenho e o consumo de créditos do seu agente em comparação com suas jornadas existentes, adicione uma etapa de Jornadas experimentais para que apenas parte do seu público entre na ramificação que contém sua etapa de Agente.
Por exemplo, você pode começar enviando alguns milhares de usuários por dia para uma jornada com o agente e enviar o restante para uma jornada de controle ou uma jornada sem o agente. Colete dados por 1 a 2 semanas e compare os indicadores chave de desempenho (KPIs), as contramétricas e o consumo de créditos do agente entre as jornadas. Assim, você ganha confiança e comprova o ROI antes de aumentar o tráfego para a ramificação com o agente, além de limitar o consumo de invocações durante esse processo.
Perguntas frequentes
Quando devo usar uma etapa do agente?
Em geral, recomendamos usar uma etapa do agente quando você quer alimentar um LLM com dados contextuais específicos e deixar que ele atribua, de forma autônoma e inteligente, uma variável de contexto do Canvas em uma escala impossível para humanos.
Digamos que você esteja enviando uma mensagem personalizada para recomendar um novo sabor de sorvete a um usuário que já pediu chocolate e morango. Veja a diferença entre usar uma etapa do agente e as recomendações de itens de IA:
- Etapa do agente: Usa LLMs para tomar uma decisão qualitativa sobre o que o usuário pode querer, com base nas instruções e nos pontos de dados de contexto fornecidos ao agente. Neste exemplo, uma etapa do agente pode recomendar um novo sabor considerando a possibilidade de o usuário querer experimentar sabores diferentes.
- Recomendações de itens de IA: Usam modelos de machine learning para prever os produtos que um usuário tem mais probabilidade de querer, com base em eventos anteriores do usuário, como compras. Neste exemplo, as recomendações de itens de IA sugeririam um sabor (baunilha) com base nos dois pedidos anteriores do usuário (chocolate e morango) e em como eles se comparam aos comportamentos de outros usuários no seu espaço de trabalho.
Como as etapas do agente usam os dados de entrada?
Uma etapa do agente analisa os dados de contexto que o agente está configurado para usar, além de quaisquer instruções opcionais da etapa que você adicionar a ela.