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 fornecido pela Braze ou usar sua própria chave de API.

Importante

O modelo Auto fornecido pela Braze é otimizado para modelos com capacidade de raciocínio suficiente para tarefas como recuperar dados de catálogo por meio de fontes de conhecimento e verificar a associação a segmentos. Se você usar outros modelos, recomendamos testá-los para confirmar que funcionam bem no seu caso de uso. Talvez seja necessário ajustar suas instruções para dar mais ou menos detalhes ou um raciocínio passo a passo, de acordo com a velocidade e as capacidades de cada modelo.

Opção 1: Usar um modelo fornecido pela Braze

Essa é a opção mais simples e não exige nenhuma configuração extra. A Braze fornece acesso direto a grandes modelos de linguagem (LLMs). Para usar essa opção, selecione Auto, que usa modelos Gemini.

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

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

Recomendamos testar regularmente os modelos mais recentes, já que modelos legados podem ser descontinuados ou obsoletos depois de alguns meses. Confira se você tem 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 e 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 Integrações de parceiros > Parceiros de tecnologia e encontre seu provedor.
2. Insira a chave de API do provedor.
3. Selecione Salvar.

Depois, você pode voltar ao seu agente e selecionar o modelo.

Quando você usa um LLM fornecido pela Braze, os provedores desse modelo atuam como Subprocessadores da Braze, sujeitos aos termos do Adendo de Processamento de Dados (DPA) entre você e a Braze. Se você optar por usar sua própria chave de API, o provedor da sua assinatura de LLM será considerado um Fornecedor Terceirizado nos termos do contrato entre você e a Braze.

Níveis de raciocínio

Alguns provedores de LLM permitem ajustar o nível de raciocínio do modelo selecionado. Os níveis de raciocínio definem quanto o modelo pensa antes de responder, desde respostas rápidas e diretas até cadeias de raciocínio mais longas. Isso afeta a qualidade das respostas, a latência e o uso de tokens.

Recomendamos começar com Mínimo e testar as respostas do seu agente. Depois, você pode ajustar o nível de raciocínio para Baixo ou Médio se perceber que o agente tem dificuldade em fornecer respostas precisas. Em casos raros, pode ser necessário um nível de raciocínio Alto. Porém, esse nível pode gerar custos altos de tokens, tempos de resposta mais longos ou maior risco de erros de tempo limite. Se o seu agente tiver dificuldade em equilibrar o raciocínio em várias etapas com tempos de resposta razoáveis, considere dividir seu caso de uso em mais de um agente, que podem trabalhar juntos em um Canvas ou catálogo.

A Braze usa os mesmos intervalos de IP para chamadas de LLM de saída que usa para o Connected Content. Os intervalos estão listados na lista de permissões de IP do Connected Content. Se o seu provedor permitir lista de permissões de IP, 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 desse modelo atuam como Subprocessadores da Braze, sujeitos aos termos do Adendo de Processamento de Dados (DPA) entre você e a Braze. Se você optar por usar sua própria chave de API, o provedor da sua assinatura de LLM será considerado um Fornecedor Terceirizado nos termos do contrato entre você e a Braze.

Determinar qual modelo usar

Cada provedor de LLM tem uma combinação um pouco diferente de capacidades, custos e níveis de raciocínio dos modelos. Veja algumas diretrizes gerais e práticas recomendadas:

• Para economizar, priorize testar modelos com custo de tokens menor antes de modelos mais caros. Só mude para modelos mais caros se os mais baratos tiverem dificuldade com o caso de uso ou gerarem resultados inconsistentes ou imprecisos.
• Para ganhar velocidade e desempenho, priorize testar níveis de raciocínio mais baixos antes dos mais altos. Só mude para níveis de raciocínio mais altos se os mais baixos tiverem dificuldade com o caso de uso ou gerarem resultados inconsistentes ou imprecisos.
• Se modelos mais baratos ou níveis de raciocínio mais baixos tiverem dificuldade com o caso de uso ou gerarem resultados inconsistentes ou imprecisos, considere mudar para modelos mais caros ou níveis de raciocínio mais altos.
• Durante os testes, equilibre confiabilidade e precisão com o uso de tokens e a duração das invocações.
• Cada caso de uso pode ter um modelo e um nível de raciocínio ideais diferentes. Recomendamos testar bem para confirmar uma qualidade consistente, sem erros de tempo limite.

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
• Usando sua própria chave de API: 5.000 invocações por minuto

