Publicado: 12 de junho de 2026 | Tempo de Leitura: 7 minutos | Categoria: Salesforce

Resumo

Construir um Agente de Serviço do Agentforce para capturar leads requer o gerenciamento de estado de várias interações de forma segura. Embora os Fluxos padrão sejam ótimos para tarefas simples, o uso de um @InvocableMethod Apex permite o rastreamento persistente do estado entre as interações da conversa e operações DML seguras em USER_MODE. Veja exatamente como construir um.

Introdução: A Era do Agentforce

O Agentforce da Salesforce mudou completamente a forma como pensamos sobre interações automatizadas com clientes. Estamos passando de chatbots rígidos baseados em árvores para agentes autônomos que podem raciocinar, fazer perguntas de esclarecimento e executar ações.

Um dos primeiros casos de uso mais comuns para o Agentforce é a Captura de Leads. O objetivo é simples: um agente de IA pergunta ao usuário suas informações (por exemplo, Sobrenome e Empresa), retém essas informações em várias interações da conversa e cria um registro de Lead do Salesforce assim que todos os dados necessários forem coletados.

Embora você possa tentar isso com um fluxo de tela ou um fluxo autolançado, as ações invocáveis Apex fornecem controle significativamente maior sobre o gerenciamento de estado e o contexto de segurança.

Aqui está o projeto exato para um Agente de Captura de Leads pronto para produção em 2026.

A Arquitetura

Nossa solução requer três componentes principais:

  1. O Roteador de Agente (start_agent): Recebe o usuário e o direciona para o subagente correto com base na intenção.
  2. O Subagente de Captura de Leads (subagent): Instruí o LLM sobre exatamente quais campos são necessários (Sobrenome e Empresa) e aciona a ação.
  3. A Ação Invocável Apex (@InvocableMethod): O "motor" real que analisa a entrada, mantém o estado e executa a inserção no banco de dados.

1. O DSL do Script do Agente

O Agentforce usa uma Linguagem de Domínio Específico (DSL) específica para definir o comportamento do agente. Definimos variáveis para reter a entrada do usuário entre as interações.

variables:
    last_name: mutable string = ""
        description: "Sobrenome do lead"
    company: mutable string = ""
        description: "Empresa do lead"
    lead_created: mutable boolean = False
        description: "Se o lead já foi criado"
    last_lead_id: mutable string = ""
        description: "O ID do Lead criado mais recentemente"

A lógica para nosso subagente dita que para cada mensagem que o usuário envia enquanto está no tópico de captura de leads, chamamos nossa ação Apex. Passamos a userMessage atual, juntamente com as variáveis last_name e company que coletamos até agora.

subagent lead_capture:
    label: "Captura de Leads"
    description: "Coleta sobrenome e empresa, depois cria um Lead do Salesforce através do Apex."
    reasoning:
        instructions: ->
            if @variables.lead_created == True:
                | Um lead já foi criado nesta conversa. Compartilhe o ID do Lead e pergunte se o usuário deseja algo mais.
            if @variables.lead_created == False:
                | Use Process Lead Capture Turn para cada mensagem de captura de leads.
        actions:
            process_lead_turn: @actions.process_lead_turn
                    with userMessage = ...
                    with knownLastName = @variables.last_name
                    with knownCompany = @variables.company
                    set @variables.last_name = @outputs.resolvedLastName
                    set @variables.company = @outputs.resolvedCompany
                    set @variables.lead_created = @outputs.isSuccess
                    set @variables.last_lead_id = @outputs.leadId

2. A Ação Invocável Apex

O verdadeiro poder deste padrão reside na classe Apex. Em vez de fazer o LLM adivinhar quando criar o lead, usamos uma ação invocável para gerenciar a lógica de negócios de forma segura.

Por que Apex em vez de Fluxo?

  • Estado de Múltiplas Interações: Ao passar knownLastName e knownCompany para a ação Apex e retornar resolvedLastName e resolvedCompany, mantemos o estado da conversa perfeitamente, mesmo que o usuário forneça as informações fora de ordem.
  • Contexto de Segurança: Podemos impor o Nível de Acesso a Campos (FLS) e permissões CRUD dinamicamente usando AccessLevel.USER_MODE.

Aqui está a estrutura das variáveis de entrada e saída:

public class LeadCaptureTurnAction {
    
    public class Request {
        @InvocableVariable(required=true label='User Message')
        public String userMessage;
        
