Referência para agentes

Ao criar agentes personalizados, consulte este artigo para mais informações sobre configurações importantes, como instruções e esquemas de saída. Para a configuração passo a passo, veja Criar agentes personalizados. Para uma introdução, veja Braze Agents e Perguntas frequentes.

Modelos

Ao configurar um agente, você pode escolher o modelo que ele usa para gerar respostas. Há duas opções: usar um modelo da Braze ou trazer sua própria chave de API.

Importante

O modelo Auto da Braze é otimizado para modelos cujas capacidades de raciocínio são suficientes para executar tarefas como busca em catálogos e pertencimento a Segments. Ao usar outros modelos, recomendamos testar para confirmar que o modelo funciona bem para o seu caso de uso. Pode ser necessário ajustar suas instruções para fornecer diferentes níveis de detalhamento ou raciocínio passo a passo a modelos com diferentes velocidades e capacidades.

Opção 1: Usar um modelo da Braze

Esta é a opção mais simples, sem necessidade de configuração adicional. A Braze fornece acesso a modelos de linguagem de grande porte (LLMs) diretamente. Para usar esta opção, selecione Auto, que utiliza modelos Gemini.

Importante

Se você não vir Braze Auto como opção no menu suspenso Model ao criar um agente, entre em contato com seu CSM para saber como se tornar elegível para usar o modelo Braze Auto.

Opção 2: Trazer sua própria chave de API

Com esta opção, você pode conectar sua conta da Braze a provedores como OpenAI, Anthropic ou Google Gemini. Se você trouxer sua própria chave de API de um provedor de LLM, os custos de tokens são cobrados diretamente pelo seu provedor, não pela Braze.

Recomendamos testar rotineiramente os modelos mais recentes, pois modelos legados podem ser descontinuados ou depreciados após alguns meses. Certifique-se de ter créditos suficientes com seu provedor para executar seus agentes em escala. Você também pode se inscrever para receber notificações do Agent Console em Preferências de notificação para ser alertado quando a Braze detectar que um modelo não está mais disponível ou encontrar problemas de cobrança com seu provedor de LLM.

Para configurar:

1. Acesse Partner Integrations > Technology Partners e encontre seu provedor.
2. Insira sua chave de API do provedor.
3. Selecione Save.

Então, você pode retornar ao seu agente e selecionar seu modelo.

Quando você usa um LLM fornecido pela Braze, os provedores de tal modelo atuarão como subprocessadores da Braze, sujeitos aos termos do Adendo de Processamento de Dados (DPA) entre você e a Braze. Se você optar por trazer sua própria chave de API, o provedor da sua assinatura de LLM é considerado um Provedor Terceiro sob o contrato entre você e a Braze.

Níveis de raciocínio

Alguns provedores de LLM podem permitir que você ajuste o nível de raciocínio de um modelo selecionado. Os níveis de raciocínio definem a amplitude de pensamento que o modelo usa antes de responder — desde respostas rápidas e diretas até cadeias mais longas de raciocínio. Isso afeta a qualidade da resposta, a latência e o uso de tokens.

Recomendamos começar com Mínimo e testar as respostas do seu agente. Então, você pode ajustar o nível de raciocínio para Baixo ou Médio se perceber que o agente está tendo dificuldade em fornecer respostas precisas. Em casos raros, um nível de raciocínio Alto pode ser necessário, embora usar esse nível possa resultar em altos custos de tokens e tempos de resposta mais longos ou maior risco de erros de timeout. Se seu agente está tendo dificuldade em equilibrar raciocínio com múltiplas etapas e tempos de resposta razoáveis, considere dividir seu caso de uso em mais de um agente que possam trabalhar juntos em um Canvas ou catálogo.

A Braze usa os mesmos intervalos de IP para chamadas LLM de saída que para Connected Content. Os intervalos estão listados na lista de IPs permitidos do Connected Content. Se seu provedor suporta lista de IPs permitidos, você pode restringir a chave a esses intervalos para que apenas a Braze possa usá-la.

