Agentforce Goes Where Your Users Are
Agentforce Employee Agent (AEA) delivers powerful conversational AI experiences inside Salesforce. But your users don’t always live inside Salesforce. They interact with custom portals, internal tools, partner-facing dashboards, and standalone web applications that sit entirely outside the Salesforce domain.
The Agentforce Conversation Client (ACC) Web SDK bridges this gap. It allows you to embed the same rich, production-quality AEA conversational experience into any external web application — regardless of frontend framework. React, Vue, Angular, or vanilla JavaScript: the SDK is framework-agnostic by design.
How the SDK Works: Lightning Out 2.0 Under the Hood
The SDK ships as an npm package — @salesforce/agentforce-conversation-client — that you install like any other JavaScript dependency. Being framework-agnostic, it has no opinions about your build system, component library, or state management approach.
Under the surface, the SDK is built on Lightning Out 2.0 as a Lightning Web Component Interface (LWCI). This means the full ACC conversational UI is a production-grade Lightning Web Component that has been engineered to render outside of a Salesforce domain. It carries with it the same rendering engine, streaming infrastructure, and Lightning Types support that powers the native Salesforce experience.
Here’s how the pieces fit together:
Your Web App Salesforce
+---------------------------+ +----------------------------------+
| React / Vue / Vanilla JS | | External Client App (ECA) |
| | | OAuth 2.0 credentials |
| 1. Get access_token -----+------->| |
| (server-side OAuth) |<-------+-- access_token |
| | +----------------------------------+
| 2. Build frontdoor URL |
| /secur/frontdoor.jsp | +----------------------------------+
| ?sid=<token> | | Agentforce Infrastructure |
| | | |
| 3. embedAgentforceClient(|------->| Session negotiation |
| { frontdoorUrl, | | Streaming transport |
| agentId, |<-------| Lightning Types rendering |
| container }) | | Conversation state mgmt |
| | +----------------------------------+
| 4. Chat UI renders in |
| your DOM container |
+---------------------------+The key split: you handle authentication (getting a fresh access token and building the frontdoor URL). The SDK handles everything else — session negotiation, real-time message transport, streaming, UI rendering, and conversation state. You don’t build the chat UI. You configure it, style it, and place it.
Authentication: What the SDK Expects
The SDK doesn’t handle OAuth itself — it expects a pre-authenticated frontdoor URL. You need four things in place in your Salesforce org:
- External Client App (ECA) configured to manage OAuth 2.0 credentials for your web application
- Trusted Domains registered so Salesforce permits rendering in your application’s origin
- A frontdoor URL constructed from a valid access token (typically
https://your-domain.my.salesforce.com/secur/frontdoor.jsp?sid=<access_token>) - An Agent ID — the 18-character identifier for your deployed Employee Agent (starts with
0Xx)
Once configured, your app’s runtime job is simply: get a fresh access token, build the frontdoor URL, pass it to the SDK. For complete setup instructions, refer to the official ACC SDK prerequisites documentation.
One Function, One Configuration Object
Here’s where it gets interesting. The entire integration surface is a single async function: embedAgentforceClient(). You call it with a configuration object, and the SDK handles the rest.
import { embedAgentforceClient } from '@salesforce/agentforce-conversation-client';
const { loApp } = await embedAgentforceClient({
container: document.getElementById('agent-container'),
frontdoorUrl: 'https://your-domain.my.salesforce.com/secur/frontdoor.jsp?sid=...',
agentforceClientConfig: {
agentId: '0XxXXXXXXXXXXXXXXX',
renderingConfig: {
mode: 'inline',
width: '100%',
height: '600px',
headerEnabled: true,
agentLabel: 'Support Agent',
styleTokens: {
headerBlockBackground: '#0176d3',
headerBlockTextColor: '#ffffff',
},
},
},
});Let’s break down what each property does:
container — any DOM element where the chat UI renders. In React, a useRef target. In Vue, a template ref. In vanilla JS, a querySelector result.
frontdoorUrl — the authenticated session handoff. This URL embeds your access token and tells the SDK how to establish the user’s session.
agentforceClientConfig.agentId — routes the conversation to your specific deployed Employee Agent. The 18-character ID from Setup.
renderingConfig — controls the visual presentation: display mode, dimensions, header visibility, and the label shown to users.
styleTokens — brand-level visual overrides (colors, backgrounds, text styling) applied consistently across the SDK’s rendered components.
The function returns a promise that resolves with loApp — a reference to the Lightning Out application instance for programmatic lifecycle control. Most use cases won’t need it; the SDK manages its own state once initialized.
Inline vs. Floating: Choosing Your UX Pattern
The SDK supports two rendering modes for different use cases:
Inline mode (mode: 'inline') renders the chat directly into your container element. You control the exact dimensions, placement, and surrounding layout. Use this for dedicated agent pages, embedded support panels, or dashboard layouts where the conversation is a primary interaction.
Floating mode (mode: 'floating') renders a Floating Action Button (FAB) that expands into a chat panel overlay on click. The SDK manages its own positioning and expand/collapse behavior. This is your “always available” assistant pattern — the agent supplements page content without consuming dedicated layout space.
Both modes deliver identical capabilities — streaming, Lightning Types, message state management. The only difference is how the UI claims space. Inline requires explicit width and height; floating handles its own dimensions.
Making It Yours: Style Tokens
The styleTokens object gives you systematic control over the SDK’s look without resorting to CSS overrides or shadow DOM hacks. Tokens like headerBlockBackground and headerBlockTextColor let you align the agent UI with your brand palette — stable, versioned, and documented.
Why not just target CSS classes? Because the SDK renders inside its own component boundary. Selectors break across versions, specificity wars with shadow DOM are painful — style tokens are the supported customization surface.
Looking forward, Agentforce Vibes lets you refine styling through natural-language prompts — describe the look you want, and the system translates that into token values. That’s where this is heading: declarative intent over manual configuration.
What You Get
That single embedAgentforceClient() call gives you capabilities that would take significant engineering effort to build from scratch:
Token-by-token streaming — responses arrive progressively with the typing feel users expect from modern AI interfaces. The SDK manages the streaming connection and incremental DOM updates.
Dynamic Lightning Types rendering — the agent doesn’t just return text. It renders structured, interactive UI components (forms, selection lists, cards, property displays) directly in the conversation thread. Lightning Types map automatically to the correct renderers.
Real-time message state management — optimistic updates, delivery confirmation, retry logic, and conversation continuity. No state machine to build, no WebSocket connections to manage.
All of this from one function call and one config object. No transport plumbing, no custom rendering pipeline, no conversation state sync logic.
Conclusion
The ACC Web SDK turns what would be weeks of custom chat UI development into a single function call. You get streaming, Lightning Types, brand styling, and full conversation state management — all rendered outside of Salesforce — with zero UI code on your end.
If your users interact with portals, dashboards, or tools that live outside Salesforce, this is how you bring Agentforce to them. One npm package, one config object, production-grade conversational AI wherever your web app runs.