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, veja Braze Agents.

Tipos de agentes personalizados

Agentes personalizados são implantados em diferentes partes da Braze dependendo do tipo. Use a tabela abaixo para encontrar o caminho de implantação correto para o seu agente.

Você seleciona o tipo de agente no Console do agente ao criar o agente. Para as etapas de configuração, consulte Criar agentes personalizados.

Práticas recomendadas

Priorize casos de uso de alto valor em que os agentes possam gerar o maior retorno sobre o investimento (ROI) e escolha públicos com maior probabilidade de resposta. Um público menor e com alta oportunidade frequentemente supera um público grande com baixa oportunidade.

Para agentes de Canvas, comece com usuários que apresentam sinais fortes — como buscas recentes, alto engajamento ou dados de perfil ricos — antes de expandir para segmentos mais amplos. Para agentes de catálogo, priorize linhas em que as colunas de entrada necessárias já estejam preenchidas, para que cada invocação tenha contexto suficiente para produzir uma saída útil.

Para testar o ROI em pequena escala antes de expandir um agente amplamente, use uma etapa de Jornadas do experimento para que apenas parte do seu público entre na ramificação que contém a etapa de agente.

Usar agentes de etapa do Canvas

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

Como funciona

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

As etapas de agente usam variáveis de contexto do Canvas para ingerir contexto relevante e gerar uma variável que pode ser usada no Canvas. Para pré-requisitos e uma 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 dados nesta etapa.
3. Defina o nome da variável de saída. O tipo de dado de saída é definido no Console do agente.
4. (Opcional) Adicione valores de contexto adicionais para o agente consultar durante a execução. Isso pode incluir variáveis Liquid extras ou contexto do Canvas que você ainda não vinculou na configuração do agente — por exemplo, valores que você deseja passar apenas no momento do envio a partir desta etapa.
5. Teste e visualize a saída do agente na pré-visualização da etapa.

Para 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 é executado, use a variável de saída no seu Canvas:

• Roteamento de jornada: Direcione usuários por diferentes jornadas do Canvas com base na resposta do agente. Use Jornadas do 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 dados de usuários e, em seguida, armazene-os no perfil do usuário (por exemplo, com uma etapa de Atualização de usuário) ou envie-os usando um webhook.

Para exemplos, consulte Como funciona na Etapa de agente.

Tratamento de erros e comportamento de fallback

O seguinte se aplica a agentes de etapa do Canvas em uma Etapa de agente.

