Como Desenvolvedores Salesforce Constroem e Expõem Métodos Invocable Apex, Flows e APIs MuleSoft como Ações no Agentforce

O Salesforce Agentforce redefine a inteligência artificial corporativa, transformando assistentes conversacionais passivos em agentes autônomos (Autonomous Agents). Em cenários de negócios reais, um agente não deve apenas responder perguntas a partir de artigos de conhecimento, mas também interpretar a intenção do cliente, selecionar ferramentas corporativas especializadas, executar transações em tempo real e avaliar os resultados para orquestrar os próximos passos operacionais.

As ações padrão fornecidas nativamente atendem a tarefas rotineiras de CRM, como rascunhar e-mails e resumir registros. No entanto, as operações corporativas exigem regras de negócios proprietárias, integrações complexas com sistemas legados e dados externos em tempo real. Desenvolvedores e arquitetos corporativos do ecossistema Salesforce expandem as capacidades do Agentforce criando Ações Personalizadas (Custom Actions) fundamentadas em três pilares:

1. Métodos Invocable Apex: Lógica programática determinística para cálculos avançados, validações rigorosas e manipulação sofisticada de dados.
2. Fluxos Autoiniciados sem Interface (Autolaunched Flows): Automações declarativas de baixo código para operações de CRUD e aprovações sem necessidade de desenvolvimento manual.
3. APIs MuleSoft via External Services e API Catalog: Conectores corporativos que integram ERPs legados (como SAP e Oracle), gateways de pagamento e microsserviços diretamente ao tempo de execução do agente.

Este guia detalha a arquitetura ponta a ponta, os passos técnicos de implementação, as melhores práticas de engenharia de contexto (Context Engineering) e as diretrizes de governança de segurança para disponibilizar essas ações no Agentforce.

1. Arquitetura Central: Como o Mecanismo de Raciocínio Atlas Compreende e Executa Ações

Para construir ações resilientes e livres de alucinações, é indispensável entender o funcionamento do cérebro do Agentforce: o mecanismo de raciocínio Atlas (Atlas Reasoning Engine).

[ Interação do Usuário / Canais Omni-Channel ]
                       │
                       ▼
         [ Mecanismo de Raciocínio Atlas ]
        (ReAct: Raciocinar - Agir - Observar)
                       │
       ┌───────────────┼───────────────┐
       ▼               ▼               ▼
[ Classificação de Tópicos ] │ [ Guardrails e Filtro de Contexto ]
       │               │
       └───────┬───────┘
               ▼
     [ Seleção de Ação / Ferramenta ]
               │
   ┌───────────┼───────────┐
   ▼           ▼           ▼
[ Apex ]    [ Flow ]   [ MuleSoft / API ]
   │           │           │
   └───────────┼───────────┘
               ▼
[ Saída Estruturada Observada pelo Atlas ]
               │
               ▼
[ Resposta Final ou Próxima Ação Orquestrada ]

O Padrão ReAct e a Engenharia de Contexto

O motor Atlas opera com base no ciclo ReAct (Reason - Act - Observe):

• Raciocinar (Reason): Avalia a solicitação do usuário em relação aos Tópicos (Topics) configurados e determina qual ferramenta específica (Ação) é adequada para atender à necessidade.
• Agir (Act): Extrai os parâmetros necessários do diálogo, preenche o esquema de entrada da ação e realiza a invocação.
• Observar (Observe): Analisa o resultado estruturado retornado pela ação, verifica se o objetivo foi atingido e decide se deve executar uma ação subsequente ou gerar a resposta final em linguagem natural.

No desenvolvimento de software convencional, a comunicação entre classes depende de tipos estritos e chamadas diretas. No paradigma dos agentes autônomos, os metadados atuam como prompt. O modelo de linguagem não lê o código-fonte interno do Apex; ele interpreta o label, a description, as anotações dos parâmetros e as instruções da ação (Action Instructions). Descrições vagas provocam confusão e erros de extração, enquanto metadados precisos asseguram execuções determinísticas.

2. Construindo e Expondo Invocable Apex como Ações Personalizadas

O Invocable Apex é a escolha indicada quando o processo de negócio exige lógica algorítmica complexa, processamento em lote, consultas SOQL elaboradas ou integração de segurança personalizada.

