ACC API: Como Invocar Agentes Agentforce Direto de Components LWC

A forma como os usuários interagem com agentes de IA dentro do Salesforce mudou de maneira significativa com o lançamento da API Agentforce Conversation Client (ACC). Em vez de depender exclusivamente do painel lateral nativo, desenvolvedores agora podem controlar conversas com agentes Agentforce diretamente a partir de componentes Lightning Web Components — abrindo, fechando e enviando utterances de forma programática.

Se você já precisou criar uma experiência de IA integrada dentro do Salesforce Lightning, provavelmente enfrentou o mesmo problema: como fazer com que o agente certo seja acionado no momento certo, sem que o usuário precise navegar manualmente pelo painel lateral. A ACC API resolve exatamente isso.

O Que É a Agentforce Conversation Client API

A ACC API é um módulo headless do LWC (lightning/accApi) que funciona como um roteador de mensagens entre componentes customizados e o painel nativo do Agentforce. Ela permite que qualquer componente LWC em páginas de registro ou home inicie e gerencie conversas com agentes de IA de forma transparente.

A arquitetura por trás da ACC não é trivial. O framework já processa mais de 2,5 milhões de ações em interfaces como o sidebar do CRM, dashboards do Tableau e o próprio Agentforce for Setup. Quando você usa a ACC API, está se conectando a uma infraestrutura de larga escala que cuida de streaming de respostas, renderização de componentes interativos e gerenciamento de conexão em tempo real.

Pré-requisitos para Implementação

Antes de começar a codificar, é importante garantir que o ambiente atenda a alguns requisitos específicos:

Interface: a funcionalidade funciona exclusivamente no Lightning Experience desktop. Tableau, SentOS e outras interfaces não são suportadas.
Versão da API: o módulo lightning/accApi requer API version 59.0 ou superior.
Agentforce habilitado: a org precisa ter o Agentforce ativo. Sem essa configuração, os métodos da API simplesmente não estarão disponíveis.

Os Três Métodos Essenciais

A ACC API expõe três métodos principais que cobrem praticamente todos os cenários de interação programática com o painel do Agentforce:

1. open() — Abrir o Painel

O método open() abre o painel lateral do Agentforce e, opcionalmente, já inicia a conversa com um agente específico. Isso é útil quando você quer que o contexto do registro atual seja automaticamente transmitido ao agente.

2. execute() — Enviar Utterance

import { open } from "lightning/accApi";

export default class MeuComponente extends LightningElement {
    async handleAbrirAgente() {
        try {
            await open();
            console.log("Painel do Agentforce aberto com sucesso");
        } catch (erro) {
            console.error("Erro ao abrir painel:", erro);
        }
    }
}
Code language: JavaScript (javascript)

O método execute() é o mais poderoso dos três. Ele envia um texto diretamente para o agente como se o usuário tivesse digitado a mensagem. Isso permite que componentes customizados disparem ações específicas no agente — desde consultas a dados até execução de fluxos de trabalho complexos.

import { execute } from "lightning/accApi";

export default class QualificadorLead extends LightningElement {
    @api recordId;

    async handleQualificarLead() {
        try {
            await execute("Analise o lead com ID " + this.recordId + " e forneça uma recomendação de qualificação");
        } catch (erro) {
            console.error("Erro ao enviar utterance:", erro);
        }
    }
}Code language: JavaScript (javascript)

3. close() — Fechar o Painel

O método close() encerra a interação e fecha o painel lateral. Útil em cenários onde o componente precisa controlar o ciclo de vida completo da conversa.

import { close } from "lightning/accApi";

export default class MeuComponente extends LightningElement {
    async handleFecharPainel() {
        try {
            await close();
        } catch (erro) {
            console.error("Erro ao fechar painel:", erro);
        }
    }
}Code language: JavaScript (javascript)

Configuração do Componente meta.xml

Para que o componente LWC com a ACC API funcione corretamente em páginas de registro e home, é necessário adicionar os targets adequados no arquivo de metadados:

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>59.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__RecordPage</target>
        <target>lightning__AppPage</target>
        <target>lightning__HomePage</target>
    </targets>
</LightningComponentBundle>Code language: HTML, XML (xml)

Caso de Uso Real: Assistente de Oportunidade Integrado à Página

Imagine que o time de vendas precisa de um assistente inteligente diretamente na página de detalhes da oportunidade. Em vez de pedir que cada vendedor abra o painel lateral, busque o agente correto e digite a pergunta, o componente LWC já faz tudo isso automaticamente.

import { LightningElement, api, wire } from "lwc";
import { getRecord, getFieldValue } from "lightning/uiRecordApi";
import { open, execute, close } from "lightning/accApi";

import STAGE_NAME from "@salesforce/schema/Opportunity.StageName";
import AMOUNT from "@salesforce/schema/Opportunity.Amount";
import CLOSE_DATE from "@salesforce/schema/Opportunity.CloseDate";

const CAMPOS = [STAGE_NAME, AMOUNT, CLOSE_DATE];

export default class AssistenteOportunidade extends LightningElement {
    @api recordId;
    mensagem = "";
    analiseCarregando = false;

    @wire(getRecord, { recordId: "$recordId", fields: CAMPOS })
    oportunidade;

    get estagioAtual() {
        return getFieldValue(this.oportunidade.data, STAGE_NAME);
    }