Importante

Quando você usa um LLM fornecido pela Braze, os provedores de tal modelo atuarão como subprocessadores da Braze, sujeitos aos termos do Adendo de Processamento de Dados (DPA) entre você e a Braze. Se você optar por trazer sua própria chave de API, o provedor da sua assinatura de LLM é considerado um Provedor Terceiro sob o contrato entre você e a Braze.

Determinar qual modelo usar

Cada provedor de LLM tem uma combinação ligeiramente diferente de capacidades de modelo, custos e níveis de raciocínio. Aqui estão algumas diretrizes gerais e práticas recomendadas:

• Para eficiência de custo, priorize testar modelos com menor custo de token antes dos modelos com maior custo. Ajuste para modelos mais caros apenas se os modelos de menor custo estiverem tendo dificuldade com o caso de uso ou gerando resultados inconsistentes ou imprecisos.
• Para eficiência de velocidade e desempenho, priorize testar níveis de raciocínio mais baixos antes dos mais altos. Ajuste para níveis de raciocínio mais altos apenas se os níveis mais baixos estiverem tendo dificuldade com o caso de uso ou gerando resultados inconsistentes ou imprecisos.
• Se modelos de menor custo ou níveis de raciocínio mais baixos estiverem tendo dificuldade com o caso de uso ou gerando resultados inconsistentes ou imprecisos, considere ajustar para modelos de maior custo ou níveis de raciocínio mais altos.
• Durante os testes, certifique-se de equilibrar a confiabilidade e a precisão com o uso de tokens e a duração da invocação.
• Cada caso de uso pode ter um modelo e nível de raciocínio ideais diferentes. Recomendamos testar exaustivamente para verificar a qualidade consistente sem timeouts.

Controles de fluxo de invocação

Os seguintes controles de fluxo de invocação se aplicam por espaço de trabalho:

• Modelo da Braze: 5.000 invocações por minuto
• Trazendo sua própria chave de API: 5.000 invocações por minuto

Quando muitos usuários entram em uma etapa do agente ao mesmo tempo, a Braze enfileira as invocações de acordo com esses limites, então o processamento pode levar mais tempo durante envios de alto volume.

Limites diários de invocação e créditos

Cada agente tem um limite diário de invocação (padrão 250.000; máximo 1.000.000, a menos que seu contrato permita valores maiores). Cada invocação (incluindo prévias no Agent Console e execuções de Test Canvas que usam Simulate response) conta para esse limite.

No Agent Console, o Daily action credit cost limit estima o máximo de créditos que um agente pode consumir por dia. A Braze multiplica a proporção de créditos por invocação do seu espaço de trabalho para o modelo selecionado pelo limite diário de invocação.

Quando os créditos são consumidos

A Braze cobra créditos apenas para invocações que concluem o processamento. Os créditos não são consumidos quando uma invocação falha por causa de:

• Um erro de limite de frequência do provedor de LLM (incluindo tentativas que eventualmente falham)
• O modelo selecionado estar indisponível
• O agente atingir seu limite diário de invocação

Os créditos são consumidos quando uma invocação atinge o timeout, mesmo que o agente não retorne uma saída utilizável.

Monitorar o uso de créditos

Acesse Settings > Billing > Credits Usage > Agent Console para ver o consumo de créditos, contagem de invocações e proporções de créditos por agente.

As proporções de créditos vêm do seu contrato e aparecem no dashboard Credits Usage (guia Credit Ratios e guia Agent Console). A estimativa é atualizada quando você altera o modelo ou o limite de invocação.

Para gerenciar gastos, reduza o limite diário de invocação. Para modelos BYO (traga sua própria chave), você também pode escolher um modelo de menor custo ou reduzir o nível de raciocínio para diminuir os custos de tokens do provedor. O Braze Auto não suporta ajuste do nível de raciocínio.

Erros de limite de frequência

