Referência para agentes

Ao criar agentes personalizados, consulte este artigo para saber mais 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 da Braze foi ajustado para tarefas como pesquisar fontes de conhecimento e verificar a associação a Segments. Se você usar seu próprio modelo, teste essas tarefas especificamente. Modelos de custo mais baixo com níveis de raciocínio baixos podem pular chamadas de ferramentas ou responder antes de recuperar os dados. Talvez seja necessário ajustar suas instruções para oferecer diferentes níveis de detalhe ou 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 modelos de linguagem grandes (LLMs). Para usar essa opção, selecione Auto, que usa modelos Gemini.

Opção 2: Trazer 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. Para ver a lista completa de provedores compatíveis, consulte Provedores de modelos de IA. 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, e não pela Braze.

Recomendamos testar regularmente os modelos mais recentes, pois modelos legados podem ser descontinuados ou se tornar 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. Assim, você recebe um alerta quando a Braze detecta que um modelo não está mais disponível ou encontra problemas de faturamento 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, volte ao seu agente e selecione 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 trazer sua própria chave de API, o provedor da sua assinatura de LLM será considerado um Provedor Terceirizado, conforme o 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 o quanto o modelo pensa antes de responder, desde respostas rápidas e diretas até cadeias de raciocínio mais longas. Isso afeta a qualidade da resposta, a latência e o uso de tokens.

Os níveis disponíveis variam conforme o modelo. Alguns modelos oferecem Nenhum no lugar de Mínimo, e nem todo modelo oferece Alto.

Recomendamos começar com Mínimo (ou Nenhum) e testar as respostas do seu agente. Se o agente usar fontes de conhecimento, comece com Baixo. No nível mais baixo, alguns modelos respondem sem executar a pesquisa. Se o agente tiver dificuldade em fornecer respostas precisas, suba um nível de cada vez. Em casos raros, pode ser necessário um nível de raciocínio Alto. No entanto, 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 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 saída a LLMs 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 oferecer suporte a listas de permissões de IP, você pode restringir a chave a esses intervalos para que somente 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 trazer sua própria chave de API, o provedor da sua assinatura de LLM será considerado um Provedor Terceirizado, conforme o 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. Confira algumas diretrizes gerais e práticas recomendadas:

• Para economizar, priorize testar modelos com custo de tokens mais baixo antes dos modelos mais caros. Passe para modelos mais caros somente 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. Passe para níveis de raciocínio mais altos somente 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 passar para modelos mais caros ou níveis de raciocínio mais altos.
• Durante os testes, equilibre a confiabilidade e a 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 garantir uma qualidade consistente, sem tempos limite esgotados.

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ções e créditos

Cada agente tem, por padrão, um limite diário de 250.000 invocações, que pode chegar a 1.000.000 por dia. Se quiser aumentar o limite para mais de 1.000.000, entre em contato com seu gerente de sucesso do cliente. Todas as invocações contam para esse limite, incluindo as prévias do Agent Console e as 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 a quantidade máxima de créditos que um agente pode consumir por dia. A Braze multiplica a taxa 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 somente pelas 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)
• Indisponibilidade do modelo selecionado
• O agente ter atingido o 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 taxas de créditos por agente.

