Criar agentes personalizados

Aprenda como criar agentes personalizados, o que preparar antes de começar e como colocá-los para trabalhar em envio de mensagens, tomada de decisões e gerenciamento de dados. Para mais informações gerais, veja Braze Agents.

Pré-requisitos

Antes de começar, você precisará do seguinte:

• Permissão para acessar o Agent Console no seu espaço de trabalho. Fale com os administradores da Braze se você não encontrar essa opção.
• Permissão para criar e editar AI Agents personalizados.
• Uma ideia do que você quer que o agente realize. Os Braze Agents podem realizar as seguintes ações:
  • Envio de mensagens personalizadas: gerar linhas de assunto, títulos, textos no produto ou outro conteúdo.
  • Roteamento de usuários: direcionar usuários no Canvas com base em comportamento, preferências ou atributos personalizados.
  • Gerenciamento de dados: calcular valores, enriquecer entradas de catálogo ou atualizar campos de perfil.

Como funciona

Quando você cria um agente, define seu propósito e estabelece limites para como ele deve se comportar. Depois de estar ativo, o agente pode ser implantado na Braze para gerar textos personalizados, tomar decisões em tempo real ou atualizar campos de catálogo. Enquanto constrói seu agente, você pode salvá-lo como rascunho e atualizá-lo a qualquer momento pelo dashboard. Cada salvamento cria uma nova versão que pode ser revisada na guia Histórico de versões.

Os casos de uso a seguir mostram algumas formas de aproveitar agentes personalizados.

Criar um agente

Etapa 1: Escolher um tipo de agente

Para criar um agente, primeiro escolha o tipo de agente:

1. Acesse Agent Console.
2. Escolha Canvas Step Agents ou Catalog Agents.

Etapa 2: Escolher como criar um agente

Selecione Create agent e escolha uma das seguintes opções:

• Custom agent para criar um agente do zero
• Uma opção em Create an agent with Operator para usar o BrazeAI Operator e aplicar um modelo inicial

Se você usar o Operator, revise e aprove as alterações no chat antes de prosseguir para a próxima etapa.

Etapa 3: Configurar os detalhes

Em seguida, configure os detalhes do seu agente:

1. Insira um nome e uma descrição para ajudar sua equipe a entender o propósito do agente.
2. (opcional) Adicione tags para filtrar seu agente.
3. Escolha o modelo que o agente usará.
4. Se você não estiver usando o modelo Braze Auto, selecione o nível de raciocínio do modelo. Você pode escolher entre mínimo, baixo, médio ou alto. Recomendamos começar com Minimal e testar as respostas do seu agente, ajustando conforme necessário.
5. Defina um limite diário de invocações. Por padrão, esse valor é definido como 250.000, mas pode ser aumentado para 1.000.000. Se você tiver interesse em aumentar o limite acima de 1.000.000, entre em contato com o seu gerente de sucesso do cliente para saber mais. Defina o limite alto o suficiente para o tamanho de público planejado após os testes. Um limite muito baixo causa falhas de limite diário (que não consomem créditos, mas aplicam valores de fallback ou deixam a saída como null).

O campo Daily action credit cost limit especifica o número máximo de créditos que este agente pode consumir por dia. A Braze calcula esse valor a partir da proporção de créditos por invocação do seu espaço de trabalho para o modelo selecionado (do seu contrato, exibida na página Credit Ratios) multiplicada pelo limite diário de invocações. A estimativa é atualizada quando você altera o modelo ou o limite de invocações.

Para gerenciar custos, reduza o limite diário de invocações. Para modelos bring-your-own (BYO), você também pode mudar para um modelo de menor custo ou reduzir o nível de raciocínio. O Braze Auto não oferece suporte ao ajuste do nível de raciocínio. Acompanhe o uso real em Settings > Billing > Credits Usage > Agent Console.

Etapa 4: Escrever as instruções

Forneça as instruções ao agente. Se você usou um modelo do Operator, revise as instruções pré-preenchidas e edite conforme necessário.

Inclua instruções sobre o que o agente deve fazer em cenários inesperados ou ambíguos. Isso minimiza o risco de que a confusão do agente leve a erros. Por exemplo, em vez de pedir ao agente apenas valores de sentimento “positivo” ou “negativo”, peça que ele retorne “incerto” se não conseguir decidir.

Consulte Escrevendo instruções para melhores práticas e Exemplos para inspiração sobre como configurar seu agente.

Adicionar contexto

Importante

Os agentes recebem apenas os dados que você passa explicitamente — eles não buscam perfis de usuário nem avisam quando dados necessários estão ausentes. Use Liquid nas suas instruções, selecione + Agent context, adicione etapas de Contexto upstream no Canvas, ou passe contexto adicional na etapa do agente. Para uma lista completa de fontes de dados e orientações de design, consulte Quais dados os agentes recebem.

Selecione + Agent context para escolher o que seu agente pode referenciar. Isso inclui:

• Fontes de conhecimento: Dê ao agente acesso a dados de catálogo. Crie uma fonte de conhecimento a partir de um catálogo e adicione-a como contexto do agente para que ele possa consultar e recuperar as linhas e campos necessários.
• Associação a Segments: Permita que o agente personalize respostas com base nos Segments aos quais um usuário pertence. Você pode selecionar até cinco Segments.
• Diretrizes da marca: Referencie as diretrizes de voz e estilo da marca para o agente seguir. Por exemplo, se você deseja que seu agente gere textos de SMS para incentivar os usuários a se inscreverem em uma academia, você pode usar este campo para referenciar sua diretriz predefinida de tom ousado e motivacional.
• Arquivos de contexto: Faça upload de documentos de referência (PDF, TXT, MD, CSV) para o agente consultar em cada invocação. Selecione + Agent context > Upload files, adicione um ou mais arquivos e salve o agente para fazer o upload.
• All Canvas Context: Analise todos os dados de contexto do Canvas para um usuário quando este agente for invocado, incluindo quaisquer variáveis que não estejam referenciadas na seção Instructions.
• Dados de interação do usuário: Forneça ao agente os dados recentes de aberturas, cliques e conversões de Campaigns e Canvas de cada usuário.

Dica

Para agentes de Canvas, você pode usar Liquid nas instruções para referenciar atributos de usuário, como nome e sobrenome, ou atributos personalizados. Qualquer variável Liquid nas instruções do agente é automaticamente passada para a etapa do agente quando um usuário entra na etapa. Consulte Quais dados os agentes recebem para saber como passar dados de contexto do Canvas e de perfil de forma intencional.

Etapa 5: Selecionar a saída

Na seção Output, você pode organizar e definir a saída do agente por esquemas básicos ou avançados. Se você usou um modelo do Operator, revise o esquema de saída pré-preenchido e edite conforme necessário.

Para melhores resultados, certifique-se de que o que você especificou na seção Output corresponda às instruções do agente inseridas na Etapa 4. Por exemplo, se você mencionou nas instruções do agente que deseja um objeto com duas strings, certifique-se de especificar um objeto com duas strings na seção Output. Se as instruções do agente não estiverem alinhadas com a saída especificada, o agente pode ficar confuso, expirar o tempo ou gerar saídas indesejadas.

Dica

Quando você usa um esquema de saída avançado, adicione um campo de string chamado explanation se quiser que o agente retorne sua justificativa além das outras saídas. Instrua o agente nas suas instruções para preencher explanation quando isso ajudar você a revisar ou depurar as respostas.

Configurar valores de fallback

Os valores de fallback estão disponíveis apenas para Canvas Step Agents. Na seção Output de um Canvas Step Agent, você pode definir valores que a Braze utiliza quando uma invocação do agente falha — por exemplo, quando o LLM expira ou retorna um erro de chave de API inválida. Os valores de fallback funcionam como padrões de personalização. Você pode definir uma linha de assunto estática ou uma mensagem curta que ainda ofereça saída útil aos usuários quando o agente não puder executar.

Catalog Agents não oferecem suporte à configuração de valores de fallback no Agent Console.

Para agentes de Canvas, os valores de fallback suportam templates Liquid para que você possa referenciar atributos de usuário ou variáveis de contexto no texto de fallback.

Os campos de fallback se adaptam ao formato de saída do seu Canvas Step Agent:

Quando um Canvas Step Agent com valores de fallback é executado em uma etapa do agente, a Braze renderiza o fallback por usuário e o armazena na variável de saída em vez de null. Se você não configurar valores de fallback, invocações com falha deixam a saída do Canvas indefinida (null).

Para o comportamento em tempo de execução, consulte Tratamento de erros e comportamento de fallback.

Etapa 6: Testar o agente

O painel Preview é uma instância do agente que aparece como um painel lado a lado dentro da experiência de configuração. Você pode usar esta seção para testar o agente enquanto o cria ou faz atualizações, experimentando-o de forma semelhante aos usuários finais. Esta etapa ajuda a confirmar que o agente está se comportando conforme esperado e oferece a oportunidade de fazer ajustes finos antes de colocá-lo em produção.

1. No campo Test your agent, insira dados de exemplo do cliente ou respostas de clientes — qualquer coisa que reflita cenários reais que seu agente vai lidar.
2. Visualize a resposta do agente para um usuário aleatório, um usuário existente ou um usuário personalizado.
3. Selecione Simulate response. O agente será executado com base na sua configuração e exibirá a resposta.

Nota

As execuções de teste contam para o seu limite diário de invocações.

Revise a saída com um olhar crítico. Considere as seguintes perguntas:

• O texto está alinhado com a marca?
• A lógica de decisão direciona os clientes conforme esperado?
• Os valores calculados estão precisos?

Se algo parecer estranho, atualize a configuração do agente e teste novamente. Execute diferentes entradas para ver como o agente se adapta a diversos cenários, especialmente casos extremos como ausência de dados ou respostas inválidas.

Dica

Descreva o que o agente deve fazer. Listar conteúdo indesejado pode direcionar o modelo a gerá-lo. Para mais orientações, consulte Por que meu agente não seguiu minhas instruções ou regras?.

Etapa 7: Usar o agente

Seu agente está pronto para uso! Para mais detalhes, consulte Implantar agentes.

Modelos de agente criados com o Operator

O Operator pode pré-configurar instruções, campos de saída e contexto para os seguintes modelos iniciais do Agent Console. Escolha um modelo no Operator ou peça ao Operator para aplicar um pelo nome.

Modelos de agente de etapa do Canvas

Modelos de agente de catálogo

Recursos relacionados

• Referência para agentes
• Perguntas frequentes
• Webinar da Braze: IA em ação