Se o provedor de LLM retornar um erro de limite de frequência durante uma invocação de Canvas Step Agent ou Catalog Agent, a Braze tenta novamente a solicitação continuamente usando backoff exponencial até que a chamada seja bem-sucedida ou a Braze determine que ela não pode ser concluída.

Quando as tentativas do Canvas ou catálogo se esgotam, o painel de detalhes de Logs mostra Error e a mensagem do provedor (como Rate limit exceeded) em Output. As tentativas são visíveis nos logs, incluindo a primeira invocação, independentemente de seu eventual sucesso ou falha. Para um determinado usuário, se forem necessárias quatro tentativas para finalmente obter sucesso, você pode buscar o ID do usuário e ver todas as cinco (original mais quatro tentativas) em Logs, e a original mais as três primeiras tentativas mostrarão Error com Rate limit exceeded.

Erros de limite de frequência não consomem créditos da Braze, incluindo tentativas falhadas exibidas em Logs.

Instruções de escrita

Instruções são as regras ou diretrizes que você dá ao agente (prompt de sistema). Elas definem como o agente deve se comportar cada vez que é executado. As instruções de sistema podem ter até 25 KB.

Se você criou seu agente com o BrazeAI Operator usando um modelo inicial, revise as instruções pré-preenchidas e edite conforme necessário.

Aqui estão algumas práticas recomendadas gerais para começar a criar seus prompts:

1. Comece com o objetivo final em mente. Declare a meta primeiro.
2. Dê ao modelo um papel ou persona (“Você é um …”).
3. Defina contexto e restrições claras (público, comprimento, tom, formato).
4. Peça estrutura (“Retorne JSON/lista com marcadores/tabela…”).
5. Mostre, não diga. Inclua alguns exemplos de alta qualidade.
6. Divida tarefas complexas em etapas ordenadas (“Etapa 1… Etapa 2…”).
7. Incentive o raciocínio (“Pense nas etapas internamente, depois forneça uma resposta final concisa” ou “explique brevemente sua decisão”).
8. Teste, inspecione e itere. Pequenos ajustes podem levar a grandes ganhos de qualidade.
9. Lide com os casos extremos, adicione proteções e instruções de recusa.
10. Meça e documente o que funciona internamente para reutilização e escalabilidade.

Exemplos

Para configurações iniciais no Agent Console, consulte Modelos de agentes criados com o Operator.

Para exemplos completos de instruções que você pode copiar ou adaptar, consulte a biblioteca de casos de uso para Braze Agents.

Usando Liquid

Incluir Liquid nas instruções do seu agente pode adicionar uma camada extra de personalização na resposta. Você pode especificar a variável Liquid exata que o agente recebe e incluí-la no contexto do seu prompt. Por exemplo, em vez de escrever explicitamente “nome”, você pode usar o snippet Liquid {{${first_name}}}:

1

Tell a one-paragraph short story about this user, integrating their {{${first_name}}}, {{${last_name}}}, and {{${city}}}. Also integrate any context you receive about how they are currently thinking, feeling, or doing. For example, you may receive {{context.${current_emotion}}}, which is the user's current emotion. You should work that into the story.

Na seção Logs do Agent Console, você pode revisar os detalhes de entrada e saída do agente para entender qual valor é renderizado a partir do Liquid.

Quais dados os agentes recebem

O contexto do agente não é uma memória conversacional aberta. Ao contrário de um assistente de chat, um agente só enxerga os dados que você passa explicitamente no momento da invocação — ele não navega por perfis de usuário, infere campos ausentes ou avisa quando informações obrigatórias estão faltando.

Projete cada agente como um pipeline deliberado de entrada-para-saída. Conecte cada ponto de dados que o agente precisa usando um ou mais dos seguintes métodos:

1. Liquid nas instruções: Use templates de atributos de usuário ({{${first_name}}}) e variáveis de contexto do Canvas ({{context.${variable_name}}}) diretamente no prompt do agente.
2. + Agent context: Selecione catálogos, pertencimento a Segments, diretrizes de marca, All Canvas Context ou dados de interação do usuário no Agent Console.
3. Etapas de contexto: Defina ou atualize variáveis context.* a montante no Canvas antes de uma etapa de agente ser executada.
4. Contexto adicional na etapa do agente: Passe quaisquer valores adicionais com template Liquid que ainda não foram especificados por outros métodos ao agente no momento do envio a partir da configuração da etapa.

Certifique-se de usar template Liquid dessas variáveis de contexto nas instruções do agente ou selecionar Add All Canvas Context. Se um valor não for passado por um desses canais, o agente não o receberá. Liste as entradas necessárias nas suas instruções ou nos pré-requisitos do caso de uso, e verifique as entradas em Agent Console > Logs após os testes.

Para Catalog Agents, use Fields na seção Output em vez de esquema JSON. Você ainda pode escrever instruções que peçam ao modelo uma saída de chave-valor correspondendo a esses nomes de campo.

Para saber mais sobre práticas recomendadas de prompting, consulte os guias dos seguintes provedores de modelos:

• OpenAI
• Anthropic
• Gemini

Saídas

Se você criou seu agente com o BrazeAI Operator usando um modelo inicial, revise o esquema de saída pré-preenchido e edite conforme necessário.

Esquemas básicos

Esquemas básicos são uma saída simples que um agente retorna. Pode ser uma string, um número, um booleano, um array de strings ou um array de números.

Por exemplo, se você deseja coletar pontuações de sentimento dos usuários a partir de uma pesquisa de feedback simples para determinar o nível de satisfação dos seus clientes após receberem um produto, é possível selecionar Number como um esquema básico para estruturar o formato de saída.

Importante

Arrays estão disponíveis apenas para agentes de etapa do Canvas, não para agentes de Catalog.

Esquemas avançados

As opções de esquema avançado incluem a estruturação manual de campos ou o uso de JSON.

• Fields: Uma forma sem código de impor uma saída de agente que você pode usar de maneira consistente.
• JSON: Uma abordagem com código para criar um formato de saída preciso, onde você pode aninhar variáveis e objetos dentro do esquema JSON. Disponível apenas para agentes de etapa do Canvas, não para agentes de Catalog.

Recomendamos usar esquemas avançados quando você deseja que o agente retorne uma estrutura de dados com vários valores definidos de maneira estruturada, em vez de uma saída de valor único. Isso permite que a saída seja melhor formatada como uma variável de contexto consistente.

Saída de fallback

Os valores de fallback estão disponíveis apenas para agentes de etapa do Canvas. Na seção Output do Console de agente para um agente de etapa do Canvas, você pode definir valores que a Braze utiliza quando uma invocação falha.

Para esquemas JSON, a Braze lê o esquema e gera um campo de entrada para cada propriedade, permitindo definir um valor de fallback por chave. Para esquemas Fields, você insere um valor de fallback para cada campo. Para esquemas básicos, você insere um único valor de fallback. Agentes de etapa do Canvas suportam Liquid nos valores de fallback.

Para as etapas de configuração, consulte Configurar valores de fallback. Para o comportamento em tempo de execução no Canvas, consulte Tratamento de erros e comportamento de fallback.

Por exemplo, você pode usar um formato de saída dentro de um agente projetado para criar um roteiro de viagem de exemplo para um usuário com base em um formulário enviado. O formato de saída permite definir que cada resposta do agente deve retornar com valores para tripStartDate, tripEndDate e destination. Cada um desses valores pode ser extraído de variáveis de contexto e inserido em uma etapa de mensagem para personalização usando Liquid.

• fields
• json schema

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "type": "object",
  "properties": {
    "sentiment": {
      "type": "string"
    },
    "reasoning": {
      "type": "string"
    }
  },
  "required": [
    "sentiment",
    "reasoning"
  ]
}

Catálogos e campos