        @InvocableVariable(label='Known Last Name')
        public String knownLastName;
        
        @InvocableVariable(label='Known Company')
        public String knownCompany;
    }
    
    public class Result {
        @InvocableVariable(label='Is Success')
        public Boolean isSuccess;
        
        @InvocableVariable(label='Lead ID')
        public String leadId; // GOTCHA: Deve ser String, não Id
        
        @InvocableVariable(label='Resolved Last Name')
        public String resolvedLastName;
        
        @InvocableVariable(label='Resolved Company')
        public String resolvedCompany;
        
        @InvocableVariable(label='Message')
        public String message;
    }
    
    @InvocableMethod(label='Process Lead Capture Turn')
    public static List<Result> processTurn(List<Request> requests) {
        // 1. Analisar userMessage em busca de campos ausentes usando Regex
        // 2. Combinar campos encontrados com knownLastName e knownCompany
        // 3. Se ambos estiverem presentes, inserir o Lead
        // 4. Retornar o Resultado
    }
}

O "Gotcha" de Vinculação leadId

Observe que public String leadId; é definido como String e não como Id. Esta é uma nuance crítica no Agentforce. Ao vincular a saída de uma ação invocável de volta a uma variável de Script do Agente (set @variables.last_lead_id = @outputs.leadId), o Agentforce prefere fortemente tipos de string primitivos em vez de tipos Id estritos do Salesforce. Usar Id pode causar falhas silenciosas de vinculação durante a execução.

3. Aplicando Segurança com USER_MODE

Quando o Agentforce executa uma ação invocável, ele é executado sob o contexto do usuário Einstein Service Agent (ou seu usuário agente padrão configurado).

Se você tentar inserir um lead usando DML padrão (insert newLead;), o contexto do sistema pode ignorar as verificações de segurança necessárias ou falhar de forma imprevisível, dependendo das configurações de compartilhamento da organização.

A abordagem correta em 2026 é sempre impor DML em modo de usuário:

Database.SaveResult sr = Database.insert(newLead, false, AccessLevel.USER_MODE);

A Permissão Ausente

Para que a inserção em USER_MODE funcione, o usuário Einstein Service Agent deve ter permissão para criar registros de Lead.

Você deve criar um Conjunto de Permissões (por exemplo, LeadCaptureAgent_Apex_Access) que conceda:

  1. Acesso à Classe Apex: À sua classe LeadCaptureTurnAction.
  2. Acesso ao Objeto: Permissões de Leitura e Criação no objeto Lead.
  3. Permissões de Campo: Acesso de edição aos campos LastName e Company.

Atribua este Conjunto de Permissões ao usuário Einstein Service Agent. Sem ele, o agente ficará em loop infinito, solicitando campos que já coletou porque a falha silenciosa do DML em USER_MODE impede que isSuccess retorne true.

4. Testando o Agente Localmente

Antes de publicar, você deve validar a lógica de múltiplas interações usando o Salesforce CLI. O comando sf agent preview permite simular a conversa diretamente do seu terminal.

# Iniciar a sessão
sf agent preview start --json --authoring-bundle LeadCaptureAgent --use-live-actions --target-org my-org

# Enviar a primeira fala (apenas Empresa)
sf agent preview send --json --session-id <SESSION_ID> --utterance "Minha empresa é Acme Corp" --authoring-bundle LeadCaptureAgent --target-org my-org

# Enviar a segunda fala (Sobrenome)
sf agent preview send --json --session-id <SESSION_ID> --utterance "Meu sobrenome é Smith" --authoring-bundle LeadCaptureAgent --target-org my-org

# Verificar a criação do Lead
sf data query --query "SELECT Id, LastName, Company FROM Lead ORDER BY CreatedDate DESC LIMIT 1" --target-org my-org

O Ponto Principal

O Agentforce nos permite criar experiências de conversação incrivelmente dinâmicas, mas requer uma mudança na forma como lidamos com estado e segurança. Ao direcionar a captura de leads através de um subagente dedicado e confiar em ações invocáveis Apex para gerenciamento de estado determinístico, você garante uma experiência segura, resiliente e amigável ao usuário.

Lembre-se sempre de usar String para saídas de ID, impor DML em USER_MODE e atribuir os conjuntos de permissões corretos ao seu usuário agente.

Sobre o Autor: Este guia é escrito pela equipe editorial técnica da Resumity, explorando a interseção de plataformas modernas de IA e arquitetura de CRM empresarial.