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. Verifique com os administradores da Braze se você não encontrar essa opção.
• Permissão para criar e editar agentes de IA personalizados.
• Uma ideia do que você deseja 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 outros conteúdos.
  • 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 diretrizes para como ele deve se comportar. Depois de ativado, 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 você pode revisar na guia Histórico de versões.

Os casos de uso a seguir mostram algumas maneiras 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 o 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 para aplicar um modelo inicial

Se você usar o Operator, revise e aprove as alterações no chat antes de continuar 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 a finalidade do agente.
2. (opcional) Adicione tags para filtrar seu agente.
3. Escolha o modelo que seu agente vai 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 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 além de 1.000.000, entre em contato com 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 esse 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 (definida no seu contrato e 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 trocar 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 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 para ele retornar “incerto” se não conseguir decidir.

Consulte Escrevendo instruções para conhecer as melhores práticas e Exemplos para se inspirar em como orientar seu agente.

Adicionar contexto

Importante

Os agentes recebem apenas os dados que você passa explicitamente — eles não pesquisam 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 anteriores 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.
• Pertencimento a Segments: permite 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ê quiser que seu agente gere texto de SMS para incentivar os usuários a se inscreverem em uma academia, pode usar esse 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 realizar 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 sejam 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 suas 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 nessa etapa. Consulte Quais dados os agentes recebem para saber como passar contexto do Canvas e dados de perfil de forma deliberada.

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 esquemas 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

Ao usar 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 a preencher explanation quando isso ajudar você a revisar ou depurar 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 usa 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 forneça uma saída útil aos usuários quando o agente não puder ser executado.

Os 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 de 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 como indefinida (null).

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

Etapa 6: Testar o agente

O painel de Preview é uma instância do agente que aparece como um painel lado a lado dentro da experiência de configuração. Você pode usar essa seção para testar o agente enquanto o cria ou faz atualizações, experimentando-o de maneira similar aos usuários finais. Essa etapa ajuda a confirmar que ele está se comportando conforme o esperado e dá a chance de ajustar antes de colocá-lo em produção.

1. No campo Test your agent, insira dados de exemplo do cliente ou respostas do cliente — qualquer coisa que reflita cenários reais que seu agente vai enfrentar.
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 está direcionando os clientes conforme o esperado?
• Os valores calculados estão corretos?

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

Dica

Defina o que o agente deve fazer. Listar conteúdo indesejado ainda 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 seu 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 sobre IA em ação: 3 novos casos de uso para personalização 1:1