Quando muitos usuários entram em uma etapa de agente ao mesmo tempo, a Braze coloca as invocações em fila de acordo com esses limites. Por isso, o processamento pode demorar mais durante envios de alto volume.

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

Cada agente tem um limite diário de invocações (padrão de 250.000; máximo de 1.000.000, a menos que seu contrato permita mais). Toda invocação conta para esse limite, incluindo prévias do Agent Console e execuções de teste do Canvas que usam Simular resposta.

No Agent Console, o Limite diário de custo de créditos de ação 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ções.

Quando os créditos são consumidos

A Braze cobra créditos apenas por 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 novas tentativas que acabam falhando)
• O modelo selecionado estar indisponível
• O agente atingir seu limite diário de invocações

Os créditos são consumidos quando uma invocação atinge o tempo limite, mesmo que o agente não retorne um resultado utilizável.

Monitorar o uso de créditos

Acesse Configurações > Faturamento > Uso de créditos > Agent Console para ver o consumo de créditos, a contagem de invocações e as proporções de créditos por agente.

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

Para controlar os gastos, reduza o limite diário de invocações. Para modelos com sua própria chave (BYO), você também pode escolher um modelo mais barato ou reduzir o nível de raciocínio para diminuir os custos de tokens do provedor. O Braze Auto não permite ajustar o 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 a invocação de um agente de etapa do Canvas ou de um agente de catálogo, a Braze tenta novamente a solicitação continuamente, usando recuo exponencial, até que a chamada seja bem-sucedida ou a Braze determine que ela não pode ser concluída.

Quando as novas tentativas do Canvas ou do catálogo se esgotam, o painel de detalhes de Registros mostra Erro e a mensagem do provedor (como Rate limit exceeded) em Saída. As novas tentativas aparecem nos registros, incluindo a primeira invocação, independentemente de ela acabar em sucesso ou falha. Por exemplo, se um usuário precisar de quatro novas tentativas até finalmente ter sucesso, você pode pesquisar o ID do usuário e ver as cinco (a original mais as quatro novas tentativas) em Registros. A original e as três primeiras novas tentativas vão mostrar Erro com Rate limit exceeded.

Erros de limite de frequência não consomem créditos da Braze, incluindo as novas tentativas com falha exibidas em Registros.

Escrevendo instruções

As instruções são as regras ou diretrizes que você dá ao agente (prompt do sistema). Elas definem como o agente deve se comportar sempre que for 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 você começar a escrever prompts:

1. Comece pelo resultado. Declare o objetivo primeiro.
2. Dê ao modelo uma função ou persona (“Você é um…”).
3. Defina contexto e restrições claras (público, extensão, tom, formato).
4. Peça uma estrutura (“Retorne JSON/lista com marcadores/tabela…”).
5. Mostre em vez de só explicar. 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, analise e itere. Pequenos ajustes podem gerar grandes ganhos de qualidade.
9. Trate casos extremos com regras positivas e explícitas e adicione instruções de recusa quando necessário.
10. Meça e documente internamente o que funciona para reutilizar e escalar.

Sempre que possível, escreva instruções positivas e explícitas. 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 ver exemplos completos de instruções que você pode copiar ou adaptar, consulte a biblioteca de casos de uso dos Braze Agents.

Usando Liquid

Incluir Liquid nas instruções do seu agente pode adicionar uma camada extra de personalização à 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 da 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 de conversa aberta. Diferente 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 deduz campos ausentes e não avisa quando faltam informações necessárias.

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