• Se o modelo conectado retornar um erro de limite de taxa do provedor de LLM, a Braze tenta novamente a solicitação continuamente usando backoff exponencial até que a chamada seja bem-sucedida ou a Braze determine que não pode ser concluída; os usuários então prosseguem para a próxima etapa do Canvas.
• Para outras falhas (como timeout ou 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 Console do agente.
• Se um agente atingir seu limite diário de invocações, a Braze também aplica os valores de fallback configurados quando presentes; caso contrário, a variável de saída é definida como null.

Quando valores de fallback estão configurados, a Braze os aplica para erros não recuperáveis e para falhas de limite diário. A Braze renderiza o fallback com Liquid por 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 você preferir configurar valores padrão específicos da etapa em etapas de Mensagem em vez de fallbacks do Console do agente, ainda pode usar valores padrão de Liquid posteriormente. Para isso, deixe os fallbacks em branco na seção Saída da configuração do agente para que os valores padrão de Liquid possam ser aplicados quando o agente retornar null.

• 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 em cache ainda contam para o total de invocações e invocações diárias.
• As etapas de agente podem levar tempo para processar um grande lote de usuários. A Braze enfileira 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.

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

Usar agentes de catálogo

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

Como funciona

Após o lançamento, o agente executa e avalia cada linha, usando as colunas selecionadas como contexto para produzir uma saída. Os agentes são executados em todas as novas linhas adicionadas após a implantação do agente. Se você selecionou Recalculate when catalog rows update, todos os valores desse campo serão atualizados quando os campos de origem existentes mudarem.

Ao configurar colunas de entrada para um agente de catálogo, ative o controle no produto que marca quais colunas selecionadas são obrigatórias para execução antes que o agente seja invocado (os rótulos podem variar ligeiramente por espaço de trabalho). Com esse controle ativado, escolha o subconjunto de colunas que devem conter valores — as colunas selecionadas começam como obrigatórias por padrão, mas você pode remover colunas que podem ficar vazias sem bloquear o agente. O agente pula uma linha apenas quando uma coluna que você deixou como obrigatória está em branco ou ausente — por exemplo, um campo gender que ainda não foi preenchido. Executar sem o contexto obrigatório desperdiça tokens e pode produzir saídas de baixa qualidade.

Os agentes de catálogo também respeitam dependências entre colunas. Se a coluna D é gerada a partir das colunas B e C, o agente não executa na coluna D para uma linha até que B e C contenham valores para essa linha.

Você pode atualizar e editar os campos do catálogo que usam agentes. Para remover um agente de uma coluna, desmarque Apply AI agent. Isso reverte a coluna para uma coluna não agente, e os campos mantêm os últimos valores que o agente aplicou na última execução no catálogo.

Referências circulares em catálogos não são suportadas. Portanto, o seguinte cenário não pode ocorrer:

• A Coluna Agente 1 usa a Coluna Agente 2 como entrada
• A Coluna Agente 2 usa a Coluna Agente 1 como entrada

Adicionar um agente a um campo de catálogo

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

1. No seu catálogo, adicione um novo campo.
2. Selecione Apply AI agent.
3. Atribua um agente a este campo.
4. Selecione quais colunas devem ser passadas como entrada. Se nenhuma for selecionada, o agente terá acesso a todas as colunas do catálogo.
5. (Opcional) Ative Only run when required columns have values para pular linhas em que uma ou mais colunas de entrada selecionadas estejam em branco. Quando essa opção está ativada, selecione quais das colunas de entrada devem estar preenchidas para que o agente execute — todas as colunas selecionadas começam como obrigatórias por padrão, mas você pode remover qualquer uma que possa ficar vazia sem bloquear a execução.
6. Decida se o agente deve recalcular os campos quando as linhas do catálogo forem atualizadas. Se você não selecionar esta opção, o agente será executado apenas uma vez por linha.
7. Selecione Add fields para implantar o agente e revisar as estimativas de custo. O modal Cost estimation mostra quantas vezes o agente será executado neste catálogo, aproximadamente igual ao número total de linhas. Para continuar, selecione Confirm.

Práticas recomendadas para agentes de catálogo

Planeje quais colunas o agente precisa antes de aplicá-lo a um campo de catálogo. Depois de ativar os controles de entrada obrigatória para o campo, selecione as colunas que contêm os dados que o agente deve ler e, em seguida, desmarque qualquer coluna que possa ficar vazia sem bloquear a execução. O agente pula uma linha apenas quando uma coluna que você deixou marcada como obrigatória está em branco.

Não deixe uma coluna marcada como obrigatória se você espera que ela fique vazia para algumas linhas e ainda deseja que o agente execute — remova-a do conjunto obrigatório. Pular linhas incompletas evita o uso incorreto de tokens e mantém a qualidade da saída alta.

Casos de uso

Definir campos de resposta

Se o seu agente usar campos como formato de saída, você pode selecionar, no campo Response Field, o campo correspondente do agente para usar 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 o Response Field para preencher a coluna com as descrições do agente.

Você também pode substituir manualmente a célula gerada pelo agente selecionando Edit Item e atualizando a descrição gerada pelo agente com suas edições. Para reverter à descrição gerada pelo agente, selecione o símbolo de atualizar na célula.

Tratamento de erros

• Invocações de catálogo com falha não são tentadas novamente, incluindo quando o provedor de LLM retorna um erro de limite de taxa.
• Se a chamada de API para o provedor do modelo fundamental retornar qualquer outro erro, como um erro de chave de API inválida, o valor do campo não é atualizado. Agentes de catálogo não suportam a configuração de valores de fallback no Console do agente.
• Você pode revisar os registros do agente para ver detalhes sobre execuções com falha.
• Agentes de catálogo estão limitados a processar valores de entrada de até 25 KB por linha.

Monitore seu agente

O monitoramento funciona da mesma forma, independentemente de o agente ser executado no Canvas ou em catálogos.

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

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

Dica

Você também pode monitorar erros de limite de invocação diária no Registro de atividades de envio de mensagem.

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

Use o Currents

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

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

Consulte o glossário de eventos de engajamento com mensagem para mais detalhes.

Artigos relacionados

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