Implantar agentes personalizados

Depois de criar um agente, use esta página para saber onde e como implantá-lo na Braze. O tipo de agente que você escolhe no momento da criação — agente de Canvas ou agente de catálogo — determina onde o agente pode ser executado. Para uma introdução, consulte Braze Agents.

Tipos de agentes personalizados

Os agentes personalizados são implantados em diferentes partes da Braze, dependendo do tipo. Use a tabela a seguir para encontrar o caminho de implantação certo para o seu agente.

Você escolhe o tipo de agente ao criá-lo. Para ver as etapas de configuração, consulte Criar agentes personalizados.

Melhores práticas

Foque em casos de uso de alto valor, nos quais os agentes podem gerar o maior retorno sobre o investimento (ROI), e escolha públicos com maior probabilidade de resposta. Muitas vezes, um público menor e com alto potencial tem um desempenho melhor do que um público grande e com baixo potencial.

Para agentes de etapa do Canvas, comece com usuários que tenham sinais fortes, como pesquisas recentes, alto engajamento ou dados de perfil completos. Depois, expanda para Segments mais amplos. Para agentes de catálogo, priorize as linhas em que as colunas de entrada necessárias já estão preenchidas. Assim, cada invocação tem contexto suficiente para gerar um resultado útil.

Para testar o ROI em pequena escala antes de implementar um agente de forma ampla, use uma etapa de Jornadas experimentais. Dessa forma, apenas parte do seu público entra na ramificação que contém a etapa do agente.

Escalar após um teste bem-sucedido

Depois que um teste em pequena escala (por exemplo, uma ramificação de Jornadas experimentais) mostrar qualidade e ROI aceitáveis, planeje implementar o agente para todo o seu público-alvo (não apenas o grupo de teste), para que todos os usuários elegíveis se beneficiem.

Antes de escalar, considere o seguinte:

• Aumente o limite diário de invocações do agente no Agent Console para que ele consiga lidar com o volume total do seu público. O padrão é 250.000. Você pode aumentá-lo para até 1.000.000 (ou mais, com a ajuda do seu gerente de sucesso do cliente). Consulte Limites diários de invocação e de créditos.
• Revise a estimativa do Limite diário de custo de créditos de ação e confirme se o seu espaço de trabalho tem créditos suficientes para envios em escala total.
• Remova ou reconfigure o experimento para que todo o público-alvo entre na etapa do agente (ou promova a variante vencedora para a jornada principal).

Escalar para o público completo aumenta o consumo de créditos proporcionalmente. Após o lançamento, monitore o uso em Configurações > Faturamento > Uso de créditos > Agent Console.

Usar agentes de etapa do Canvas

Depois de criar um agente de etapa do Canvas, adicione-o a um Canvas como uma etapa de Agente para personalizar mensagens ou orientar decisões em tempo real.

Como funciona

Quando um usuário chega a uma etapa de Agente em um Canvas, a Braze envia ao seu agente os dados de entrada que você configurou. O agente processa a entrada usando o modelo e as instruções dele. Então, retorna uma saída que fica armazenada na variável de saída definida na etapa. Você pode usar essa saída para tomada de decisões, personalização ou processamento posterior.

As etapas de Agente usam variáveis de contexto do Canvas para receber o contexto relevante e gerar uma variável que pode ser usada no Canvas. Para conferir os pré-requisitos e a referência completa, consulte Etapa de Agente.

Adicionar uma etapa de Agente

Para adicionar um agente ao seu Canvas:

1. 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.
2. Selecione o agente que processa os dados nesta etapa.
3. Defina o nome da variável de saída. O tipo de dados da saída é definido no Agent Console.
4. (Opcional) Adicione valores de contexto extras para o agente consultar durante a execução. Isso pode incluir variáveis Liquid adicionais ou contexto do Canvas que você ainda não vinculou na configuração do agente. Por exemplo, valores que você só quer passar no momento do envio a partir desta etapa.
5. Teste o agente usando a prévia na etapa ou o Testar Canvas para percorrer toda a jornada do usuário.

Para conferir os tipos de dados de saída, templates Liquid e capturas de tela, consulte Etapa de Agente.

Casos de uso

Usar a saída do agente

Depois que o agente for executado, use a variável de saída no seu Canvas:

• Roteamento da jornada: Direcione usuários para diferentes jornadas do Canvas com base na resposta do agente. Use Jornadas de público ou Divisões de decisão com saídas numéricas, booleanas ou estruturadas.
• Personalização: Insira a resposta do agente diretamente em uma etapa de Mensagem usando Liquid.
• Processamento de dados de usuários: Analise e padronize os dados de usuários e, depois, armazene-os no perfil de usuário (por exemplo, com uma etapa de Atualização de usuário) ou envie-os usando um webhook.

