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. Existem duas opções: usar um modelo fornecido pela Braze ou trazer sua própria chave de API.

Importante

O modelo Auto fornecido pela Braze é otimizado para modelos cujas capacidades de raciocínio são suficientes para realizar tarefas como recuperar dados de catálogo por meio de fontes de conhecimento e verificar a associação a Segments. Ao usar outros modelos, recomendamos testar para confirmar que seu modelo funciona bem para o seu caso de uso. Talvez seja 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 fornecido pela Braze

Essa é a opção mais simples, sem necessidade de configuração extra. A Braze fornece acesso a grandes modelos de linguagem (LLMs) diretamente. Para usar essa opção, selecione Auto, que usa 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 gerente de sucesso do cliente para saber como se tornar elegível para usar o modelo Braze Auto.

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

Com essa opção, você pode conectar sua conta 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 serão cobrados diretamente pelo seu provedor, não pela Braze.

Recomendamos testar rotineiramente os modelos mais recentes, pois modelos legados podem ser descontinuados ou obsoletos 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.

Em seguida, você pode voltar ao seu agente e selecionar seu modelo.

Quando você usa um LLM fornecido pela Braze, os provedores desse 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 extensão 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. Em seguida, você pode ajustar o nível de raciocínio para Baixo ou Médio se perceber que o agente está tendo dificuldades para 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 o seu agente estiver tendo dificuldades para equilibrar raciocínio de múltiplas etapas com 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 as mesmas faixas de IP para chamadas de saída de LLM que para Connected Content. As faixas estão listadas na lista de IPs permitidos do Connected Content. Se o seu provedor suportar lista de IPs permitidos, você pode restringir a chave a essas faixas para que somente a Braze possa usá-la.

Importante

Quando você usa um LLM fornecido pela Braze, os provedores desse 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 custos, priorize testar modelos de menor custo de tokens antes dos modelos de maior custo. Ajuste para modelos de maior custo somente se os modelos de menor custo estiverem tendo dificuldades com o caso de uso ou gerando saídas inconsistentes ou imprecisas.
• Para eficiência de velocidade e desempenho, priorize testar níveis de raciocínio mais baixos antes de níveis mais altos. Ajuste para níveis de raciocínio mais altos somente se os níveis mais baixos estiverem tendo dificuldades com o caso de uso ou gerando saídas inconsistentes ou imprecisas.
• Se modelos de menor custo ou níveis de raciocínio mais baixos estiverem tendo dificuldades com o caso de uso ou gerando saídas inconsistentes ou imprecisas, 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 fornecido pela 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 mais). Toda invocação (incluindo prévias do Agent Console e execuções de teste do 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 somente para invocações que concluem o processamento. Os créditos não são consumidos quando uma invocação falha devido a:

• 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 expira por 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, contagens de invocação e proporções de créditos por agente.

As proporções de créditos vêm do seu contrato e aparecem no dashboard de 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 agente de etapa do Canvas ou agente de catálogo, a Braze tenta continuamente reenviar a solicitação 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 do seu eventual sucesso ou falha. Para um determinado usuário, se forem necessárias quatro tentativas para finalmente obter um sucesso, você pode pesquisar o ID do usuário e ver todas as cinco (original mais quatro tentativas) nos 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 nos Logs.

Escrevendo instruções

Instruções são as regras ou diretrizes que você fornece ao agente (prompt do sistema). Elas definem como o agente deve se comportar cada vez que é executado. As instruções do 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 escrever 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, tamanho, tom, formato).
4. Peça uma estrutura (“Retorne JSON/lista com marcadores/tabela…”).
5. Mostre, não apenas 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 e 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 casos extremos usando regras positivas e explícitas, e adicione instruções de recusa quando necessário.
10. Meça e documente o que funciona internamente para reutilização e escala.

Escreva instruções positivas e explícitas sempre que possível. Diga ao agente o que fazer e declare quaisquer restrições em termos concretos. Se um agente ignorar suas regras, consulte Por que meu agente não seguiu minhas instruções ou regras?.

Exemplos

