Como a nova DSL da Salesforce combina condicionais rígidas, variáveis de estado tipadas e subagents com a flexibilidade da inteligência artificial generativa em arquivos versionáveis no Git.
Se você já colocou um agente autônomo baseado apenas em prompts para atender clientes reais, provavelmente passou pelo mesmo frio na espinha: o modelo atende noventa e nove clientes com simpatia impecável, mas, no centésimo atendimento, decide conceder 50% de desconto sem autorização ou pula uma checagem cadastral obrigatória por pura probabilidade semântica.
Por outro lado, tentar prender a IA nos velhos fluxos engessados de chatbot (como as árvores de decisão em Salesforce Flow) destruía a melhor parte da tecnologia: a naturalidade de entender o contexto humano e resolver ambiguidades sem parecer um robô telefônico dos anos 90.
Essa tensão entre conformidade matemática e flexibilidade conversacional encontrou sua resposta oficial na plataforma: o Agent Script.
Materializado em arquivos com a extensão .agent, o Agent Script é a linguagem de domínio específico (DSL) que opera debaixo do capô do Agentforce Builder.
Em vez de apostar em um único prompt gigante ou em dezenas de fluxos desenhados em caixas, o desenvolvedor agora escreve código e linguagem natural lado a lado. Regras inegociáveis de negócio (verificação de identidade, limites de desconto, chamadas a APIs bancárias) executam deterministicamente com if/else e variáveis tipadas. Já a empatia e a condução da conversa continuam nas mãos do modelo generativo.
Nós implantamos essa arquitetura na nossa organização de testes (onlysalesforce_cgc_1), criamos o contrato da Apex Invocable Action, validamos a execução dos testes unitários com cobertura total e mapeamos as armadilhas de schema que você vai encontrar ao montar seu primeiro agente.
1. A anatomia de um arquivo .agent
Um arquivo .agent é um documento declarativo estruturado em blocos semânticos. Ele atua como o blueprint completo do agente e pode ser editado visualmente no Agentforce Builder ou diretamente no Visual Studio Code via extensão oficial do Agentforce DX.
A hierarquia é limpa e foi pensada para versionamento no Git sem os temidos conflitos de XML:
Estrutura Hierárquica do Agent Script:
├── system: (Instruções mestras de tom de voz, mensagens de erro e boas-vindas)
├── config: (Identificação do agente, versão e fixação de modelo de IA)
├── access: (Usuário de contexto de execução para herança de permissões)
├── language: (Locales suportados)
├── variables: (Estado compartilhado fortemente tipado)
├── start_agent: (Ponto de entrada inicial da conversa e triagem)
└── subagents: (Especialistas de domínio com ações e escopo delimitado)Cada seção resolve uma camada de governança. O bloco config:, por exemplo, permite amarrar o modelo (como sfdc_einstein_gpt_large), evitando que atualizações globais de inferência alterem o comportamento semântico em produção de forma inesperada.
2. A sintaxe híbrida: o operador determinístico (->) versus o pipe generativo (|)
O grande diferencial do Agent Script está na clareza visual com que separa computação pura de instrução para LLM:
- O operador de controle (
->): Inicia um bloco lógico rigoroso. O motor da plataforma executa condicionaisif/else, comparações numéricas, atribuições de variáveis e chamadas de ferramentas. O modelo não tem poder de veto aqui. - O pipe de raciocínio (
|): Entrega a frase diretamente ao modelo de linguagem como uma diretriz de conversa. O LLM formula a resposta adaptando o tom e o contexto.
O script na prática: CustomerSuccessStrategist.agent
Abaixo está o arquivo real que estruturamos no projeto (force-app/main/default/agents/CustomerSuccessStrategist.agent):
# Data: 2026-10-07
# Objetivo da Customização: Especificação Agent Script (.agent) unindo regras determinísticas e raciocínio de IA para Agentforce
system:
instructions: "Você é o assistente virtual corporativo da Varejo Total. Atue com tom profissional, cortês e objetivo. Nunca forneça dados confidenciais sem confirmação de identidade."
messages:
welcome: "Olá! Seja bem-vindo ao canal corporativo da Varejo Total. Como posso apoiar suas operações hoje?"
error: "Identificamos uma oscilação momentânea em nossos serviços. Por favor, tente novamente em alguns instantes."
config:
agent_name: "CustomerSuccessStrategist"
model: "sfdc_einstein_gpt_large"
access:
default_agent_user: "agentforce_bot@empresa.com.br"
language:
default_locale: "pt_BR"
additional_locales: "en_US"
variables:
customerIdentified: mutable boolean = false
description: "Flag que certifica se o cliente concluiu a verificação de segurança."
churnRiskScore: mutable number = 0.0
description: "Índice preditivo de cancelamento retornado pelo modelo analítico."
accountSegment: mutable string = "Standard"
description: "Segmento comercial da conta corporativa."
start_agent triage_entrypoint:
description: "Ponto de entrada para triagem e validação cadastral do usuário."
reasoning:
instructions: ->
if not @variables.customerIdentified:
| solicite educadamente o CNPJ ou número da conta do cliente para iniciar o atendimento
call @actions.CustomerTaxIdValidatorAction
if @variables.customerIdentified:
transition_to customer_retention_flow
else:
transition_to customer_retention_flow
subagent customer_retention_flow:
description: "Trata solicitações de cancelamento, renegociação contratual e ofertas de benefícios."
tools:
- @actions.getAccountChurnMetrics
- @actions.applyRetentionDiscount
reasoning:
instructions: ->
call @actions.getAccountChurnMetrics
if @variables.churnRiskScore >= 0.75:
if @variables.accountSegment == "Enterprise":
| informe ao cliente que ele possui uma condição especial de 20% de desconto na renovação anual
call @actions.applyRetentionDiscount
else:
| ofereça uma extensão de prazo de pagamento em 30 dias sem juros
else:
| compreenda o motivo da insatisfação do cliente antes de oferecer qualquer benefício financeiroVeja o poder dessa estrutura: se a variável accountSegment for "Enterprise" e o churnRiskScore bater o patamar de 0.75, o desconto de 20% é acionado pelo if no código. O modelo é instruído a comunicar o benefício, mas a regra não depende de a IA “lembrar” da política comercial no meio de um diálogo longo.
3. Subagents: a consolidação dos antigos tópicos
Nas primeiras versões experimentais de copilotos no Salesforce, os fluxos conversacionais eram organizados sob a aba de tópicos (topics). Com o Agent Script, a plataforma consolidou formalmente a nomenclatura de subagents.
Essa mudança alinha o Salesforce ao padrão moderno de Sistemas Multiagente:
- Especialização de contexto: Agentes monolíticos com dezenas de ferramentas perdem o foco e aumentam a latência da conversa. Ao quebrar o atendimento em subagentes especialistas (triagem, faturamento, suporte técnico, retenção comercial), cada contexto carrega apenas as ações estritamente necessárias.
- Transição compulsória (
transition_to): O código força a passagem de bastão quando uma condição técnica é atendida (por exemplo, após a identificação fiscal do cliente ser aprovada). - Transição orientada a ferramentas: Quando a transição é exposta como uma ferramenta no bloco
tools:, a IA decide, pela intenção do cliente na frase, se migra de atendimento comum para suporte especializado.
Abaixo, capturamos o painel de configuração de bots e agentes na nossa organização de validação:
4. O motor em Apex: Invocable Action e as pegadinhas de schema
Para que o subagente leia e grave registros no CRM com segurança, ele consome classes Apex anotadas com @InvocableMethod.
Durante a construção da ação CustomerTaxIdValidatorAction no nosso ambiente, batemos de frente com uma pegadinha clássica de quem escreve código teórico sem testar na org viva.
Muitos exemplos teóricos da internet sugerem queries SOQL como:
SELECT Id, Name, Rating, AnnualRevenue FROM Account WHERE Tax_Number__c = :cnpj AND Active__c = trueAo executar essa query diretamente na organização onlysalesforce_cgc_1, o teste unitário quebrou com erro de compilação em tempo de execução:System.QueryException: No such column 'Rating' on entity 'Account'.
Dependendo da edição da org (como Consumer Goods Cloud ou B2B) e das configurações ativas, o campo padrão Rating não está habilitado, e campos customizados como Tax_Number__c e Active__c não existem nativamente.
Para garantir que o Invocable Action seja portátil e funcione imediatamente em qualquer ambiente sem depender de campos inexistentes, nós estruturamos o código utilizando o campo nativo AccountNumber e executando a query com o modificador WITH USER_MODE:
A classe Apex: CustomerTaxIdValidatorAction.cls
/*
* Data: 2026-10-07
* Objetivo da Customização: Invocable Action para validação de clientes e enriquecimento de contexto para o Agentforce Agent Script (.agent).
*/
public with sharing class CustomerTaxIdValidatorAction {
public class Request {
@InvocableVariable(
required=true
description='Número do documento fiscal ou conta informado pelo cliente na conversa.'
)
public String taxIdentifier;
}
public class Response {
@InvocableVariable(
description='Verdadeiro se o cliente for localizado e ativo na base de dados.'
)
public Boolean isValidCustomer;
@InvocableVariable(
description='Segmento da conta: Enterprise, Mid-Market ou Standard.'
)
public String accountSegment;
@InvocableVariable(
description='Mensagem informativa de retorno para alimentar o contexto do agente.'
)
public String feedbackMessage;
}
@InvocableMethod(
label='Validar Identificador Fiscal do Cliente'
description='Busca a conta corporativa no CRM a partir do CNPJ/AccountNumber e valida status operacional.'
category='Customer Verification'
)
public static List<Response> validate(List<Request> requests) {
List<Response> responses = new List<Response>();
if (requests == null || requests.isEmpty()) {
return responses;
}
for (Request req : requests) {
Response res = new Response();
String cleanTaxId = req.taxIdentifier != null ? req.taxIdentifier.replaceAll('[^0-9a-zA-Z]', '') : '';
List<Account> accounts = [
SELECT Id, Name, AnnualRevenue, AccountNumber
FROM Account
WHERE AccountNumber = :cleanTaxId
WITH USER_MODE
LIMIT 1
];
if (accounts.isEmpty()) {
res.isValidCustomer = false;
res.accountSegment = 'Standard';
res.feedbackMessage = 'Nenhuma conta ativa localizada com o documento informado: ' + cleanTaxId;
} else {
Account acc = accounts[0];
res.isValidCustomer = true;
res.accountSegment = (acc.AnnualRevenue != null && acc.AnnualRevenue >= 50000000) ? 'Enterprise' : 'Mid-Market';
res.feedbackMessage = 'Cliente identificado com sucesso: ' + acc.Name;
}
responses.add(res);
}
return responses;
}
}Ao rodar a suíte de testes CustomerTaxIdValidatorActionTest via Salesforce CLI (sf apex test run -t CustomerTaxIdValidatorActionTest), atingimos 100% de taxa de sucesso e 95% de cobertura de código:
5. Comparativo técnico: onde o Agent Script se posiciona?
Para entender quando utilizar cada tecnologia na sua arquitetura corporativa, organizamos a matriz prática abaixo:
| Dimensão Técnica | Prompt Engineering Puro (LLM) | Automação Procedural (Flow / Apex) | Agent Script (.agent) |
|---|---|---|---|
| Garantia de Regras de Negócio | Baixa. Suscetível a alucinações e variações de temperatura. | Total. Execução determinística estrita. | Total. Garantida por blocos if/else e transições compulsórias. |
| Fluidez Conversacional | Excelente. Compreensão rica de nuances humanas. | Rígida. Menus estáticos de opções e botões. | Excelente. O modelo formula a fala guiado por diretrizes (|). |
| Gerenciamento de Estado | Volátil. Depende do histórico da janela de contexto. | Estático. Registrado em banco ou variáveis de fluxo. | Nativo. Variáveis tipadas mutáveis integradas à DSL. |
| Ciclo DX e Versionamento | Fragmentado em caixas de texto no Setup. | XML complexo e suscetível a merge conflicts. | Limpo. Arquivo de texto declarativo versionável no Git. |
| Especialização de Tarefas | Monolítico com sobrecarga de contexto. | Fluxos separados com pouca inteligência compartilhada. | Subagentes especialistas com ferramentas dedicadas. |
6. Boas práticas para o desenvolvimento com Agentforce DX
Se você está começando a estruturar agentes no Visual Studio Code, guarde estas três regras de sobrevivência:
- Trave o modelo no bloco
config:: Em agentes de missão crítica (como suporte financeiro ou autorização de pedidos), defina explicitamente o identificador do modelo homologado pela sua equipe. Isso impede que ajustes finos de LLMs na nuvem quebrem comportamentos esperados do agente. - Limite a quantidade de ferramentas por subagente: Mantenha no máximo 5 ou 6 ações em Apex em cada subagente. Mais do que isso eleva a chance de a IA escolher a ferramenta errada ou demorar para decidir a próxima etapa.
- Teste as Invocable Actions com
WITH USER_MODE: Lembre-se de que agentes de IA operam sob o contexto de um usuário de execução (default_agent_user). Garantir segurança em nível de objeto (FLS) diretamente nas classes Apex protege seu CRM de vazamentos acidentais de dados.
Conclusão
O Agent Script coloca um ponto final na dicotomia entre regras rígidas e inteligência generativa. Em vez de torcer para que um prompt lembre de uma política interna ou frustrar o usuário com árvores de menus inflexíveis, os arquivos .agent entregam a disciplina da engenharia de software para o mundo dos agentes autônomos.
Com condicionais declarativas, subagentes modulares e integração direta com o código Apex que você já possui na sua org, o Agentforce entrega uma base sólida para construir inteligência corporativa com governança real.
Sua organização já começou a testar o Agent Script ou ainda está organizando os primeiros prompts no Agentforce? Compartilhe seus desafios nos comentários e participe do debate no LinkedIn.