Passo 1: Desenvolver a Classe Invocable Apex

O Agentforce detecta métodos Apex por meio da anotação @InvocableMethod. O método precisa ser declarado como public ou global, ser estático e aceitar uma lista (List) de objetos de entrada, retornando uma lista (List) de objetos de saída.

Veja uma implementação profissional para cancelamento de pedidos:

public with sharing class OrderCancellationService {

    // Wrapper de entrada: Parâmetros exigidos pelo agente
    public class OrderCancellationRequest {
        @InvocableVariable(
            label = 'Order Number' 
            description = 'Identificador alfanumérico do pedido a ser cancelado, por exemplo ORD-10023.' 
            required = true
        )
        public String orderNumber;

        @InvocableVariable(
            label = 'Cancellation Reason' 
            description = 'Justificativa apresentada pelo cliente para o cancelamento.' 
            required = false
        )
        public String reason;
    }

    // Wrapper de saída: Dados estruturados retornados ao motor Atlas
    public class OrderCancellationResult {
        @InvocableVariable(
            label = 'Is Success' 
            description = 'Flag booleano que indica se o cancelamento foi concluído com sucesso.'
        )
        public Boolean isSuccess;

        @InvocableVariable(
            label = 'Cancellation Reference Code' 
            description = 'Código de protocolo de auditoria gerado para a operação.'
        )
        public String referenceCode;

        @InvocableVariable(
            label = 'Status Message' 
            description = 'Mensagem de resultado ou motivo detalhado em caso de falha.'
        )
        public String message;
    }

    @InvocableMethod(
        label = 'Cancel Customer Order'
        description = 'Cancela um pedido pendente e emite um código de protocolo. Utilize esta ação somente quando o status do pedido for Pending ou Processing e o cliente solicitar explicitamente o cancelamento.'
        category = 'Order Management'
    )
    public static List<OrderCancellationResult> cancelOrders(List<OrderCancellationRequest> requests) {
        List<OrderCancellationResult> results = new List<OrderCancellationResult>();

        for (OrderCancellationRequest req : requests) {
            OrderCancellationResult res = new OrderCancellationResult();
            
            try {
                // Execução estrita no modo de usuário (User Mode)
                List<Order> orders = [
                    SELECT Id, Status, TotalAmount 
                    FROM Order 
                    WHERE OrderNumber = :req.orderNumber 
                    WITH USER_MODE 
                    LIMIT 1
                ];

                if (orders.isEmpty()) {
                    res.isSuccess = false;
                    res.message = 'Nenhum pedido ativo localizado com o número: ' + req.orderNumber;
                    results.add(res);
                    continue;
                }

                Order targetOrder = orders[0];
                if (targetOrder.Status == 'Activated' || targetOrder.Status == 'Completed') {
                    res.isSuccess = false;
                    res.message = 'O pedido ' + req.orderNumber + ' já foi expedido ou concluído e não pode ser cancelado automaticamente.';
                    results.add(res);
                    continue;
                }

                targetOrder.Status = 'Cancelled';
                targetOrder.Description = 'Cancelado via Agentforce. Motivo: ' + (req.reason != null ? req.reason : 'Não informado');

                Database.SaveResult sr = Database.update(targetOrder, AccessLevel.USER_MODE);
                if (sr.isSuccess()) {
                    res.isSuccess = true;
                    res.referenceCode = 'CAN-' + System.currentTimeMillis();
                    res.message = 'Pedido cancelado com sucesso.';
                } else {
                    res.isSuccess = false;
                    res.message = 'Falha ao atualizar o registro no banco de dados.';
                }
            } catch (Exception ex) {
                res.isSuccess = false;
                res.message = 'Erro interno ao processar o cancelamento: ' + ex.getMessage();
            }

            results.add(res);
        }

        return results;
    }
}

Boas Práticas Essenciais em Apex para Agentforce