As taxas de créditos vêm do seu contrato e aparecem no dashboard Uso de créditos (guias Taxas de crédito e 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 modelo Auto da Braze 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 Logs mostra Error e a mensagem do provedor (como Rate limit exceeded) em Saída. As novas tentativas ficam visíveis nos logs, incluindo a primeira invocação, independentemente de ela ter sucesso ou falhar no final. Por exemplo, se um usuário precisar de quatro novas tentativas até obter sucesso, você pode pesquisar o ID do usuário e ver todas as cinco invocações (a original mais as quatro novas tentativas) em Logs. A original e as três primeiras novas tentativas mostrarão Error 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 Logs.

Escrever instruções

Instruções são as regras ou diretrizes que você passa ao agente (prompt do sistema). Elas definem como o agente deve se comportar em cada execução. 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.

Confira algumas práticas recomendadas gerais para começar a escrever prompts:

1. Comece pelo resultado. Declare o objetivo 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 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 trazer 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 descreva as restrições em termos concretos. Se um agente ignorar suas regras, consulte Por que meu agente não seguiu minhas instruções ou regras?.

Formatar instruções com Markdown

As instruções aceitam formatação em Markdown, incluindo títulos, listas com marcadores e numeradas, texto em negrito, links e tabelas. Use títulos como # Role, ## Goal e ## Rules para dividir instruções longas em seções mais fáceis de ler para você e sua equipe. A formatação só altera a forma como as instruções aparecem na Braze. O agente sempre recebe o texto original que você escreveu.

• Na etapa Instruções, selecione Prévia para ver suas instruções como texto formatado e Editar para voltar ao editor.
• Na página de visualização do agente, as instruções aparecem com a formatação em Markdown.
• Os links nas instruções formatadas abrem em uma nova guia.
• Tags HTML brutas ou no estilo XML (como <role>) aparecem como texto simples na prévia. O agente continua recebendo essas tags exatamente como foram escritas.

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 de Braze Agents.

Usar Liquid

Incluir Liquid nas instruções do seu agente adiciona uma camada extra de personalização à resposta dele. 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 “nome” explicitamente, 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 guia Logs do agente, você pode conferir os detalhes da entrada e da saída do agente para entender qual valor foi renderizado a partir do Liquid.

Quais dados os agentes recebem

O contexto do agente não é uma memória de conversa aberta. Ao contrário de um assistente de chat, o agente só vê os dados que você passa explicitamente no momento da invocação. Ele não navega pelos perfis de usuário, não deduz campos ausentes e não avisa quando falta alguma informação necessária.

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

1. Liquid nas instruções: Use templates de atributos do usuário ({{${first_name}}}) e de 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 segmentos, 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 template Liquid que ainda não tenham sido especificados pelos outros métodos.

Não deixe de usar templates Liquid para essas variáveis de contexto nas instruções do agente, anexar arquivos de contexto que o agente deve consultar ou selecionar 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 na guia Logs do agente 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 em pares de chave e valor correspondente a esses nomes de campo.

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 que um agente retorna. Ela pode ser uma string, um número, um booleano, um array de strings ou um array de números.

Por exemplo, se você quiser coletar pontuações de sentimento dos usuários em uma pesquisa de feedback simples para saber o quanto seus clientes estão satisfeitos depois de receber um produto, você pode selecionar Número como esquema básico para estruturar o formato da 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 garantir 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 os 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, então você pode definir um valor de fallback por chave. Para esquemas de Campos, você informa um valor de fallback para cada campo. Para esquemas básicos, você informa 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 exemplo de roteiro de viagem para um usuário com base em um formulário que ele enviou. O formato de saída permite definir que toda resposta do agente deve retornar os valores tripStartDate, tripEndDate e destination. Cada um desses valores pode ser extraído das variáveis de contexto e inserido em uma etapa de Mensagem para personalização com 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 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 ao Segment

Você pode selecionar até cinco Segments para que o agente verifique a associação de cada usuário a eles quando o agente for usado em um Canvas. Digamos que seu agente tenha a associação ao Segment “Loyalty Users” selecionada e que ele seja usado em um Canvas. Quando os usuários entram em uma etapa do 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 o seu agente seguir nas respostas. Por exemplo, se você quiser que o seu agente gere textos de SMS para incentivar os usuários a se inscreverem em um plano de academia, pode usar este 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.

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.

Copiar agentes para outro espaço de trabalho

Copie um Canvas Step Agent ou um Agentic Standard para outro espaço de trabalho da sua empresa e reutilize a configuração sem precisar recriá-la. A Braze salva a cópia como rascunho, com o nome “Cópia de” seguido do nome original. Para copiar um agente:

1. Passe o mouse sobre a linha do agente e selecione o menu .
2. Selecione Copiar para o espaço de trabalho.
3. Selecione o Espaço de trabalho de destino e depois Copiar como rascunho.
4. No espaço de trabalho de destino, revise a cópia e reconecte as configurações que não foram copiadas.

A cópia mantém as instruções, a descrição, o formato de saída, os valores de fallback, as regras, os arquivos de contexto e o limite diário de invocações do agente. Se o limite for maior do que o permitido no espaço de trabalho de destino, a Braze reduz o limite para o máximo desse espaço de trabalho. As configurações a seguir pertencem ao espaço de trabalho de origem e não são copiadas:

• Segments
• Equipes
• Tags
• Campos do catálogo
• Diretriz da marca
• Fontes de conhecimento

Se o espaço de trabalho de destino não puder executar o modelo do agente, a cópia usa o Braze Auto.

Observe as seguintes limitações:

• Não é possível copiar Catalog Agents nem agentes arquivados.
• Você precisa ter permissão para editar esse tipo de agente em todo o espaço de trabalho de destino.

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.