Para ver exemplos, consulte Como funciona em Etapa de Agente.

Tratamento de erros e comportamento de fallback

As informações a seguir se aplicam aos agentes de etapa do Canvas em uma etapa de Agente.

• Se o modelo conectado retornar um erro de limite de frequência do provedor de LLM, a Braze tenta a solicitação novamente de forma contínua, usando backoff exponencial, até que a chamada tenha sucesso ou a Braze determine que ela não pode ser concluída. Então, os usuários seguem para a próxima etapa do Canvas.
• Para outras falhas (como um tempo limite esgotado ou uma chave de API inválida), a variável de saída é definida como null, a menos que o agente tenha valores de fallback configurados no Agent Console.
• Se um agente atingir o limite diário de invocações, a Braze também aplica os valores de fallback configurados, quando houver. Caso contrário, a variável de saída é definida como null.

Quando há valores de fallback configurados, a Braze os aplica em erros que não permitem nova tentativa e em falhas por limite diário. A Braze renderiza o fallback com Liquid para cada usuário e armazena o resultado na variável de saída da etapa de Agente. Sem valores de fallback, essas falhas definem a variável de saída como null. Se preferir configurar padrões específicos nas etapas de Mensagem em vez de usar fallbacks do Agent Console, você ainda pode usar valores padrão do Liquid nas etapas seguintes. Para isso, deixe os fallbacks em branco na seção Saída da configuração do agente, para que os padrões do Liquid possam ser aplicados quando o agente retornar nulo.

Erros de limite de frequência, indisponibilidade do modelo e falhas por limite diário de invocações não consomem créditos da Braze. Tempos limite esgotados consomem créditos. Consulte Quando os créditos são consumidos.

• As respostas ficam em cache para entradas idênticas e podem ser reutilizadas em invocações idênticas repetidas dentro de alguns minutos. Respostas em cache continuam contando para o total de invocações e para as invocações diárias.
• As etapas de Agente podem levar algum tempo para processar um lote grande de usuários. A Braze coloca as invocações em fila de acordo com os controles de fluxo de invocação, então os usuários podem ficar pendentes durante envios de alto volume.

Para detalhes de configuração e execução da etapa de Agente, consulte Tratamento de erros em Etapa de Agente. Para saber mais, consulte Tratamento de erros em Braze Agents.

Use agentes de catálogo

Depois de criar um agente de catálogo, aplique-o a um campo do catálogo para gerar ou calcular valores automaticamente para cada linha. O agente também é executado nas novas linhas adicionadas ao catálogo no futuro.

Como funciona

Depois do lançamento, o agente avalia cada linha e usa as colunas selecionadas como contexto para produzir um resultado. Os agentes são executados em todas as novas linhas adicionadas depois que você implanta o agente. Se você selecionou Recalcular quando as linhas do catálogo forem atualizadas, todos os valores desse campo são atualizados quando os campos de origem existentes mudarem.

Ao configurar as colunas de entrada de um agente de catálogo, ative o controle no produto que indica quais colunas selecionadas são obrigatórias antes de o agente ser invocado (os rótulos podem variar um pouco conforme o espaço de trabalho). Com esse controle ativado, escolha o subconjunto de colunas que precisa ter valores. As colunas selecionadas começam como obrigatórias por padrão, mas você pode remover as que podem ficar vazias sem bloquear o agente. O agente pula uma linha somente quando uma coluna que você manteve como obrigatória está vazia ou ausente, como um campo gender que não foi preenchido. Executar sem o contexto necessário desperdiça tokens e pode gerar resultados de baixa qualidade.

Os agentes de catálogo também respeitam as dependências entre colunas. Se a coluna D for gerada a partir das colunas B e C, o agente só é executado na coluna D de uma linha quando B e C tiverem valores nessa linha.

Você pode atualizar e editar os campos do seu catálogo que usam agentes. Para remover um agente de uma coluna, desmarque Aplicar agente de IA. Isso transforma a coluna em uma coluna sem agente, e os campos mantêm os últimos valores aplicados pelo agente na última vez em que ele foi executado no catálogo.

Referências circulares em catálogos não são compatíveis. Ou seja, o seguinte cenário não pode ocorrer:

• A coluna com agente 1 usa a coluna com agente 2 como entrada
• A coluna com agente 2 usa a coluna com agente 1 como entrada