• Evitar Classes Monolíticas (God Classes): Não reúna consulta, cálculo, cobrança e expedição em uma única ação gigante. Mantenha cada ação focada em um objetivo para permitir que o motor Atlas orquestre passos de forma transparente.
• Retornar Erros Estruturados em vez de Exceções Não Tratadas: Exceções não capturadas interrompem o fluxo de raciocínio do agente. Capture as exceções e retorne isSuccess = false acompanhado de uma message compreensível, capacitando o agente a orientar o usuário ou pedir dados adicionais.
• Segurança em User Mode: Adote sempre WITH USER_MODE e AccessLevel.USER_MODE nas operações de DML para garantir o respeito aos perfis e permissões de campo do Agent User.

Passo 2: Registrar a Ação Apex no Salesforce Setup

1. Em Setup (Configuração) do Salesforce, digite Agent na Busca Rápida e clique em Agentforce Assets (ou Agent Actions).
2. Clique em New Agent Action (Nova Ação de Agente).
3. No campo Reference Action Type (Tipo de Ação de Referência), selecione Apex.
4. Localize a classe OrderCancellationService e o método Cancel Customer Order.
5. Revise as propriedades pré-preenchidas a partir das anotações do código.
6. Em Action Instructions (Instruções da Ação), detalhe os critérios de disparo (por exemplo: «Acione esta ação somente quando um cliente autenticado solicitar explicitamente o cancelamento. Solicite o número do pedido se não for informado»).
7. Salve a ação.

3. Construindo e Expondo Fluxos Autoiniciados como Ações

Para operações declarativas de CRUD, acionamento de fluxos de aprovação e reutilização de regras existentes, o Autolaunched Flow oferece entrega ágil e fácil manutenção por administradores.

Restrição de Tipo de Fluxo

O Agentforce suporta exclusivamente Fluxos Autoiniciados sem Gatilho (Autolaunched Flow - No Trigger). Fluxos de tela (Screen Flows) dependem de interface visual para humanos e fluxos acionados por registro respondem a eventos de banco de dados; nenhum dos dois se aplica a agentes headless. O fluxo autoiniciado fornece uma interface estrita de requisição e resposta.

[ Solicitação do Usuário: "Atualize meu endereço de entrega para Av. Paulista, 1000" ]
                               │
                               ▼
              [ Planejador de Ações do Agentforce ]
                               │
         (Extrai parâmetros: orderId, streetAddress, city)
                               │
                               ▼
      [ Autolaunched Flow: Atualizar Endereço do Pedido ]
               ┌─────────────────────────┐
               │ Get Records: Pedido     │
               ├─────────────────────────┤
               │ Decision: Já Despachado?│
               ├─────────────────────────┤
               │ Update Records: Endereço│
               └─────────────────────────┘
                               │
       (Variáveis de saída: isUpdated = True, mensagem)
                               │
                               ▼
             [ Atlas Formula a Resposta Final ]

Configuração Passo a Passo no Flow Builder

1. Criar o Fluxo: Abra o Flow Builder e escolha Autolaunched Flow (No Trigger).
2. Definir Variáveis de Entrada:
   • Crie a variável de texto var_orderId.
   • Marque a opção Available for input (Disponível para entrada).
   • Em Description (Descrição), insira: «ID de 18 caracteres do registro de Pedido no Salesforce».
   • Crie as demais variáveis de entrada (var_streetAddress, etc.) com descrições objetivas.
3. Definir Variáveis de Saída:
   • Crie a variável booleana var_isUpdated. Marque Available for output (Disponível para saída). Descrição: «Verdadeiro se o endereço foi atualizado no banco de dados».
   • Crie a variável de texto var_statusMessage e marque-a como disponível para saída.
4. Construir a Lógica:
   • Adicione o elemento Get Records para carregar o pedido.
   • Adicione um elemento Decision para validar o status da entrega.
   • Use um elemento Update Records para gravar o novo endereço.
   • Use um elemento Assignment para preencher as variáveis de saída.
5. Salvar e Ativar: Salve como Agent_Update_Order_Address e ative o fluxo.

Passo 3: Registrar a Ação de Fluxo

1. Acesse Setup > Agentforce Assets > New Agent Action.
2. Selecione Reference Action Type = Flow.
3. Escolha o fluxo Agent_Update_Order_Address.
4. Valide se as descrições das variáveis de entrada e saída são claras para o entendimento da IA.
5. Defina as instruções da ação e conclua o cadastro.