1. Liquid nas instruções: Insira atributos do 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, Todo o contexto do Canvas ou dados de interação do usuário no Agent Console.
3. Etapas de contexto: Defina ou atualize variáveis context.* em etapas anteriores do Canvas, antes da execução de uma etapa de agente.
4. Contexto adicional na etapa de agente: Passe ao agente, no momento do envio e a partir da configuração da etapa, quaisquer valores adicionais com modelo Liquid que ainda não tenham sido especificados pelos outros métodos.

Insira essas variáveis de contexto com Liquid nas instruções do agente, anexe os arquivos de contexto que o agente deve consultar ou selecione Adicionar todo o contexto do Canvas. Se um valor não for passado por um desses canais, o agente não o recebe. 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 depois de testar.

Para agentes de catálogo, use Campos na seção Saída em vez de um esquema JSON. Você ainda pode escrever instruções que peçam ao modelo uma saída de chave-valor correspondente a esses nomes de campos.

Para saber mais sobre práticas recomendadas de prompts, 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 retornada por um agente. Ela pode ser uma string, um número, um booleano, um array de strings ou um array de números.

Por exemplo, imagine que você quer coletar pontuações de sentimento dos usuários em uma pesquisa de feedback simples para saber o nível de satisfação dos clientes depois de receberem um produto. Nesse caso, você pode selecionar Número 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.

• Campos: Uma forma sem código de definir uma saída do agente que você pode usar de maneira consistente.
• JSON: Uma abordagem com 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 vários valores definidos de forma estruturada, em vez de uma saída com um único valor. Assim, a saída fica mais bem formatada como uma variável de contexto consistente.

Saída de fallback

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

Para esquemas JSON, a Braze lê o esquema e gera um campo de entrada para cada propriedade, para que você possa definir um valor de fallback por chave. Para esquemas de Campos, 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 ver as etapas de configuração, consulte Configurar valores de fallback. Para saber como funciona a execução no Canvas, consulte Tratamento de erros e comportamento de fallback.

Por exemplo, você pode usar um formato de saída em um agente criado para gerar um roteiro de viagem de exemplo para um usuário com base em um formulário enviado por ele. O formato de saída permite definir que toda resposta do agente deve retornar 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.

• campos
• esquema json

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 agente de etapa do Canvas acesso aos dados do catálogo, crie uma fonte de conhecimento a partir do catálogo e adicione-a como + Contexto do agente. O agente consulta a fonte de conhecimento para recuperar as linhas correspondentes e envia ao LLM apenas os dados relevantes do catálogo. Isso minimiza o uso de tokens e melhora a precisão da recuperação. Não é possível anexar o catálogo diretamente como contexto do agente. Agentes configurados com a opção legada Adicionar campos de catálogo antes de as fontes de conhecimento estarem disponíveis podem continuar usando esse contexto até que você os migre.

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

Os agentes de catálogo 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 só executa na coluna D quando B e C tiverem valores para aquela linha.

Para ver cenários de implantação e exemplos, consulte Usar agentes de catálogo e Práticas recomendadas para agentes de catálogo.

Contexto de associação a Segments

Você pode selecionar até cinco Segments para o agente cruzar a associação de cada usuário quando ele for usado em um Canvas. Por exemplo, imagine que seu agente tem a associação ao Segment “Loyalty Users” selecionada e é usado em um Canvas. Quando os usuários entram em uma etapa de Agente, o agente pode verificar se cada usuário pertence a cada Segment que você especificou no console do agente. Então, ele usa essa associação (ou a falta dela) como contexto para o LLM.

Diretrizes da marca

Você pode selecionar diretrizes da marca para que seu agente siga nas respostas. Por exemplo, se você quiser que seu agente gere textos de SMS para incentivar os usuários a se inscreverem em um plano de academia, use este campo para referenciar sua diretriz predefinida, com um 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.

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 recuperar configurações anteriores. Para duplicar um agente:

1. Passe o mouse 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 Gerenciamento de agentes arquivando os agentes que não estão sendo usados ativamente. Para arquivar um agente:

1. Passe o mouse sobre a linha do agente e selecione o menu .
2. Selecione Arquivar.