Adicionar um agente a um campo do catálogo

Para adicionar um agente ao campo do seu catálogo:

1. No seu catálogo, adicione um novo campo.
2. Selecione Aplicar agente de IA.
3. Atribua um agente a esse campo.
4. Selecione quais colunas devem ser enviadas como entrada. Se nenhuma for selecionada, o agente terá acesso a todas as colunas do catálogo.
5. (Opcional) Ative Executar somente quando as colunas obrigatórias tiverem valores para pular linhas em que uma ou mais colunas de entrada selecionadas estejam vazias. Com essa opção ativada, selecione quais colunas de entrada precisam estar preenchidas para o agente ser executado. Todas as colunas selecionadas começam como obrigatórias por padrão, mas você pode remover as que podem ficar vazias sem bloquear uma execução.
6. Decida se o agente deve recalcular os campos quando as linhas do catálogo forem atualizadas. Se você não selecionar essa opção, o agente será executado apenas uma vez por linha.
7. Selecione Adicionar campos para implantar o agente e revisar as estimativas de custo. O modal Estimativa de custo mostra quantas vezes o agente será executado nesse catálogo, o que equivale aproximadamente ao número total de linhas. Para continuar, selecione Confirmar.

Melhores práticas para agentes de catálogo

Planeje de quais colunas o agente precisa antes de aplicá-lo a um campo do catálogo. Depois de ativar os controles de entradas obrigatórias para o campo, selecione as colunas com os dados que o agente deve ler. Em seguida, desmarque qualquer coluna que possa ficar vazia sem bloquear uma execução. O agente pula uma linha somente quando uma coluna que você manteve como obrigatória está vazia.

Não deixe uma coluna marcada como obrigatória se você espera que ela fique vazia em algumas linhas e ainda quer que o agente seja executado. Nesse caso, remova-a do conjunto de colunas obrigatórias. Pular linhas incompletas evita o uso incorreto de tokens e mantém a qualidade dos resultados.

Casos de uso

Definir campos de resposta

Se o seu agente usa campos como formato de saída, você pode selecionar o campo correspondente do agente em Campo de resposta para usá-lo no campo do catálogo.

Digamos que você tenha um agente que adiciona descrições de produtos a um catálogo, com os seguintes campos para estruturar o formato de saída:

Você pode adicionar um campo chamado product_description a um catálogo e selecionar description como Campo de resposta para preencher a coluna com as descrições do agente.

Você também pode sobrescrever manualmente a célula gerada pelo agente selecionando Editar item e atualizando a descrição gerada com suas edições. Para voltar à descrição gerada pelo agente, selecione o símbolo de atualização na célula.

Tratamento de erros

• Se o provedor de LLM retornar um erro de limite de frequência, a Braze tenta a solicitação novamente de forma contínua usando backoff exponencial até que a chamada seja bem-sucedida ou até determinar que ela não pode ser concluída.
• Em outras falhas (como tempo limite esgotado ou chave de API inválida), o valor do campo do catálogo não é atualizado. Os agentes de catálogo não permitem configurar valores de fallback no Agent Console.
• Você pode revisar os logs do agente para ver detalhes sobre as execuções que falharam.
• Os agentes de catálogo processam valores de entrada de até 25 KB por linha.

Monitore seu agente

O monitoramento funciona da mesma forma, seja o seu agente executado no Canvas ou em catálogos.

Na seção Uso do seu agente, você pode consultar onde o agente está sendo usado ativamente em catálogos e Canvas e navegar até esses locais.

Na seção Registros do seu agente, você pode monitorar as chamadas reais do agente que ocorrem nos seus Canvas e catálogos. É possível filtrar por informações como intervalo de datas, resultado (sucesso ou falha) ou local da chamada. Você também pode selecionar Exportar CSV para exportar apenas os registros exibidos na página atual.

Dica

Você também pode monitorar os erros de limite diário de invocações no Registro de atividades de mensagens.

Selecione Visualizar em uma chamada específica do agente para ver a entrada, a saída e o ID do usuário.

Para agentes em etapas do Canvas, os registros incluem uma seção Saída de fallback, que mostra qualquer saída de fallback usada quando a invocação apresentou erro.

Usar o Currents

Você também pode usar estes eventos do Currents para acessar os esquemas de registro do Kafka:

• Eventos de agente executado
• Eventos de invocação de ferramenta

Consulte o Glossário de eventos de engajamento com mensagem para saber mais.

Artigos relacionados

• Etapa do agente
• Referência para agentes
• Perguntas frequentes