4. Expondo APIs MuleSoft via External Services e API Catalog

Agentes corporativos frequentemente precisam acessar dados fora do Salesforce, como estoques em SAP, históricos de faturamento no Oracle ou sistemas de rastreamento logístico. A plataforma MuleSoft gerencia a integração e a segurança, enquanto o Salesforce expõe essas APIs como ações no Agentforce por meio de External Services (Serviços Externos) e do Salesforce API Catalog.

Comparação entre Abordagens de Integração

[ ERP Corporativo / SAP / Banco Legado ]
                   │
                   ▼
     [ MuleSoft Anypoint Platform ]
  (System, Process, Experience APIs)
                   │
     (Topic Center / Especificações OAS 3.0)
                   │
                   ▼
  [ Conexão e Sincronização no Salesforce ]
                   │
      ┌────────────┴────────────┐
      ▼                         ▼
[ Named Credentials ]   [ Salesforce API Catalog ]
 (Autenticação Segura)    (Descoberta Unificada)
      │                         │
      └────────────┬────────────┘
                   ▼
       [ External Services ]
    (Gera Ações Invocáveis)
                   │
                   ▼
  [ Catálogo de Ações do Agentforce ]

Passo 1: Projetar Especificações OpenAPI Otimizadas para IA

O motor Atlas inspeciona a especificação OpenAPI para identificar rotas, parâmetros e formatos de retorno. Para garantir uma boa interpretação pelo agente:

• Descrições Detalhadas em Todos os Atributos: Cada parâmetro de rota, consulta e propriedade JSON precisa de uma description clara.
• Estruturas Planas e Diretas: Evite tipos polimórficos (oneOf, anyOf) e estruturas aninhadas excessivamente profundas.
• Status e Payloads de Erro Informativos: Defina códigos de status padrão (200, 400, 404, 500) com corpos JSON explicativos em falhas.

Exemplo de especificação OpenAPI 3.0 para consulta de inventário:

openapi: 3.0.3
info:
  title: Enterprise Warehouse API
  version: 1.0.0
  description: Consulta de estoque de depósito e disponibilidade em tempo real.
paths:
  /inventory/{sku}:
    get:
      summary: Consultar estoque de armazém por SKU
      description: Retorna quantidade disponível, depósito de origem e prazo de reposição para um SKU de produto.
      operationId: getInventoryBySku
      parameters:
        - name: sku
          in: path
          required: true
          description: Código identificador do produto, por exemplo PROD-WIDGET-99.
          schema:
            type: string
      responses:
        '200':
          description: Consulta realizada com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  sku:
                    type: string
                    description: O código SKU consultado.
                  quantityOnHand:
                    type: integer
                    description: Quantidade de unidades físicas no armazém.
                  isAvailableToShip:
                    type: boolean
                    description: Indica se o item pode ser expedido imediatamente.
                  warehouseRegion:
                    type: string
                    description: Região do centro de distribuição responsável.
        '404':
          description: SKU não localizado no catálogo

Passo 2: Sincronizar e Publicar a Ação no Salesforce

1. Configurar Conexão com Anypoint: No Setup do Salesforce, acesse Anypoint Platform Setup e autentique a conexão com o Organization ID e credenciais.
2. Sincronização no API Catalog: No MuleSoft Topic Center ou Exchange, aplique a tag sf-api-catalog. No API Catalog do Salesforce, ative as operações desejadas como ações.
3. Configurar Named Credentials: Vincule uma credencial nomeada com OAuth 2.0 para chamadas seguras.
4. Criar Ação de Serviço Externo: Em Agentforce Assets, crie a nova ação escolhendo o tipo External Service e associe a operação correspondente.

5. Orquestração no Agentforce Builder (Camada de Tópicos)

As ações não atuam isoladas; elas precisam ser organizadas sob um Tópico (Topic) dentro do Agentforce Builder. Os tópicos delimitam o domínio de atuação e o escopo funcional do agente.

[ Agente Autônomo: Agente de Atendimento ao Cliente ]
                        │
        ┌───────────────┴───────────────┐
        ▼                               ▼