Escolha catálogos específicos para um agente referenciar e forneça ao seu agente o contexto necessário para entender seus produtos e outros dados que não são de usuários, quando relevante. Os agentes usam ferramentas para encontrar apenas os itens relevantes e enviá-los ao LLM para minimizar o uso de tokens. Para uma melhor recuperação de catálogo, crie uma fonte de conhecimento e adicione-a como contexto do agente em vez de anexar o catálogo diretamente.

Ao implantar um Catalog Agent em um campo de catálogo, ative o controle de entrada obrigatória e escolha quais colunas selecionadas são necessárias para a execução antes que o agente seja invocado. O agente ignora uma linha apenas quando uma dessas colunas obrigatórias está em branco ou ausente — por exemplo, um campo gender que ainda não foi preenchido. As colunas selecionadas começam como obrigatórias por padrão, mas você pode remover colunas que podem estar vazias sem bloquear a execução. Isso evita desperdício de tokens em dados incompletos.

Catalog Agents também respeitam a ordem das colunas quando os campos de entrada dependem uns dos outros. Se a coluna D deve ser gerada a partir das colunas B e C, o agente não executa na coluna D até que B e C contenham valores para aquela linha.

Para cenários de implantação e exemplos, consulte Usar Catalog Agents e Práticas recomendadas para Catalog Agents.

Contexto de associação ao Segment

Você pode selecionar até cinco Segments para que o agente cruze a associação de cada usuário com os Segments quando o agente for usado em um Canvas. Digamos que seu agente tenha a associação ao Segment selecionada para um Segment “Loyalty Users” e que o agente esteja sendo usado em um Canvas. Quando os usuários entram em uma etapa de agente, o agente pode verificar se cada usuário é membro de cada Segment que você especificou no console do agente e usar a associação (ou não associação) de cada usuário como contexto para o LLM.

Diretrizes da marca

Você pode selecionar diretrizes da marca para que seu agente siga em suas respostas. Por exemplo, se você quiser que seu agente gere textos de SMS para incentivar os usuários a se inscreverem em uma academia, você pode usar esse campo para referenciar suas diretrizes predefinidas com tom motivacional e ousado.

Histórico de interação específico do usuário

Os dados de interação de um usuário incluem as mensagens de Campaigns e Canvas recebidas recentemente por canal, o conteúdo de cada mensagem e se o usuário interagiu com cada uma delas. Você pode incluir essas informações como contexto específico do usuário para um agente referenciar quando ele é invocado para um usuário no Canvas. O histórico de interação específico do usuário pode ajudar a influenciar um agente a escrever textos que ressoem com cada usuário quando sua função é redigir mensagens personalizadas.

Histórico de versões

O Console do agente registra uma nova versão cada vez que você salva alterações no agente. A guia Histórico de versões lista todas as versões salvas e as edições entre os salvamentos.

1. Abra o agente no Console do agente.
2. Selecione a guia Histórico de versões.
3. Selecione uma versão para revisar sua configuração.

Para inspecionar o que mudou em uma versão, selecione View. A Braze exibe um diff inline no estilo de código que destaca adições e exclusões. O conteúdo excluído aparece com estilo de tachado em vermelho.

Se você precisar recuperar instruções de uma versão anterior, abra View para essa versão, copie o texto da instrução e cole no campo Instructions atual.

Dica

Na visualização de diff inline, pressione ⌘ + A (macOS) ou Ctrl + A (Windows) para selecionar todas as instruções sem a marcação de exclusão em vermelho, para que você possa copiar e recuperar o texto limpo.

Duplicar agentes

Duplique um agente para testar melhorias ou iterações lado a lado com o original. Use o histórico de versões para revisar ou restaurar configurações anteriores. Para duplicar um agente:

1. Passe o cursor sobre a linha do agente e selecione o menu .
2. Selecione Duplicar.

Arquivar agentes

À medida que você cria mais agentes personalizados, é possível organizar a página Agent Management arquivando os agentes que não estão sendo usados ativamente. Para arquivar um agente:

1. Passe o cursor sobre a linha do agente e selecione o menu .
2. Selecione Archive.