    async handleAnaliseRisco() {
        this.analiseCarregando = true;
        try {
            await open();
            const prompt = "Analise a oportunidade " + this.recordId +
                " no estagio " + this.estagioAtual +
                ". Identifique riscos de perda e sugira acoes para avancar.";
            await execute(prompt);
        } catch (erro) {
            this.mensagem = "Erro ao iniciar analise: " + erro.message;
        } finally {
            this.analiseCarregando = false;
        }
    }

    async handleSugereProximosPassos() {
        try {
            await execute("Com base no historico da oportunidade " +
                this.recordId + ", sugira os 3 proximos passos prioritarios");
        } catch (erro) {
            this.mensagem = "Erro: " + erro.message;
        }
    }

    async handleFechar() {
        await close();
    }
}Code language: JavaScript (javascript)

O HTML do componente fica assim:

<template>
    <lightning-card title="Assistente de Oportunidade" icon-name="custom:custom18">
        <div class="slds-p-around_medium">
            <template lwc:if={mensagem}>
                <div class="slds-notify slds-notify_alert slds-alert_error">
                    {mensagem}
                </div>
            </template>

            <div class="slds-m-top_medium">
                <lightning-button
                    label="Analise de Risco com IA"
                    variant="brand"
                    onclick={handleAnaliseRisco}
                    disabled={analiseCarregando}
                    class="slds-m-right_small">
                </lightning-button>

                <lightning-button
                    label="Sugerir Proximos Passos"
                    onclick={handleSugereProximosPassos}
                    class="slds-m-right_small">
                </lightning-button>

                <lightning-button
                    label="Fechar Assistente"
                    variant="neutral"
                    onclick={handleFechar}>
                </lightning-button>
            </div>
        </div>
    </lightning-card>
</template>Code language: HTML, XML (xml)

ACC API vs. ACC Web SDK: Qual Usar?

Uma dúvida comum entre desenvolvedores é quando usar a ACC API versus o ACC Web SDK. A distinção é mais simples do que parece:

Use a ACC API quando o componente está dentro do Salesforce Lightning Experience — ou seja, dentro da própria plataforma. É o caminho mais direto, com menos configuração e sem dependências externas.

Use o ACC Web SDK quando precisa integrar a experiência conversacional do Agentforce em aplicações web externas — sites, portais customizados ou dashboards fora do Salesforce. O SDK oferece recursos de styling, streaming e feedback prontos para uso.

Para a maioria dos cenários de desenvolvimento dentro do Salesforce, a ACC API é a escolha correta.

Padrões de Arquitetura para Projetos Reais

Padrão 1: Botão de Ação Contextual

O padrão mais simples. Um botão na página de registro abre o painel e envia um utterance pré-configurado com o contexto do registro. Ideal para ações repetitivas como qualificação de lead, análise de risco ou resumo de caso.

Padrão 2: Wizard com Múltiplas Etapas

Componentes que guiam o usuário por um processo com etapas, onde cada etapa pode invocar o agente para validar dados, sugerir preenchimentos ou executar verificações automáticas. O componente controla o fluxo enquanto o agente fornece inteligência em cada etapa.

Padrão 3: Dashboard com Agentes Especializados

Páginas home ou app pages que oferecem acesso rápido a múltiplos agentes — cada um especializado em uma área diferente. O componente gerencia qual agente é acionado com base na ação do usuário, sem que ele precise saber qual agente específico está por trás.

Limitações Importantes

A ACC API é poderosa, mas tem restrições que precisam ser consideradas na arquitetura:

Apenas Lightning Experience desktop: a API não funciona no Salesforce Mobile App nem em experiências Community/Experience Cloud.
Painel padrão apenas: interfaces customizadas do Agentforce ou integrações com Tableau não são suportadas pela ACC API (use o Web SDK para esses casos).
Sem controle sobre o agente em si: a API gerencia o painel e as mensagens, mas não permite configurar o comportamento do agente. Para isso, use o Agent Builder.
Uma conversa por vez: o painel lateral suporta uma conversa ativa. Se precisar de múltiplas conversas simultâneas, considere uma arquitetura com múltiplos componentes ou o Web SDK.

Impacto para Desenvolvedores e Empresas

A ACC API representa uma mudança fundamental na forma como experiências de IA são construídas no Salesforce. Antes dela, integrar um agente em uma tela customizada significava construir toda a infraestrutura conversacional do zero — gerenciamento de estado, streaming de respostas, renderização de componentes interativos. Agora, com três métodos simples, qualquer componente LWC pode se conectar à mesma infraestrutura que processa milhões de interações no Salesforce.

Para empresas, o impacto é direto: redução do tempo de adoção de agentes de IA. Em vez de treinar usuários para encontrar e usar o painel lateral, os desenvolvedores podem incorporar a IA nos fluxos de trabalho existentes. O agente aparece quando e onde é necessário, com o contexto já carregado.

Conclusão

A Agentforce Conversation Client API é uma das funcionalidades mais subestimadas do Summer ’26. Ela não apenas simplifica a integração de agentes em componentes customizados como estabelece um padrão arquitetural para o futuro das experiências conversacionais no Salesforce.

Se você é desenvolvedor LWC e ainda não explorou a ACC API, agora é o momento. Comece com um botão simples de ação contextual em uma página de registro e expanda a partir dái. A documentação oficial da Salesforce oferece guias completos para cada cenário de integração.

Quer trocar ideia sobre implementações com a ACC API? Deixe um comentário ou compartilhe sua experiência nas redes sociais. O ecossistema Salesforce cresce quando desenvolvedores compartilham conhecimento prático.

ACC API: Como Invocar Agentes Agentforce Direto de Components LWC

Byluisfernandobrito