[ Tópico: Logística de Pedidos ]    [ Tópico: Suporte Técnico ]
 (Classificação e Escopo)            (Classificação e Escopo)
        │
    ┌───┴───────────────────────────────┐
    ▼                                   ▼
[ Ação: Consultar Pedido ]          [ Ação: Cancelar Pedido ]
 (Autolaunched Flow)                 (Invocable Apex)

Passos de Configuração

1. Abra o Agentforce Builder no Setup e edite o agente desejado.
2. Selecione um tópico existente ou clique em New Topic (ex.: Order Logistics and Changes).
3. Preencha a Topic Classification Description: Defina com clareza quais solicitações pertencem a este domínio.
4. Na aba Actions do tópico, clique em Add Action e adicione as ações criadas (Apex, Flow ou MuleSoft).

Redação de Instruções para o Tópico e Ações

As instruções em linguagem natural orientam o raciocínio do modelo:

### Instruções do Tópico: Order Logistics and Changes
- Ajude os clientes com rastreamento, status de pedidos, alteração de endereço e cancelamentos.
- Antes de cancelar um pedido, verifique o status atual e solicite a confirmação expressa do cliente.
- Caso o cancelamento falhe devido a envio concluído, oriente o cliente sobre a política de devolução.

### Instruções da Ação: Cancel Customer Order
- Execute esta ação somente após o cliente informar o número do pedido e confirmar o cancelamento.
- Se o número do pedido não for informado, pergunte: "Qual é o número do pedido que você gostaria de cancelar?"
- Ao concluir, informe sempre o código de protocolo (referenceCode) ao cliente.

Human-in-the-Loop e Confirmação Prévia

Para operações que alteram registros críticos, movimentam valores ou realizam cancelamentos, marque a opção Require Confirmation (Exigir Confirmação) nas propriedades da ação. O agente solicitará confirmação em linguagem natural (ex.: «Tem certeza de que deseja cancelar o pedido ORD-10023? Esta ação não pode ser desfeita») antes de acionar a lógica de backend.

6. Matriz Comparativa de Decisão Técnica

A escolha criteriosa da tecnologia para cada ação equilibra custo de desenvolvimento, facilidade de manutenção e desempenho operacional.

7. Estratégia de Testes, Permissões e Implantação

1. Permissões do Usuário do Agente (Agent User)

As ações são executadas sob o contexto do Agent User. Falhas frequentes após o lançamento decorrem de permissões ausentes:

• Acesso às Classes Apex: Garanta que o perfil ou Permission Set do Agent User tenha permissão de acesso à classe Apex.
• Acesso ao Flow: Verifique se o Agent User possui a permissão de sistema Run Flows e acesso ao fluxo específico.
• Named Credentials e FLS: Libere o acesso às credenciais nomeadas utilizadas e verifique a segurança em nível de campo (FLS) de leitura e escrita nos objetos afetados.

2. Estratégia de Testes em Três Camadas

1. Testes Unitários em Apex: Crie classes de teste com cobertura superior a 85%, validando entradas nulas, exceções de negócio e segurança em User Mode.
2. Testes Interativos no Agentforce Builder: Utilize o painel de chat para simular solicitações reais, conferindo no log de raciocínio se o motor Atlas escolhe o tópico certo, extrai os parâmetros necessários e interpreta os retornos.
3. Testes em Lote no Agentforce Testing Center: Avalie centenas de variações de perguntas automaticamente para mensurar precisão de seleção de ferramentas e taxa de alucinações.

Combinando o rigor técnico do Invocable Apex, a agilidade declarativa dos Autolaunched Flows e o alcance corporativo das APIs MuleSoft, equipes de desenvolvimento constroem agentes de IA seguros, eficientes e escaláveis na plataforma Salesforce.

Referências

• Agent Customization with Apex | Salesforce Trailhead
• Learn How to Make Agent-Ready Flows | Salesforce Trailhead
• How to Write Effective Natural Language Instructions for Agentforce | Salesforce Developers Blog
• A Developer’s Guide to Context Engineering with Agentforce | Salesforce Developers Blog
• Salesforce Agentforce Specialist Certification Guide & Tips | Salesforce Ben
• External Services | Salesforce Help