Platform
Headless Experience Layer: building AIforce widgets that work across interfaces
An agent can explain a quote in chat, but a buyer still needs to inspect its lines and confirm the change. Salesforce's Headless Experience Layer brings reusable widgets to Agentforce and external assistants. Learn what the beta supports, how to build the first widget, and which permission and confirmation checks belong in your pilot.
A quote needs a table before it needs another paragraph from an agent.
Your seller can ask an assistant to explain a renewal, but eventually someone has to inspect the products, change a quantity, and confirm the result. A chat response makes that work awkward. A small interactive widget can keep the conversation useful without making the seller describe every field in another message.
Salesforce’s Headless Experience Layer, or HXL, is designed for that gap. It lets you build reusable widgets for Agentforce and external assistants. Start with one read-only view over an existing, governed action. Add a write only after you have tested identity, stale data, and confirmation on each intended interface.
HXL adds an interface to the AIforce architecture
AIforce describes Salesforce capabilities reaching people in the tools where they work. Headless 360 provides the broader architecture for making those capabilities reachable. HXL supplies the interactive presentation: a record card, a table, or another widget that makes a result easier to inspect.
The distinction matters when you estimate the project. Connecting an assistant to an action gives it a way to retrieve or change data. It doesn’t automatically give the person a useful form for reviewing that data. You can have a working integration and still have a poor experience because the user has to approve a consequential change from a paragraph.
Salesforce’s September 28 Dreamforce announcement roundup describes HXL as a beta for rendering interactive widgets inside Agentforce or externally through a hosted MCP server. The developer guide names Agentforce, ChatGPT, Claude, and Slackbot as target interfaces.
Those are documented targets, not a promise that every widget behaves identically in every client you use. Treat client compatibility as part of your pilot. Check the actual renderer, authentication path, and interaction support before showing a buyer an interface that your chosen client cannot complete.
HXL also has a different job from Slackforce Surfaces. A prompt-generated dashboard answers an immediate reporting request. A widget you develop and deploy should have a defined purpose, an owner, and a release process. Decide which of those jobs you’re solving before picking the tool.
The beta has a concrete development path
The HXL prerequisites identify availability in API version 67.0 and later. They tell you to open Headless Experience Layer Settings in Setup, review the beta terms, and turn on the feature. Verify that your target org exposes those settings before treating a development estimate as a delivery commitment.
Widgets are source-based metadata. Salesforce documents an SFDX project, an authorized target org, and widget bundles stored in the project’s uiWidgets folder. Use the Salesforce CLI’s project commands to deploy and retrieve them. Put the source under the same review process as the action it calls.
The guide also points to the HXL Playground for composing declarative JSON widgets and previewing them across interfaces. Prototype there, then copy the definitions into your project. A preview helps you understand presentation; it doesn’t replace a test against your org’s records and permissions.
Keep your first widget smaller than the demo you want to show. Display a case’s status, owner, and last update, with a link back to its record. That exercises the data contract and the rendering path while leaving the existing case process responsible for changes.
Once the read path works, introduce one interaction. Fetch a fresh result when the user requests it, or open a detail view. You’ll learn where the client keeps state before an accidental repeated click can change a record twice.
Build the widget around a narrow action contract
A widget should display a result your org has already computed. For a quote, that means prices from the pricing engine. For a commission statement, it means the payout from the compensation system. The useful design in our sales commissions guide applies here: generated language explains an authoritative number.
Define the payload before arranging the interface. A quote-review view might need a quote ID, a version indicator, product labels, quantities, approved totals, and allowed next steps. It probably doesn’t need every field from the Account, Opportunity, and Quote objects.
That smaller contract gives your developer something testable. Each displayed value has a named source. Each interaction maps to a specific action. The assistant can explain the result without inventing a field name or interpreting an arbitrary blob of JSON as an instruction.
If you expose the action through Salesforce Hosted MCP Servers, review the tool and the widget together. A friendly confirmation button is useless if the underlying tool accepts any record ID and any update. The action must reject requests that fall outside its intended task.
Use custom Apex actions or another appropriate implementation to enforce the rule. Presentation can help a user understand a restriction, but the restriction has to survive a caller that bypasses the presentation entirely.
Permission inheritance still needs an acceptance test
Salesforce says HXL experiences inherit its native permissions and sharing models. Build on that documented model, then test the complete path you intend to release. An org’s permission model can work as configured while still granting more access than the task requires.
Use identities with visibly different access. A seller should see their permitted quotes. Another seller should fail to retrieve a private quote. A manager may see a broader set. A user without access to a sensitive field should not receive that field in the widget’s payload.
Inspect the returned data as well as the visible widget. Hiding a column doesn’t remove a value from an API response. If the user’s client receives a confidential value, a display rule has already arrived too late to protect it.
Also test expiry and identity changes. Open the widget, let the session expire, and try an interaction. Sign in with another permitted user and check that the previous result isn’t reused. Share a link with a colleague and verify what they can retrieve under their own identity.
These are recommended acceptance tests, not claims about a documented HXL defect. They answer whether your authentication, action, and client configuration jointly satisfy the access model your security reviewer expects. The same questions belong in any governed Agentforce implementation.
Confirmation must survive stale data and repeated clicks
An interactive view can remain open while the underlying record changes. Suppose a seller reviews a quote and a pricing administrator updates its terms before the seller clicks confirm. The action should detect the stale version and ask for another review rather than applying approval to a different quote.
Define that behavior in the action contract. Include the relevant version or freshness information in the read result, and verify it on the write. The exact implementation depends on your data model. The requirement is that a confirmation refers to the values the person inspected.
Repeated submission is another ordinary failure to plan for. A slow client encourages a second click. A network retry can repeat a request after the first request already succeeded. Your action needs the idempotency controls appropriate to its operation so repetition cannot create duplicate business effects.
Make the pending state visible, and return a clear final result. If the operation fails, say whether anything changed and how the person can recover. A generic error leaves the user guessing whether to retry, which is particularly dangerous for payments, approvals, and external system updates.
Keep the first pilot’s write reversible. Updating a draft note is easier to assess than committing a quote or issuing a refund. Increase the consequence only after your tests show that identity, freshness, and repeated submission behave as intended.
Understanding the basics
What is Salesforce’s Headless Experience Layer?
HXL is a Salesforce platform for building reusable interactive widgets across Agentforce and external assistant interfaces. It separates the widget’s definition from the interface that renders it. Salesforce’s current developer documentation describes it as beta.
Is Headless Experience Layer the same as AIforce?
AIforce is the broader framing for using Salesforce through interfaces such as Claude, Slack, and Salesforce itself. HXL handles interactive presentation within that architecture. An HXL widget still needs an appropriate data and action path underneath it.
What do I need to start building HXL widgets?
Salesforce documents API version 67.0 or later, the HXL beta setting, and an SFDX project connected to your org. Widget bundles live in the project’s uiWidgets folder. The HXL Playground lets you prototype definitions before deploying them.
Do HXL widgets enforce Salesforce permissions?
Salesforce documents inheritance of native permissions and sharing. Test the running identity, returned fields, shared access, and write actions in your actual client configuration. A hidden field in the interface is not a substitute for restricting the returned data.
Start with the record your seller already checks
Pick the record someone opens immediately after an assistant gives an answer. That extra tab usually tells you what the conversation failed to show: the quote lines, the case history, or the source of a total.
Build a widget for that one inspection step, keep its data contract small, and test it with users who have different access. A successful pilot should make the source and the permitted next action easier to understand. Add more interaction only when it serves that purpose.
Planning an AIforce interface over your Salesforce records? Talk to us, or use the Agentforce readiness assessment to identify the data and access work your first widget depends on.
