Como transformar componentes Lightning Web Components em gatilhos inteligentes para o painel nativo de inteligência artificial, enviando comandos contextuais e dados não salvos em tempo de execução.
Durante as primeiras iterações do Agentforce, a interação do usuário com os agentes de inteligência artificial ocorria quase exclusivamente de maneira passiva: o usuário precisava clicar manualmente no ícone do painel lateral, digitar sua dúvida em linguagem natural e aguardar a resposta. Embora esse modelo funcione bem para consultas abertas, ele cria atrito em fluxos operacionais corporativos onde a interface já possui todo o contexto do registro aberto.
Para unir a experiência rica e estruturada dos componentes Lightning Web Components (LWC) com a flexibilidade conversacional do Agentforce, a Salesforce disponibilizou o módulo headless lightning/accApi (conhecido como Agentforce Conversation Client API, ou simplesmente ACC API).
Esse módulo atua como uma ponte programática entre o código JavaScript do seu componente front-end e o painel nativo do Agentforce no desktop. Com ele, um botão customizado na tela pode abrir o painel, selecionar o agente correto e disparar uma instrução estruturada contendo dados que o usuário acabou de digitar no formulário, mesmo antes do registro ser gravado no banco de dados.
Neste guia técnico, vamos explorar os métodos fundamentais da ACC API, analisar o fluxo de mensagens entre o LWC e o painel, e implementar um componente completo de assistência de casos pronto para produção.
1. O Que É o Módulo lightning/accApi?
O lightning/accApi é um módulo JavaScript sem interface gráfica (headless) que expõe métodos assíncronos para manipular o ciclo de vida do painel do Agentforce na experiência desktop do Lightning Experience.
Ele foi desenhado para atender a três casos de uso principais:
- Abertura e Fechamento Controlados: Permitir que botões de ação na página abram ou minimizem o painel lateral conforme a etapa do processo de negócio.
- Disparo de Utterances Programáticas: Enviar frases e instruções pré-formatadas diretamente para a caixa de diálogo do agente, simulando a digitação do usuário.
- Injeção de Contexto Volátil: Enviar valores de campos modificados na tela que ainda não passaram por um comando DML no backend, garantindo que o agente analise o estado mais recente da interação.
+-------------------------------------------------------------+
| Custom Lightning Web Component |
| (Ex: Botão "Analisar Risco de Churn" ou Formulário) |
+-------------------------------------------------------------+
|
import { open, execute } from 'lightning/accApi';
|
v
+-------------------------------------------------------------+
| Agentforce Conversation Client |
| (lightning/accApi Bridge) |
+-------------------------------------------------------------+
|
v [App-to-Panel Message Router]
+-------------------------------------------------------------+
| Painel Lateral Nativo do Agentforce |
| (Abre na tela, seleciona o agente e executa a instrução) |
+-------------------------------------------------------------+
2. Métodos Principais da ACC API
Para utilizar o módulo, você deve importá-lo no seu arquivo JavaScript definindo a versão mínima da API como 59.0 (recomendado 67.0 para desfrutar de todas as otimizações do runtime moderno).
Os métodos disponíveis são:
open(options)
Abre o painel lateral do Agentforce. Pode receber opcionalmente o identificador do agente (agentId ou botId) para o qual a conversa deve ser direcionada:
JavaScript
import { open } from 'lightning/accApi';
// Abertura simples do painel
await open();
// Abertura apontando para um Employee Agent específico
await open({ agentId: '0Xxxx0000000001CAA' });
close()
Fecha ou minimiza o painel lateral do Agentforce programaticamente:
JavaScript
import { close } from 'lightning/accApi';
await close();
execute(options)
O método mais poderoso da API. Ele abre o painel (caso esteja fechado), seleciona o agente especificado e envia uma mensagem de texto (utterance) como se tivesse sido redigida pelo operador:
JavaScript
import { execute } from 'lightning/accApi';
await execute({
agentId: '0Xxxx0000000001CAA',
text: 'Resuma as três últimas interações deste cliente e sugira a próxima melhor oferta.'
});
3. Arquitetura de UI Agêntica: Passando Valores Não Salvos ao Agentforce
Um dos maiores desafios em telas complexas de atendimento ou cotação é que o operador preenche vários campos de texto (como anotações de triagem ou justificativas de desconto) antes de salvar o registro. Se o agente de IA consultar apenas os dados gravados via SOQL ou Data Cloud, ele perderá as informações vitais que estão apenas na memória do navegador.
Com o lightning/accApi, o LWC captura os valores do formulário via JavaScript e monta uma utterance rica que inclui esses dados no prompt antes de disparar a execução.
Exemplo Prático: Componente caseAgentAssistant
Vamos construir um componente LWC para páginas de Caso (Case) que permite ao operador redigir uma anotação rápida de suporte e clicar em um botão para que o Agentforce redija uma resposta formal ao cliente considerando tanto o histórico do caso quanto a anotação provisória.
1. Template HTML: caseAgentAssistant.html
HTML
<template>
<lightning-card title="Assistente Agêntico de Atendimento" icon-name="standard:agentforce">
<div class="slds-p-around_medium">
<div class="slds-m-bottom_small">
<p class="slds-text-body_small slds-text-color_weak">
Utilize o Agentforce para gerar uma minuta de resposta técnica baseada nas anotações da triagem atual.
</p>
</div>
<!-- Campo de entrada com valores voláteis (não salvos no banco) -->
<lightning-textarea
name="triageNotes"
label="Anotações de Triagem em Tempo Real"
placeholder="Ex: Cliente relatou falha no módulo de faturamento após a atualização 2.4..."
value={triageNotes}
onchange={handleNotesChange}
rows="3"
required>
</lightning-textarea>
<div class="slds-m-top_medium slds-grid slds-grid_align-spread">
<lightning-button
label="Abrir Painel"
icon-name="utility:chat"
onclick={handleOpenPanel}>
</lightning-button>
<lightning-button
variant="brand"
label="Gerar Resposta com Agentforce"
icon-name="utility:magicwand"
onclick={handleGenerateResponse}
disabled={isGenerateDisabled}>
</lightning-button>
</div>
</div>
</lightning-card>
</template>
2. Controlador JavaScript: caseAgentAssistant.js
JavaScript
import { LightningElement, api, track } from 'lwc';
import { open, execute } from 'lightning/accApi';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';
export default class CaseAgentAssistant extends LightningElement {
@api recordId; // ID do Caso fornecido pelo contexto da página de registro
@track triageNotes = '';
// ID do agente especializado (pode ser configurado no Lightning App Builder)
@api targetAgentId = '';
get isGenerateDisabled() {
return !this.triageNotes || this.triageNotes.trim().length === 0;
}
handleNotesChange(event) {
this.triageNotes = event.target.value;
}
async handleOpenPanel() {
try {
await open(this.targetAgentId ? { agentId: this.targetAgentId } : {});
} catch (error) {
this.showToast('Erro', 'Não foi possível abrir o painel do Agentforce: ' + error.message, 'error');
}
}
async handleGenerateResponse() {
try {
// Monta a instrução incluindo o contexto do registro e os dados voláteis da tela
const promptText = `Atue como o especialista de suporte do Caso de ID ${this.recordId}. ` +
`O operador realizou as seguintes observações em tempo real: "${this.triageNotes}". ` +
`Por favor, consulte os manuais técnicos via Data Library e elabore uma minuta de resposta estruturada para o cliente.`;
const options = {
text: promptText
};
if (this.targetAgentId) {
options.agentId = this.targetAgentId;
}
// Dispara a ação no painel do Agentforce
await execute(options);
this.showToast('Sucesso', 'Instrução enviada ao Agentforce com sucesso.', 'success');
} catch (error) {
this.showToast('Falha na Execução', 'Erro ao enviar comando para o Agentforce: ' + error.message, 'error');
}
}
showToast(title, message, variant) {
this.dispatchEvent(new ShowToastEvent({ title, message, variant }));
}
}
3. Metadados de Configuração: caseAgentAssistant.js-meta.xml
XML
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
<apiVersion>67.0</apiVersion>
<isExposed>true</isExposed>
<masterLabel>Case Agentforce Assistant</masterLabel>
<description>Componente LWC que controla o painel do Agentforce enviando anotações de triagem.</description>
<targets>
<target>lightning__RecordPage</target>
<target>lightning__AppPage</target>
</targets>
<targetConfigs>
<targetConfig targets="lightning__RecordPage">
<objects>
<object>Case</object>
</objects>
<property name="targetAgentId" type="String" label="ID do Agente Alvo" description="Identificador único (18 dígitos) do Agentforce Agent para este fluxo." />
</targetConfig>
</targetConfigs>
</LightningComponentBundle>
4. Boas Práticas e Tratamento de Exceções com lightning/accApi
Ao implementar componentes baseados na ACC API em ambientes corporativos, siga estas diretrizes essenciais:
- Tratamento Elegante de Erros (Try/Catch): Chamadas a
open()ouexecute()podem falhar caso o usuário não possua permissão de acesso ao Agentforce ou esteja utilizando um navegador incompatível. Sempre envolva as chamadas em blocostry/catche notifique o usuário viaShowToastEvent. - Evite Sobrecarga de Prompts: Mantenha as instruções objetivas. Em vez de enviar o dump completo do registro na utterance, passe o
recordIde apenas os dados novos digitados pelo usuário, deixando que o agente recupere os campos complementares via SOQL ou grounding do Atlas Engine. - Idempotência e Prevenção de Múltiplos Cliques: Desabilite temporariamente o botão de disparo enquanto a Promise de
execute()estiver pendente para evitar o envio duplicado de comandos ao agente.
Conclusão
A chegada do módulo lightning/accApi representa a evolução definitiva da experiência do desenvolvedor front-end na era dos agentes autônomos. Ao permitir que componentes Lightning Web Components controlem o painel nativo do Agentforce de maneira programática, a Salesforce entrega aos arquitetos a capacidade de desenhar jornadas de trabalho fluidas, onde cliques em botões especializados e dados digitados na tela tornam-se gatilhos instantâneos para a ação da inteligência artificial.
Sua equipe já começou a integrar componentes LWC com o Agentforce em suas páginas de registro? Deixe suas dúvidas e experiências nos comentários abaixo ou compartilhe suas implementações com nossa comunidade no LinkedIn.