Para configurações iniciais no Agent Console, consulte Modelos de agente 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 da 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. Diferentemente de um assistente de chat, um agente só vê os dados que você passa explicitamente no momento da invocação — ele não navega por perfis de usuário, não infere campos ausentes nem 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: Insira atributos de usuário ({{${first_name}}}) e variáveis de contexto do Canvas ({{context.${variable_name}}}) diretamente no prompt do agente.
2. + Contexto do agente: Selecione fontes de conhecimento, associação a Segments, diretrizes da 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.* em etapas anteriores no Canvas antes da execução de uma etapa de agente.
4. Contexto adicional na etapa do agente: Passe quaisquer valores adicionais com template Liquid que não foram especificados pelos outros métodos ao agente no momento do envio, a partir da configuração da etapa.

Certifique-se de inserir essas variáveis de contexto com template Liquid nas instruções do agente, anexar arquivos de contexto que o agente deve consultar 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 obrigató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 correspondente aos nomes desses campos.

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

• OpenAI
• Anthropic
• Gemini

Saídas

Se você construiu 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, selecione Number como 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 catálogo.

Esquemas avançados

As opções de esquema avançado incluem estruturar campos manualmente ou usar JSON.

• Fields: Uma forma sem código de aplicar uma saída do agente que você pode usar de maneira consistente.
• JSON: Uma abordagem por código para criar um formato de saída preciso, em que 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 catálogo.

Recomendamos usar esquemas avançados quando você quiser que o agente retorne uma estrutura de dados com múltiplos valores definidos de forma 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 do Agente para um agente de etapa do Canvas, você pode definir os 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 que você defina 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 destinado a 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 toda 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"
  ]
}

Contexto de catálogo e campos

Para dar a um Canvas Step Agent acesso aos dados do catálogo, crie uma fonte de conhecimento a partir do catálogo e adicione-a como + Agent context. O agente consulta a fonte de conhecimento para recuperar as linhas correspondentes e envia apenas os dados relevantes do catálogo ao LLM, o que minimiza o uso de tokens e melhora a precisão da recuperação. Não anexe o catálogo diretamente como contexto do agente. Agentes configurados com a opção legada Add catalog fields antes de as fontes de conhecimento estarem disponíveis podem continuar usando esse contexto até que você os migre.

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 pertencimento a Segments

Você pode selecionar até cinco Segments para que o agente faça referência cruzada do pertencimento de cada usuário a Segments quando o agente é usado em um Canvas. Digamos que seu agente tenha o pertencimento a Segments selecionado para um Segment “Loyalty Users”, e o agente é usado em um Canvas. Quando os usuários entram em uma etapa de agente, o agente pode verificar por referência cruzada se cada usuário é membro de cada Segment que você especificou no console do agente, e usar o pertencimento (ou não pertencimento) 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 usuários a se inscreverem em uma academia, você pode usar esse campo para referenciar sua diretriz predefinida com tom ousado e motivacional.

Arquivos de contexto

Faça upload de documentos de referência para que um agente possa consultar material estático em cada invocação — por exemplo, um guia de tom de voz, documento de política ou especificação de produto. Os arquivos de contexto estão disponíveis para Canvas Step Agents e Catalog Agents.

Para anexar arquivos:

1. Na etapa Instructions, selecione + Agent context > Upload files.
2. Adicione um ou mais arquivos. Os tipos compatíveis são PDF, TXT, MD e CSV.
3. Salve o agente. Os arquivos são enviados quando você salva. Eles permanecem preparados no navegador e são incluídos quando você visualiza a prévia do agente.

Você pode anexar até 10 arquivos por agente. Todos os arquivos anexados juntos podem totalizar até 15 MB. Ao anexar arquivos de contexto, informe ao agente nas suas instruções como usá-los. Por exemplo, você pode incluir: “Siga o tom e a terminologia no guia de estilo anexado.” Uma seção Files vazia conta para o aviso de needs setup até que você anexe pelo menos um arquivo.

A Braze envia os arquivos anexados em cada invocação do agente, incluindo prévias no Agent Console. Como os arquivos são incluídos em cada execução, anexos maiores podem aumentar o uso de tokens e a latência.

Os arquivos de contexto diferem das diretrizes da marca: as diretrizes da marca são configurações sintetizadas do espaço de trabalho, enquanto os arquivos de contexto são documentos que você envia diretamente para um único agente. Para as etapas de configuração, consulte Adicionar contexto.

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. Quando você adiciona ou remove arquivos de contexto, o diff lista os nomes dos arquivos anexados.

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.

Agentes duplicados

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, pode organizar a página Agent Management arquivando 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.