Runtime behavior follows one of two routes:

• Route 1 runs inside Agentforce. 
• Route 2 runs through the Model Context Protocol (MCP), the open standard that MCP clients such as Claude and ChatGPT use to call external tools. 

Knowing which component does what in each route helps you design better actions, and tells you where to look when a card doesn’t show up. In this blog post, you’ll:

• Walk through Route 1, from the user’s question to the card in Agentforce.
• Walk through Route 2, first in a simplified view and then in full.
• Learn how to troubleshoot each route when a card doesn’t show up.
• Compare both routes side by side.

Note: An earlier blog post, Building Interactive UI with Headless Experience Layer, introduces the topic and shows the code and metadata you need to create widgets. Make sure to read that post first.

Example widget: Get customer reviews in Pronto

Both routes use the same example from Pronto, a sample app for a fictional food delivery platform. A Pronto employee asks, “Show me the reviews for The Green Fork.” The agent calls the getCustomerReviews action, which runs the GetCustomerReviewsAction Apex class and returns a customerReviews widget: a card with the average rating and the list of reviews. Pronto wires that same widget into both routes, so you can deploy the app and test it yourself.

Route 1: Render HXL widgets as Agentforce action output

In Route 1, the large language model (LLM) points at a stored action result, and the Agentforce Client builds the widget in the browser from JSON. Route 1 is described in the Agentforce action output guide.

Here is the full sequence for it (HXL-specific messages are in orange):

In the diagram, there are four actors: 

• The User that sends the prompt.
• The Agentforce Conversation Client, which is the chat panel that runs in Lightning Experience, within the browser.
• The Agentforce Runtime, which is the entity that runs the reasoning loop on Salesforce.
• The LLM that the runtime calls at each step.

Steps 1 to 4: The agent calls the action

1. The user message travels from the client (browser) to the Agentforce runtime.
2. The runtime starts the reasoning loop.
3. The runtime sends the LLM the prompt plus the list of available actions.
4. The LLM decides the next step and calls getCustomerReviews with the storefront ID. In Pronto, the agent first turns the storefront name into a record ID with the standard Identify Record By Name action. The diagram skips that call to keep the flow short.

So far, this is a regular Agentforce action call. Nothing HXL-specific has happened yet.

Steps 5 and 6: The LLM asks to show the result

This is where HXL comes in.

5.  The runtime runs the action and stores its output under a short ID. When it returns the result to the LLM, it adds two extra fields:

{
  "reviews": { "reviewCount": 8, "averageRating": 4.125, "items": ["..."] },
  "__tool_idx__": "4bd08ecf",
  "__supports_result_display__": true
}

• __supports_result_display__ tells the LLM that this result can be shown as a card. The runtime only sets it when the surface can render widgets and the action has an output marked is_displayable: True in your Agent Script.
• __tool_idx__ is the ID of the stored result.

6.  If the LLM wants the card, it calls a built-in action named __show_tool_results__, passing in the __tool_idx__ value:

{
  "caption": "Here are the reviews for The Green Fork. You can view individual ratings, comments, and customer names. Let me know if you'd like to reply to any review or need more details.",
  "tool_ids": ["4bd08ecf"]
}

Rendering depends on the model choosing to call __show_tool_results__. The model can skip it, for example when a short text answer seems enough. To make the card more likely, ask for it in the agent’s instructions. Note that this call carries no data and no widget, only a caption and an ID. The LLM points at a result and the runtime does the rest.

Steps 7 and 8: The runtime resolves the results and the client renders the widget

7.  The runtime looks up the result by its ID and crafts a response. That response holds three things: the LLM response text (caption), the data returned by the Apex class, and the configured Custom Lightning Type (CLT) with its widget. In Pronto, that CLT is customerReviewsOutput, the type of the reviews output in the agent’s Agent Script.

8.  The Agentforce Conversation Client then does the HXL work in the browser. It reads the It reads the CLT’s widget mapping to find the widget. Then it hydrates each {!$attrs...} placeholder with the matching value from the data. Finally, it draws the widget’s component tree as Lightning web components. No HTML travels over the wire in this route, only JSON.

Troubleshooting Route 1 in Agentforce

If you get a wall of text instead of a card, check these steps in order. You can see the action calls in the trace in Agentforce Builder or Agentforce DX while you test, and in production through Agentforce Session Tracing:

1. Is the output marked is_displayable: True? Without that, the runtime doesn’t add __supports_result_display__ (step 5).
2. Does the output use the CLT as its complex_data_type_name? Without it, the response has no widget (step 7).
3. Did the LLM call __show_tool_results__ at all? Look for it in the trace (step 6). If it’s missing, ask for the card in the agent’s instructions.

Route 2: Expose HXL widgets to MCP clients with a custom MCP server

In Route 2, the MCP server sends a widget already filled with data, and the MCP host draws it in a sandboxed iframe. Route 2 is described in the HXL MCP channels guide. This route follows the standard MCP Apps protocol. The protocol defines how an MCP tool points to a UI resource, how the MCP host loads it, and how the host passes tool results to it.

Let’s start with a simplified view. In this diagram, everything that happens inside the MCP client is folded into one lifeline, labeled “MCP Client”:

In the diagram, there are three actors: 

• The User that sends the prompt.
• The MCP Client, such as ChatGPT, Claude, or Slackbot. The next diagram expands the client into its iframe, host, and the LLM.
• The MCP Server in Salesforce.

On connect: The client discovers the renderer

1.  When Claude or ChatGPT connects to your MCP server, it calls tools/list.

2.  Each tool that has a widget comes back with a renderer address, a ui:// Uniform Resource Identifier (URI) that MCP Apps defines in _meta.ui.resourceUri:

{
  "name": "getCustomerReviews",
  "_meta": {
    "ui": { "resourceUri": "ui://widget/lightningType/c__customerReviews" }
  }
}

In Pronto, that address comes from the Pronto Employee Server MCP server definition. There, the getCustomerReviews tool points to the customerReviews UI resource (the CLT that maps to the widget).

3.  The client then calls resources/read on that address.

4.  It gets back the HXL renderer, an HTML page that reads an HXL widget and draws it on screen. The MCP client loads that page in a sandboxed iframe, isolated from the rest of the app. The client can fetch the renderer when it connects or the first time it needs it. Each host decides, and it can cache the renderer for later calls. In Route 1, the renderer is already part of the Agentforce Client. The actual widget, already filled with data, arrives later with each tool result.

Request: The server returns data and a hydrated widget

5.  The user asks for the reviews.

6.  The LLM picks getCustomerReviews and the client sends tools/call. As in Route 1, the LLM first needs the storefront ID, which it can get from another Pronto tool such as searchStorefronts.

7.  The server runs the action. Then HXL resolves the CLT to its widget and hydrates the widget with the data. The tools/call result carries three parts:

{
  "content": [{ "type": "text", "text": "the same JSON, as a string" }],
  "structuredContent": { "...": "the raw action output, serialized as JSON" },
  "_meta": {
    "salesforce/uiMetadata": { "...": "the hydrated widget" }
  }
}

• structuredContent is the raw tool response, wrapped in an envelope with actionName, isSuccess, and outputValues, which holds the action’s output. Because the action returns a list, the envelope sits inside an array.
• content carries the same JSON as text. That’s the part the LLM reads.
• _meta holds the widget, and it’s only for rendering.

8.  The client hands the result to the renderer, which draws the card, and the agent summarizes the result in its answer to the user. Per the protocol, the agent doesn’t read _meta. It reads content, which carries the same JSON as structuredContent. Note: Slackbot shows HXL widgets as HTML styled to look like Block Kit.

The full picture: Host, LLM, and iframe

The simplified view hides who does what inside the client. This one splits the MCP Client into its three parts:

• The Widget Iframe is the sandboxed frame where the renderer runs.
• The MCP Host is the app (for example, Claude or ChatGPT) that talks to the server.
• The LLM is the model.

Four steps are worth a closer look (9 to 12 in the diagram):

9.  The tools/call result reaches the host.

10. The host pushes the tool result into the iframe. The renderer reads the widget from it and draws the card.

11. The host sends the tool result to the LLM, without the widget.

12. The LLM writes the final answer from the data, and the host shows the answer next to the card.

Troubleshooting Route 2 in MCP clients

If you get text instead of a card, check each step of the sequence in order. You can use the MCP Inspector to see the raw responses the server returns:

1. Does the client support MCP Apps? Claude, ChatGPT, and Slackbot do. Claude Code in the terminal doesn’t render widgets, so you’ll see text only.
2. Does the tools/list result include _meta.ui.resourceUri for your tool (step 2)? If not, check that the tool points to the UI resource in your MCP server definition.
3. Does the UI resource load? Call resources/read on that URI in the MCP Inspector, and make sure it returns the HXL renderer (step 4).
4. Does the tools/call result include salesforce/uiMetadata (step 7 in the simplified diagram)? If not, check isError first. When the action fails, the server returns only an error message, with no data and no widget.

Route 1 vs. Route 2: What’s different

Both routes start from the same Apex action and the same widget. They differ in who decides to show the card, where the widget gets filled with data, and who draws it.

Conclusion

You now know what happens between a user’s question and the card on the screen in both routes. In Agentforce, the LLM points at a stored result and the client builds the card in the browser. In MCP clients, the Salesforce MCP server sends a hydrated widget and the host draws it in an iframe. 

To see it in action, deploy Pronto to an org and try both routes. To go deeper, watch the recorded codeLive, Build Rich Agentic UI with Headless Experience Layer, and Ask Me Anything (AMA) sessions.

Resources

• Building Interactive UI with Headless Experience Layer
• Pronto sample app
• HXL Get Started
• Render HXL Widgets as Agentforce Action Output
• Expose HXL Widgets through MCP
• HXL Playground
• MCP Apps overview and MCP Apps specification

About the author

Alba Rivas works as a Principal Developer Advocate at Salesforce. You can follow her on GitHub or LinkedIn.

The post How HXL Widgets Render in Agentforce and MCP Clients appeared first on Salesforce Developers Blog.

An earlier post, The New Agentforce Metadata and Development Lifecycle, showed how Agent Script agents map to the Bot, GenAiPlannerBundle, and AiAuthoringBundle metadata types. This post picks up from there. It covers why we simplified agent metadata and compares the old and new structures side by side, using a real agent. It also covers what to know before you retrieve and deploy with the new types.

Agent metadata before API version 68.0 (Winter ’27)

To see what changed, let’s start with a real agent. TestAgent is an Agentforce Service Agent built with Agent Script. It has one version, 10 subagents, and 26 actions. Here’s what you get when you retrieve it into a Salesforce DX project at API version 67.0.

├── aiAuthoringBundles
│   └── TestAgent
│       ├── TestAgent.agent
│       └── TestAgent.bundle-meta.xml
├── bots
│   └── TestAgent
│       ├── TestAgent.bot-meta.xml
│       └── v1.botVersion-meta.xml
└── genAiPlannerBundles
    └── TestAgent_v1
        ├── TestAgent_v1.genAiPlannerBundle
        ├── agentGraph
        │   └── TestAgent_v1_graph.json
        ├── agentScript
        │   └── TestAgent_v1_definition.agent
        └── localActions
            ├── AccountManagement_1793afaabbea5e6
            ├── CaseManagement_1797b79603146ff
            ├── DeliveryIssues_1799f005010de87
            │   ├── AnswerQuestionsWithKnowledge_17288a938fc0c53
            │   │   ├── input
            │   │   │   └── schema.json
            │   │   └── output
            │   │       └── schema.json
            │   └── ... 5 more actions
            ├── GeneralFAQ_17958732d5d84f7
            ├── OrderInquiries_179524d7fde40be
            ├── ReservationManagement_17932b500c2b88d
            └── ServiceCustomerVerification_1796152b9540575
                ├── SendEmailVerificationCode_1724f12735f68c6
                └── VerifyCustomer_1726b9bee0044be

One agent with one version is spread across three metadata types (Bot, GenAiPlannerBundle, and AiAuthoringBundle). The agent’s settings live in TestAgent.bot-meta.xml (the bot), and the version’s settings and welcome message live in v1.botVersion-meta.xml (the version). The subagents and actions live in TestAgent_v1 (the planner bundle), and the Agent Script source sits in TestAgent.agent (the authoring bundle).

Here are the four biggest pain points we heard about from you regarding this structure:

One agent, many names. The same agent shows up as TestAgent.bot-meta.xml, v1.botVersion-meta.xml, TestAgent_v1, and TestAgent.agent. Deployment and retrieval operations can fail unless your tooling understands how these names correspond and strictly adheres to a complex naming structure. If you write your manifest by hand, every new version also adds a GenAiPlannerBundle member and an AiAuthoringBundle member to it.

Generated suffixes everywhere. Every subagent and action in a version gets a unique name with a generated suffix, such as ServiceCustomerVerification_1796152b9540575. In our one-version sample, the planner bundle contains 37 suffixed names, used 111 times, plus 33 suffixed folders. The suffixes mean nothing to you. Each version also gets its own suffixes, so comparing two versions shows changes that you never made.

Messages hidden in dialogs. To find your agent’s welcome message, you have to dig through a dialog, its steps, and its messages. Each one has its own generated identifier.

Folder names that move. At API version 67.0 and earlier, the newest authoring bundle has no version number, while older ones do. For example, once TestAgent has four versions, its newest bundle is TestAgent, and the older ones are TestAgent_1, _2, and _3. When you create a version, a different folder becomes the unnumbered one. So the same bundle can have a different name from one retrieve to the next.

What’s new in API version 68.0

API version 68.0 gives each agent a simpler shape. One metadata type holds the agent, and one metadata type holds everything that belongs to a version.

In a Salesforce DX project, the files for these types live in the aiAgents, aiAgentDefinitionVersions, and aiAuthoringBundles folders.

At API version 68.0, Agentforce agents use the new types, and the Bot and BotVersion types are for classic Einstein Bots. If you retrieve or deploy an Agentforce agent as Bot or BotVersion at this API version, you get an error that tells you to use AiAgentDefinition and AiAgentDefinitionVersion instead. To keep using the old types, stay on API version 67.0.

Before and after: the folder structure

Here’s the same agent retrieved at API version 68.0.

├── aiAgents
│   └── TestAgent.aiAgentDefinition-meta.xml
├── aiAgentDefinitionVersions
│   └── TestAgent#1
│       ├── TestAgent#1.aiAgentDefinitionVersion-meta.xml
│       ├── agentGraph
│       │   └── TestAgent_v1_graph.json
│       ├── agentScript
│       │   └── TestAgent_v1_definition.agent
│       └── localActions
│           ├── AccountManagement
│           ├── CaseManagement
│           ├── DeliveryIssues
│           │   ├── AnswerQuestionsWithKnowledge
│           │   │   ├── input
│           │   │   │   └── schema.json
│           │   │   └── output
│           │   │       └── schema.json
│           │   └── ... 5 more actions
│           ├── GeneralFAQ
│           ├── OrderInquiries
│           ├── ReservationManagement
│           └── ServiceCustomerVerification
│               ├── SendEmailVerificationCode
│               └── VerifyCustomer
└── aiAuthoringBundles
    └── TestAgent_1
        ├── TestAgent_1.agent
        └── TestAgent_1.bundle-meta.xml

If you know the old types, here’s how they map:

• The agent-level part of Bot becomes AiAgentDefinition.
• Each bot version and its GenAiPlannerBundle merge into one AiAgentDefinitionVersion.
• The planner is no longer a separate component. Instead, it’s a <planner> element inside the version file.
• AiAuthoringBundle remains largely unchanged, except that every AiAuthoringBundle file name also explicitly names its version as a suffix.

A key enhancement in API version 68.0 is support for selecting specific version members using the # delimiter. In your package.xml manifest or with the --metadata flag in Salesforce CLI, you can target an individual agent version, retrieve every version of a specific agent, or query across all versions for all agents, as shown in the table below.

A few things stand out.

• Everything that belongs to version 1, except its Agent Script source, lives in one folder, TestAgent#1.
• Subagent and action folders use the names that you gave them, like DeliveryIssues/AnswerQuestionsWithKnowledge.
• The authoring bundle folder always carries its version number. TestAgent_1 keeps its name when you add version 2.

The content itself didn’t change. When the two retrieves were compared, all 52 input and output schemas, the agent graph, and the .agent source file were identical. Only the names and the packaging changed.

Before and after: subagents and actions

The biggest difference is inside the files. Here’s the Service Customer Verification subagent and one of its actions in the API version 67.0 planner bundle. Some elements have been trimmed to save space.

<localTopics>
    <fullName>ServiceCustomerVerification_1796152b9540575</fullName>
    <canEscalate>false</canEscalate>
    <description>Verifies the customer's identity before granting access to sensitive data. ...</description>
    <developerName>ServiceCustomerVerification_1796152b9540575</developerName>
    <!-- instructions omitted -->
    <language>en_US</language>
    <localActionLinks>
        <functionName>SendEmailVerificationCode_1724f12735f68c6</functionName>
    </localActionLinks>
    <localActionLinks>
        <functionName>VerifyCustomer_1726b9bee0044be</functionName>
    </localActionLinks>
    <localActions>
        <fullName>VerifyCustomer_1726b9bee0044be</fullName>
        <description>Verifies whether the verification code entered by the user matches the code sent to the user's email address.</description>
        <developerName>VerifyCustomer_1726b9bee0044be</developerName>
        <invocationTarget>SvcCopilotTmpl__VerifyCode</invocationTarget>
        <invocationTargetType>flow</invocationTargetType>
        <isConfirmationRequired>false</isConfirmationRequired>
        <isIncludeInProgressIndicator>true</isIncludeInProgressIndicator>
        <localDeveloperName>VerifyCustomer</localDeveloperName>
        <masterLabel>Verify Customer</masterLabel>
        <source>SvcCopilotTmpl__VerifyCustomer</source>
    </localActions>
    <!-- SendEmailVerificationCode action omitted -->
    <localDeveloperName>ServiceCustomerVerification</localDeveloperName>
    <masterLabel>Service Customer Verification</masterLabel>
    <pluginType>Topic</pluginType>
</localTopics>

And here’s the same subagent in the API version 68.0 version file, inside the <planner> element.

<localTopics>
    <canEscalate>false</canEscalate>
    <description>Verifies the customer's identity before granting access to sensitive data. ...</description>
    <!-- instructions omitted -->
    <language>en_US</language>
    <localActionLinks>
        <functionName>SendEmailVerificationCode</functionName>
    </localActionLinks>
    <localActionLinks>
        <functionName>VerifyCustomer</functionName>
    </localActionLinks>
    <!-- SendEmailVerificationCode action omitted -->
    <localActions>
        <description>Verifies whether the verification code entered by the user matches the code sent to the user's email address.</description>
        <invocationTarget>SvcCopilotTmpl__VerifyCode</invocationTarget>
        <invocationTargetType>flow</invocationTargetType>
        <isConfirmationRequired>false</isConfirmationRequired>
        <isIncludeInProgressIndicator>true</isIncludeInProgressIndicator>
        <localDeveloperName>VerifyCustomer</localDeveloperName>
        <masterLabel>Verify Customer</masterLabel>
        <source>SvcCopilotTmpl__VerifyCustomer</source>
    </localActions>
    <localDeveloperName>ServiceCustomerVerification</localDeveloperName>
    <masterLabel>Service Customer Verification</masterLabel>
    <pluginType>Topic</pluginType>
</localTopics>

The suffixed fullName and developerName elements are gone. Now localDeveloperName is the name, and links between subagents and actions use it too. In this sample, all 37 suffixed subagent and action names disappeared. Because subagent and action names stay the same from one version to the next, diffs between versions get much smaller and easier to review.

Before and after: welcome and error messages

In API version 67.0, your welcome message sits inside a Welcome dialog in the bot version file.

<botDialogs>
    <botSteps>
        <botMessages>
            <message>Hi, I'm an AI service assistant. How can I help you?</message>
            <messageIdentifier>7c57d39d-5d76-40d9-a8e8-181b1a20b657</messageIdentifier>
        </botMessages>
        <stepIdentifier>42386b78-770c-4911-8ad9-60f664fdeab0</stepIdentifier>
        <type>Message</type>
    </botSteps>
    <botSteps>
        <stepIdentifier>fdf3a8b3-f4b0-4329-a7f5-349f387b84db</stepIdentifier>
        <type>Wait</type>
    </botSteps>
    <developerName>Welcome</developerName>
    <isPlaceholderDialog>false</isPlaceholderDialog>
    <label>Welcome</label>
    <showInFooterMenu>false</showInFooterMenu>
</botDialogs>
<!-- ... -->
<entryDialog>Welcome</entryDialog>

In API version 68.0, it’s one line.

<welcomeMessage>Hi, I'm an AI service assistant. How can I help you?</welcomeMessage>

The version file has three simple message elements: welcomeMessage, errorMessage, and escalationMessage. They hold the first message of the Welcome, Error_Handling, and Transfer_To_Agent dialogs. When you deploy, Salesforce builds the dialogs from these messages for you.

Before and after: package.xml

Now suppose that TestAgent has four versions. It also uses a global subagent and two global actions, which call an Apex class and a prompt template. Here’s a hand-written API version 67.0 manifest for it.

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>TestAgent</members>
        <name>Bot</name>
    </types>
    <types>
        <members>TestAgent_v1</members>
        <members>TestAgent_v2</members>
        <members>TestAgent_v3</members>
        <members>TestAgent_v4</members>
        <name>GenAiPlannerBundle</name>
    </types>
    <types>
        <members>TestAgent_1</members>
        <members>TestAgent_2</members>
        <members>TestAgent_3</members>
        <members>TestAgent</members>
        <name>AiAuthoringBundle</name>
    </types>
    <types>
        <members>Custom_Subagent</members>
        <name>GenAiPlugin</name>
    </types>
    <types>
        <members>SayHello</members>
        <name>ApexClass</name>
    </types>
    <types>
        <members>Custom_PromptTemplate</members>
        <name>GenAiPromptTemplate</name>
    </types>
    <types>
        <members>Say_Hello</members>
        <members>Custom_PromptTemplate</members>
        <name>GenAiFunction</name>
    </types>
    <version>67.0</version>
</Package>

That’s 7 types and 14 members. At API version 68.0, you name the agent and its versions.

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>TestAgent</members>
        <name>AiAgentDefinition</name>
    </types>
    <types>
        <members>TestAgent#*</members>
        <name>AiAgentDefinitionVersion</name>
    </types>
    <version>68.0</version>
</Package>

The #* wildcard picks up every version, so you don’t need to edit the manifest when you add one.

How to retrieve Agentforce metadata dependencies with the Salesforce CLI

What about the Apex class, the prompt template, and the global subagent and actions? Each agent version knows what it uses, so you can ask the Metadata API to bring those along. With Salesforce CLI, add the --root-type-with-dependencies flag and set it to AiAgentDefinitionVersion. You can use it with a manifest or with the --metadata flag. Using the # delimiter syntax and the new flag requires Salesforce CLI version 2.149.9 or later, so be sure to execute sf update prior to running these commands.

# With the manifest above
sf project retrieve start --manifest manifest/package.xml --root-type-with-dependencies AiAgentDefinitionVersion --target-org my-sandbox

# Without a manifest, for version 1 of TestAgent
sf project retrieve start --metadata "AiAgentDefinitionVersion:TestAgent#1" --root-type-with-dependencies AiAgentDefinitionVersion --target-org my-sandbox

In both cases, the retrieve then adds what each version depends on. That includes its parent AiAgentDefinition and its AiAuthoringBundle, which holds the Agent Script source that you edit. It also includes the flows, Apex classes, and prompt templates that its actions call, and any global subagents and actions that it uses. The compiled Agent Script file in the version’s agentScript folder isn’t a dependency. It’s part of the version, so you get it with or without the flag.

Without the flag, you get only what you name. For example, --metadata AiAgentDefinitionVersion on its own retrieves every version of every agent. It doesn’t bring each version’s parent AiAgentDefinition, its AiAuthoringBundle, or anything else that it uses, so name the ones that you need too. If you name versions with --metadata, put the value in double quotes so that your shell doesn’t treat # or * as special characters. Without a manifest, Salesforce CLI uses the sourceApiVersion in your sfdx-project.json file, so set it to 68.0.

Retrieving with dependencies isn’t new. From API version 64.0 (Summer ’25) through 67.0, you could do it only for a whole Bot, so you always got every version of the agent. Now you can do it for a single version, so you can move exactly the version that you want, plus what it needs.

A few limits apply. You can make up to 25 retrieve requests with dependencies per day, and each request can cover up to 100 components. The retrieve also goes only one level deep. It adds what each version uses directly, but not what those dependencies use in turn. For example, if an action calls an Apex class that uses another Apex class, you get only the first class. Add other metadata that your agent needs, such as custom objects or Data 360 dependencies, to your manifest or --metadata list.

Deployment validations in API version 68.0

The new types come with a few deployment validation rules. Most of them protect you from half-deployed agents. Deployment of agents on API 68.0 will fail if:

You mix the old and new formats. Pick either API 67.0 or API 68.0 format. Don’t try to deploy Bot or BotVersion and the new types for the same agent in the same deployment.

You deploy the definition without at least one version. A version can’t deploy unless its AiAgentDefinition already exists in the target org or is in the same deployment. A new definition also needs at least one version. The first time you deploy an agent to an org, include the definition, not just a version.

Your Agent Script source is not included. For agents built with Agent Script, you must deploy the version’s AiAuthoringBundle along with the AiAgentDefinitionVersion. Note the agentScript folder inside the version is a compiled copy, not the source that you edit. Storing the compiled copy in your source control is not recommended.

You don’t set the agent user correctly. Your retrieved metadata includes the agent username from the source org. For a draft agent, use string replacement to swap in a username from the target org. Committed agents can’t be edited, so to give one a new user, create a new version and add the user there. Either way, the agent needs a user before it can run in the new org.

Migration tips for switching to API 68.0

• Retrieve instead of converting by hand. Run sf update to get the latest Salesforce CLI, set your manifest version and the sourceApiVersion in your sfdx-project.json file to 68.0, and retrieve. Salesforce writes the new structure for you.
• Make the switch in its own commit. Every agent folder and file name changes, so keep the switch separate from other work. Real changes won’t get lost in the rename during code review.
• Update scripts that read agent XML. If your pipeline parses GenAiPlannerBundle files or relies on suffixed names, point it at the <planner> element in the version file and use localDeveloperName.

Conclusion

API version 68.0 gives every Agentforce agent a simpler, more predictable metadata shape. You get one definition per agent, one folder per version, names without generated suffixes, and messages that you can read at a glance. Your manifests get shorter, your diffs get smaller, and you can retrieve a single version with everything it depends on. Try it in a Winter ’27 org: retrieve one of your agents at API version 68.0 and compare it with what’s in your source control today.

Resources

• Release notes: Move Agents Between Orgs More Easily with Simplified Agent Metadata Types
• Agentforce Developer Guide: Use Metadata to Move an Agent to a New Org
• Agentforce Developer Guide: Define Agent Metadata (v67 and Earlier)
• Agentforce Developer Guide: Example – Configure String Replacement for Agent Username
• Salesforce CLI Command Reference: project retrieve start
• Metadata Coverage Report
• Blog: The New Agentforce Metadata and Development Lifecycle
• Blog: Intro to Agent Script Language Fundamentals
• Trailhead: Create and Activate Your Agent with Agent Script Techniques

About the author

Shreyas Ramesh serves as a Lead Software Engineer with Salesforce AI in San Francisco. He is also a Fellow of the Institute of Analytics (FIoA) alongside BCS, The Chartered Institute for IT. Within the Agentforce Core Platform group, Shreyas directs the architecture for Agentforce Metadata, Agentforce Versioning, and additional design-time functionality aimed at providing enterprise-grade application lifecycle management (ALM) for Agentforce. Connect with Shreyas via LinkedIn.

The post Agentforce Metadata Types in Winter ’27: Dive into AiAgentDefinition appeared first on Salesforce Developers Blog.

The Headless Toolkit closes those gaps for building Salesforce apps and agents. The Salesforce Skills Library (sf-skills) gives coding agents Salesforce expertise on demand. Hosted Model Context Protocol (MCP) Servers give them just the org context they need. The Salesforce CLI lets them test, validate, and deploy their changes.

This post offers one way to put the Headless Toolkit to work: an agent-driven development lifecycle with seven stages. For each stage, you’ll see what changes and which skills and tools to use. You’ll also see what to add each time the agent gets something wrong. This approach isn’t the only way, so experiment with the skills and tools covered in this post and adapt the parts that work for your team.

The post starts with how the lifecycle works, defining what a harness is and how it fits into the workflow. It then explains how to set up the skills and walks through each stage: ground, specify, build, verify, review, release, and observe.

From a linear process to an agent-driven loop

On a traditional Salesforce project, work moves in a line. A requirement becomes a user story in Jira or another tracker, a developer builds it, QA tests it, and someone deploys it. The context for each change is spread across the story, Slack threads, design docs, the org itself, and the memory of people who’ve worked on it. A developer knows where to look. An agent can use only what it can reach.

With coding agents, the line becomes a loop. The agent does more of the building, testing, and deploying, and your role shifts toward directing it and judging what it produces. Directing can be as simple as one prompt that states the goal and how the agent should check its own result. Your attention moves to a few decision points: approving the spec, reviewing the proposed design and architecture, judging review findings, and approving production releases.

Two ideas make the loop work. First, each stage leaves an artifact the next stage can read, such as a spec, a test, or a review report, so a new session doesn’t start from zero. Second, every mistake the agent makes leaves something behind, whether the mistake is caught in verification, review, or production. That might be a new test, a new rule, or a new spec for the next change.

Use this table as your map of the lifecycle. Each section below covers its row in more detail.

Two harnesses: the agent’s and yours

A harness is the layer around a model that gives it tools and manages the context it sees. Every coding agent ships with one. Claude Code, for example, gives the model built-in tools to read and edit files, search code, run commands, and orchestrate multiple agents. It also compacts long conversations and asks permission before actions you haven’t allowed. You don’t build this layer, but you can configure it, for example with permission modes and settings.

Your project adds a second layer on top, and that’s the layer this post is about:

Your project adds a second layer on top, and that’s the layer this post is about:

• Skills that teach the agent Salesforce tasks, such as the ones in sf-skills.
• Instructions in AGENTS.md or CLAUDE.md, plus your ontology (business-specific vocabulary) and feature map.
• Tools such as the Salesforce CLI, Salesforce Hosted MCP Servers, and the Apex language server.
• Checks such as tests, Code Analyzer rules, hooks, and quality gates.

The Headless Toolkit supplies most of these pieces. You add the instructions and checks that are specific to your org.

The agent’s built-in harness is the same for everyone who uses that agent. Your project harness is what makes it effective on your org, and it’s never finished. Here’s a small example instructions file, AGENTS.md, to start from.

# Agent instructions
- Check ontology.yaml before mapping a business term to a Salesforce object.
- Features live in force-app/<feature>/. Update docs/feature-map.md in the same change.

## Hard rules
- All SOQL in Apex runs WITH USER_MODE.
- Never hardcode record IDs. Use Custom Metadata, Custom Labels, or Custom Settings.

Keep both layers lean. Models get less accurate as the context window fills, an effect researchers call context rot. In my experience, deep technical work goes best under roughly 300K tokens for most models. Skills help because the agent loads a skill’s full instructions only when it uses that skill. In Claude Code, set disable-model-invocation: true on skills you only run by hand, and run /context to check usage.

Newer models also now need less prompting than most of us still give them. For Claude Opus 5 and Fable 5, over 80% of the Claude Code system prompt was removed with no measurable drop in its coding evals.

Set up the Salesforce Skills Library

A skill is a folder of instructions, scripts, and reference files that teaches an agent a specific task. The Salesforce Skills Library holds more than 250 skills and follows the open Agent Skills specification, so it works with any agent that supports skills. If you use Agentforce Vibes, the skills come pre-installed with automatic updates. In Claude Code, install the plugins for the stages you use, and add standalone skills with npx, which also works for Codex, Cursor, and OpenCode.

/plugin install salesforce-development@claude-plugins-official

/plugin marketplace add forcedotcom/sf-skills
/plugin install salesforce-code-quality@salesforce
/plugin install experience-lwc@salesforce
/plugin install dx-devops@salesforce
/plugin install agentforce-adlc@salesforce
/plugin install platform-observability@salesforce

npx skills add forcedotcom/sf-skills --skill dx-org-analyze external-diagram-mermaid-generate platform-docs-get dx-apexguru-scan

Here’s what each plugin covers:

• salesforce-development: metadata, Apex, Flow, permissions, tests, and deploys.
• salesforce-code-quality: Code Analyzer. (You can also include the architecture-review subagent to review architecture.)
• experience-lwc: LWC generation, React or Angular apps, accessibility tests, and security validation.
• dx-devops: DevOps Center work items, pipelines, test suites, and quality gates.
• agentforce-adlc and platform-observability: Agentforce testing and tracing.

Some skills call Salesforce Hosted MCP Servers in your org, and those servers are off by default. Your coding agent may not function properly without turning on the MCP servers. To do so, go to Setup, enter MCP Servers in Quick Find, open MCP Servers under API Catalog, and turn on the MCP servers your skills reference. Activation can take up to two minutes. 

Stage 1: Ground the agent in your business and org

An agent starts every session without knowing which objects matter or what your business means by a “customer.” Grounding gives it that knowledge.

Start with structure. The default Salesforce DX project groups files by type, such as all Apex in one folder. Try grouping them by business capability instead, with folders like customer_care and field_service. If you can’t restructure, add a feature map: a short file that lists the Apex, LWC, flows, permissions, and tests behind each feature.

Next, write down what the agent can’t guess. Coding agents know Salesforce, but they don’t reliably know how your business terms map to Salesforce. Is a “customer” an Account or a Contact? Keep a small ontology.yaml for those terms, and tell the agent to check it.

terms:
  customer:
    meaning: context_dependent
    resolve:
      homeowner_context: "Account is the household; Contact is the resident."
      enterprise_sales_context: "Account (RecordType=Business) is the B2B customer."
    never_assume: "Customer == Contact"
  device:
    sf: Asset
    note: "An installed unit. Its catalog definition is Product2."

Look up what already exists in your org

Objects and flows created in Setup aren’t in your repo until someone retrieves them. The Metadata Grounding MCP Server (Beta) lets the agent find them first. The agent calls describe_metadata to list types, search_metadata to search in plain language, and query_metadata to fetch full records. Use it to avoid duplicates and to draft your feature map and ontology from the real org.

The server is read-only and returns only what the signed-in user can access. Its results come from the Salesforce Catalog index, so very recent changes can lag. It isn’t available in scratch orgs or in Developer Edition orgs with namespaces, and it requires Data 360, API access, and Salesforce Catalog. Turn it on in Setup with the other MCP servers.

Skills to use: platform-metadata-grounding-get finds metadata that already exists in a Salesforce org by meaning, when you do not know its exact API name. dx-org-analyze inventories an org’s metadata, permissions, and packages. external-diagram-mermaid-generate turns your data model into a text diagram you can keep in the repo.

Improve the harness: When the agent misreads a business term, add it to the ontology.

Stage 2: Specify what to build

A plan made in an agent’s plan mode usually lives in one session. A spec is a file in the repo that humans approve and agents reread, so the decisions survive between sessions.

Specs come in three common levels. In spec-first, you write the spec, build from it, and move on. In spec-anchored, you keep the spec and update it as the feature changes. In spec-as-source, humans edit only the spec, and code is generated from it.

For Salesforce, I prefer spec-anchored. In my experience, much of the risk hides in decisions the code doesn’t show, such as sharing assumptions and which automation owns a field.

Not sure what to build yet? Ask the agent to interview you until it can resolve all the decisions required to write a spec. You can also use open-source skills like /grill-me for this. Once the spec is finalized, start a new session and build from that spec.

When a spec is worth it

Not everyone thinks specs are worth the effort, and the critiques are fair. Spec-driven workflows can be overkill for small changes, they can produce Markdown that’s tedious to review, and a spec doesn’t stop an agent from skipping instructions. Three habits address those problems:

• Right-size it. For bug fixes and one-file changes, skip the spec. One prompt that states the goal and how to verify it is usually enough. Write a spec when a feature spans several metadata types or several sessions.
• Record decisions, not a description of the code. Capture what the code can’t show, such as sharing, which automation owns a field, and data volume. Keep it to a page or less.
• Check it, don’t trust it. A spec is advice to the agent, like any instruction. Turn each requirement into a test, and have a reviewer compare the spec with the code, so that any requirement the code doesn’t implement fails a test and gets flagged in review.

Skills to use: platform-docs-get pulls official Salesforce documentation so the spec cites real platform behavior. Here is an unofficial example spec-writing skill that you can take inspiration from.

Improve the harness: When rework traces back to a decision the spec didn’t cover, add that topic to your spec template. Common additions are sharing, automation ownership, governor-limit expectations, and data volume.

Stage 3: Build step by step or in parallel

You have two ways to build with an agent, and neither is always better. Pick the one that fits the feature and the way you like to work.

• One agent, step by step. The agent builds each piece in order while you watch, steer, and review as it goes. This can be easier to follow and keeps you in flow, with no agents to coordinate. It suits bug fixes, small features, and work where each step depends on the last.
• Subagents in parallel. The agent splits the work across subagents, which are separate agents that each start with a fresh context window. Claude Code often does this on its own, so you rarely need to ask. This can finish large features with independent parts sooner. The trade-off is that you need a clear plan up front, you review more output at once, and every subagent adds cost and waiting time.

Give each subagent only the context it needs

Subagents don’t make the model smarter by default. Their value is a separate, focused context window. A subagent doesn’t carry the main session’s history, so it starts with only what you give it. An accessibility subagent needs the accessibility testing skill, not your Apex, flow, and deployment skills. Each subagent also spends tokens of its own and takes time to gather context. Save them for substantial, standalone work, such as a long audit or a migration. For a small change, one agent is usually faster and cheaper.

For example, in Claude Code, you define a subagent as a Markdown file in .claude/agents/. The skills field loads the listed skills when the subagent starts, and the tools field limits what it can do.

---
name: lwc-accessibility-tester
description: Writes and runs Jest accessibility tests for Lightning web components. Use after a component is built.
tools: Read, Write, Edit, Bash
skills:
  - experience-lwc-accessibility-jest-run
---
Test only the components named in the task. Report each failure with its file and line.

When parallel pays off

Parallel helps only when a feature has independent work, and it pays off once a single session can finish a task without you. Get one session to a passing result first. For a large feature, ask the agent to map the metadata dependency graph from the spec, and review it. Then let subagents build the independent parts at the same time.

Keep that work apart with git worktrees. Subagents that edit the same project folder can overwrite each other’s files. A worktree gives each subagent its own folder and branch in the same repository. In Claude Code, add isolation: worktree to a subagent’s definition, or start a parallel session with claude --worktree.

Skills to use: Either way, give the agent the skill for each piece, such as platform-custom-object-generate, platform-custom-field-generate, platform-apex-generate, experience-lwc-generate, or automation-flow-generate. platform-metadata-api-context-get supplies the exact schema for each metadata type, so the files deploy cleanly.

Improve the harness: Give the agent only what each piece needs: the schema it depends on, your coding standards, and your test expectations. When it breaks a standard, fix the standards file or skill, not just the code.

Stage 4: Verify with independent checks

The agent runs checks as it builds, reads the results, and fixes what’s broken. The checks must be independent tools, not the agent’s opinion of its own work. The agent can run them as skills, or hooks can run them automatically.

• platform-apex-test-generate and platform-apex-test-run write bulk-safe Apex tests, run them, and drive a test-fix loop.
• dx-code-analyzer-run runs Salesforce Code Analyzer, including PMD and ESLint, and can scan just the files in your git diff.
• dx-apexguru-scan finds performance problems, such as SOQL or DML inside loops, and reports line numbers for each.
• design-systems-slds-validate and experience-lwc-accessibility-jest-run check LWC styling and accessibility. agentforce-test runs test suites for Agentforce agents.
• For UI tests, the Salesforce UI Script Recorder turns your clicks in an org into a Playwright script.

Give the agent a check it can read. If it can run something that returns pass or fail, or a number to beat, it can keep going without you watching. One example is “all Apex tests pass and coverage stays above 90%.” For long background work, /goal sets a condition like that, and a separate model checks it after every turn, judging only what the agent has shown.

Don’t take “done” on trust. When the agent reports back, ask it to show you the command and its output, or a screenshot.

Run checks automatically with hooks

A skill runs only when the agent decides to use it, but a hook runs every time. A hook is a command your coding agent runs at a set point, such as after each file edit or before it finishes a task. Claude Code and Codex both support hooks. When a check fails, the agent sees the error and fixes it before it moves on.

The Salesforce plugins you installed earlier already include hooks. experience-lwc checks each LWC file the agent writes against Salesforce Lightning Design System (SLDS) 2 and Code Analyzer rules. agentforce-adlc checks Agent Script files after every edit. salesforce-development runs Apex language server diagnostics before each deployment.

Improve the harness: Every bug that gets past verification is a missing check. Add the test, rule, or evaluation that would have caught it. If the check should run every time, make it a hook.

Stage 5: Review with a separate agent

Agents can produce code faster than people can read it, so review can become the bottleneck. The builder shouldn’t grade its own work. A separate reviewer agent (an adversarial agent) goes first, and humans focus on its findings.

Four settings make a reviewer sharper: a fresh context without the builder’s history, read-only access, a different model when you can, and a skill to review against.

Skills to use: The read-only platform-architecture-analyze checks sharing, field-level security (FLS), bulkification, and SOQL selectivity, and it cites the file and line for every finding. It grades against the original Trusted, Easy, and Adaptable pillars of Salesforce Well-Architected, which now has five pillars, so treat its grades as a baseline. experience-lwc-security-validate checks LWC bundles for Lightning Web Security (LWS) issues.

A reviewer can catch what tests and scans miss. For example, an Apex service queries Asset fields WITH USER_MODE, but the permission set never grants access to them. The tests pass because they run as an admin, and the scan is clean. Yet a support rep with only that permission set hits an error. A reviewer catches this by comparing the permission set’s field access with the query’s fields.

Improve the harness: Turn each review finding into a check that runs on its own. For the permission gap above, add an Apex test that runs as a minimum-access user with only the permission set. It fails until the permission set is fixed.

Stage 6: Release behind deterministic gates

The agent drives the path from validation through promotion, deterministic checks guard each step, and a human owns the production gate.

In scratch orgs, sandboxes, and lower pipeline stages, the agent can validate changes and fix failures on its own. Production is different. The Salesforce Development plugin’s deploy gate checks the target org before every sf project deploy. It allows scratch, sandbox, and trial orgs. For a production org, it blocks the command and directs the agent to validate first, then quick deploy after a person approves.

Skills to use: platform-deploy-validate runs a dry run for sandboxes and a validation for production, which returns a quick-deploy job ID. platform-quick-deploy ships that job without rerunning tests.

For DevOps Center, dx-devops-promote moves work items between stages, and dx-devops-test-pipeline-configure adds quality gates, such as a coverage threshold, to a stage.

Improve the harness: When a release fails late, move the check earlier. dx-devops-test-failures-analyze explains a DevOps Center pipeline failure in plain language, so you can add a test suite or quality gate to a lower stage.

Stage 7: Observe and feed the loop

Instead of waiting for users to report problems, the agent can read debug logs, platform traces, and agent sessions to find issues and explain them.

Skills to use: platform-apex-logs-debug analyzes debug logs and governor-limit failures. platform-tracing-configure and platform-tracing-agentforce-configure turn on tracing.

Improve the harness: Ask two questions about every production finding. What should we build next? That becomes a new spec. Why did this get through? That becomes a new constraint, as the next section shows.

Make every repeated mistake a constraint

Coding agents copy patterns that already exist in your repo, including the bad ones. OpenAI saw this while building a large app with Codex, and Snyk found that AI assistants can replicate existing security vulnerabilities. So when the agent repeats a mistake, leave behind a constraint that catches it next time.

Instructions and skills are advisory: they reduce mistakes, but the agent can still ignore them. Tests, Code Analyzer rules, hooks, and quality gates are deterministic: they catch mistakes no matter which agent or human wrote the code. Pick the strongest one that fits.

For code patterns, use dx-code-analyzer-custom-rule-create. Describe the pattern in plain language, such as “ban hardcoded record IDs.” The skill picks the engine and writes the rule with a script, so the YAML is escaped correctly. Then it tests the rule on one file that should fail and one that should pass. Here’s the rule it adds to code-analyzer.yml.

engines:
  regex:
    custom_rules:
      NoHardcodedSalesforceIds:
        regex: '/[''"](?<target>(?=[a-zA-Z0-9]{0,14}\d)[a-zA-Z0-9]{15}(?:[A-Z0-5]{3})?)\\?[''"]/g'
        description: "Detects hardcoded 15 or 18 character Salesforce record IDs"
        violation_message: "Replace hardcoded ID with Custom Label, Custom Metadata, or Custom Setting"
        severity: 2
        tags:
          - "Custom"
          - "Security"
        file_extensions:
          - ".cls"
          - ".trigger"

Then use dx-code-analyzer-configure to run Code Analyzer in your CI/CD pipeline, such as GitHub Actions. Add the rule to your agent instructions, and clean up old code that breaks it, so the agent has nothing wrong to copy.

Conclusion

When agents write more of the code, your value moves to grounding them, deciding what to build, and judging the result. An agent-driven lifecycle gives that work a shape: ground, specify, build, verify, review, release, and observe. The Headless Toolkit, together with tools you already know, such as Code Analyzer, ApexGuru, and DevOps Center, covers every stage.

You don’t need to adopt it all at once. Install the skills, pick the stages that your team finds most efficient, and start there. Every time the agent gets something wrong, improve your harness.

Resources

• Salesforce Skills Library (sf-skills) on GitHub
• Salesforce Development plugin
• Salesforce Code Quality plugin
• Activate MCP Servers
• Metadata Grounding MCP Server (Beta)

Mohith Shrivastava is a Principal Developer Advocate at Salesforce. Mohith focuses on AI-assisted development and shares practical patterns for building Salesforce apps and agents with coding agents. Follow Mohith on LinkedIn and GitHub.

The post Accelerate Agent-Driven Development with the Headless Toolkit appeared first on Salesforce Developers Blog.

• Introducing Quick Pages（Salesforce ブログ）
• Bring Custom UIs to Life with Quick Pages (Beta)（Winter ’27 リリースノート）

この記事は 2026 年 11 月時点（Winter ’27）の情報で作成しています。一般提供までに、機能や画面、提供条件が変わることがあります。

注意

• Quick Pages はベータ版のサービスです。ご利用はお客様ご自身の判断で行ってください。ベータサービスのご利用には、Beta Services Terms と、Product Terms Directory の Non-GA Agentforce / Non-GA Gen AI の条件が適用されます。
• ベータ期間中、Quick Pages の AI 利用は無料ですが、一般提供後は従量課金の対象になります。
• 本番組織ではなく、Developer Edition などで試すことをおすすめします。本記事の手順は Developer Edition で動作を確認しています。
• 購入をご検討の際は、現在一般提供されている機能をもとにご判断ください。

参考:

• Considerations and Limitations for Quick Pages (Beta)
• Bring Custom UIs to Life with Quick Pages (Beta)（Winter ’27 リリースノート）

動画も公開しました。

Quick Pages とは

一言で表現すると、「話しかけるだけで、組織のデータを使ったページを作れる機能」 です。

• 作りたいページを説明すると、エージェントが React ベースの 1 ページのアプリを作ります。ライブプレビューを見ながら、チャットで直していけます。
• 組織のメタデータ（カスタムオブジェクトや項目も含む）に沿って作られ、データはいつも最新です。グラフ、表、タブなどを入れられます。
• 作ったページは、個人、公開グループ、組織全体に共有できます。見る人には、その人がアクセスできるデータだけが表示されます。
• 管理者権限がなくても、自分で作れます。 ページを作っても組織のメタデータは変わらず、管理者は組織内のすべてのページを確認できます。

使える組織の条件

• Lightning Experience
• Enterprise / Performance / Unlimited / Developer Edition
• Foundations が有効で、Hyperforce 上にある組織

参考:

• Set Up Quick Pages (Beta)
• Bring Custom UIs to Life with Quick Pages (Beta)（Winter ’27 リリースノート）

全体の流れ

1. Quick Pages をオンにする
2. 権限セットを割り当てる
3. ダミーデータを入れる（任意）
4. ページを作る
5. 会話で直す
6. 保存して共有する

今回は Developer Edition & システム管理者での操作で解説します。

事前準備

公式の Set Up Quick Pages (Beta) では、機能をオンにする前に次の 4 つを確認するよう案内されています。

• 組織が Hyperforce 上にあること（設定 > 組織情報 で、インスタンスが「英字 3 文字＋数字」になっていれば Hyperforce）
• 設定 > Salesforce Multi-Framework Apps で、ドメインが有効になっていること（「Enable Domain」ボタンがあれば押す）
• 設定 > 私のドメイン > ルーティングとポリシー で、「Use Salesforce Edge Network」が有効になっていること
• 設定 > Einstein 設定 で、Einstein がオンになっていること

最新の Developer Edition では、これらは最初から満たされています。 そのため、この記事ではすぐに機能の有効化から始めます。既存の組織で試す場合は、上の 4 つを先に確認してください。

ステップ 1：Quick Pages をオンにする

まずは組織で Quick Pages の機能を有効化します。

• 設定 > クイック検索に「Quick」と入力（英語で入力します）
• 「Quick Pages (Beta)」を選択
• 「Quick Pages」のトグルをオンにする

「Quick Pages is turned on in your org.」と表示されれば成功です。

ステップ 2：権限セットを割り当てる

次に、ページを作る人に権限セットを割り当てます。Quick Pages 用の権限セットは 2 つあります。

• クイックページを作成（Create and View Quick Pages (Beta)）: ページを作る人
• クイックページを表示（View Quick Pages (Beta)）: ページを見るだけの人

今回は自分でページを作るので、「クイックページを作成」を自分に割り当てます。

• 設定 > クイック検索に「権限セット」と入力し、「権限セット」を選択
• 「クイックページを作成」を開く
• 「割り当ての管理」>「割り当てを追加」で自分のユーザーを選び、割り当てる

「1 の割り当てに成功しました。」と表示されれば成功です。

以上で初期設定は完了です。

ステップ 3：ダミーデータを入れる（任意）

最新の Developer Edition には、取引先や商談のサンプルデータが入っていませんでした。データが無いとページを作っても中身が空になってしまうので、Anonymous Apex でダミーデータを作ります。お手持ちの組織にデータがある場合は、このステップは飛ばしてください。
作るデータは次のとおりです。

• 取引先「アストロ製作所」1 件（すでにあれば、それを使います）
• 商談 10 件（フェーズ・金額・完了予定日をばらして作成）

ここでは、ブラウザ上で使える Web コンソールから実行します。

• 画面右上の歯車アイコン（設定メニュー）>「Web コンソール」を開く
• コマンドパレットで SFDX: Create Anonymous Apex Script を実行し、スクリプトのファイルを作る
• 作られたファイルに、下のスクリプトを貼り付ける
• エディターの 1 行目の上に出る「Execute」を押す

「Anonymous Apex executed successfully」と表示されれば成功です。
スクリプトは次のとおりです。
scripts/apex/sampledata.apex:

// ============================================================
// ダッシュボード用ダミーデータ作成 (Anonymous Apex) 改訂版
// 取引先: アストロ製作所 (基本情報を拡充)
// 商談 10件
// 実行: Web Console > SFDX: Create Anonymous Apex Script で
//       このファイルの内容を貼り付け > SFDX: Execute Anonymous Apex
// ============================================================
Savepoint sp = Database.setSavepoint();
try {
    // ---------- 取引先 ----------
    Account acc;
    List<Account> existing = [SELECT Id FROM Account WHERE Name = 'アストロ製作所' LIMIT 1];
    if (existing.isEmpty()) {
        acc = new Account(
            Name = 'アストロ製作所',
            Site = '東京本社',
            Type = 'Customer - Direct',
            Industry = 'Manufacturing',
            Rating = 'Hot',
            AccountSource = 'Web',
            Phone = '03-0000-0001',
            Fax = '03-0000-0002',
            Website = 'https://www.example.com/astro',
            NumberOfEmployees = 320,
            AnnualRevenue = 4500000000.00,
            BillingStreet = '大森北1-2-3 アストロビル',
            BillingCity = '大田区',
            BillingPostalCode = '143-0000',
            ShippingStreet = '京浜島4-5-6 第一工場',
            ShippingCity = '大田区',
            ShippingPostalCode = '143-0003',
            Description = '精密部品・産業機械の製造メーカー。国内3拠点の工場を持ち、'
                        + '生産管理・品質管理の高度化を推進中。ダッシュボード検証用ダミーデータ。'
        );
        insert acc;
    } else {
        acc = existing[0];
    }

    // ---------- 商談 (10件: ステージ・金額・クローズ日を分散) ----------
    Date today = Date.today();
    List<Opportunity> opps = new List<Opportunity>{
        new Opportunity(AccountId = acc.Id, Name = 'アストロ製作所 - 生産管理システム導入',
            StageName = 'Prospecting', Amount = 3000000, CloseDate = today.addDays(90),
            LeadSource = 'Web', NextStep = '要件ヒアリング日程調整',
            Description = '既存の表計算ベース管理からの移行案件。'),
        new Opportunity(AccountId = acc.Id, Name = 'アストロ製作所 - 工場見える化ダッシュボード',
            StageName = 'Prospecting', Amount = 1800000, CloseDate = today.addDays(120),
            LeadSource = 'Web', NextStep = '初回提案資料の送付',
            Description = '稼働状況をリアルタイムに把握したいとの要望。'),
        new Opportunity(AccountId = acc.Id, Name = 'アストロ製作所 - 受発注システム刷新',
            StageName = 'Qualification', Amount = 4200000, CloseDate = today.addDays(75),
            LeadSource = 'Partner Referral', NextStep = '予算・決裁フローの確認',
            Description = 'パートナー経由の紹介案件。'),
        new Opportunity(AccountId = acc.Id, Name = 'アストロ製作所 - IoTセンサー追加',
            StageName = 'Needs Analysis', Amount = 5500000, CloseDate = today.addDays(60),
            LeadSource = 'Partner Referral', NextStep = '現地調査の実施',
            Description = '第二工場へのセンサー増設。'),
        new Opportunity(AccountId = acc.Id, Name = 'アストロ製作所 - 設備保全クラウド',
            StageName = 'Proposal/Price Quote', Amount = 2700000, CloseDate = today.addDays(45),
            LeadSource = 'Phone Inquiry', NextStep = '見積書の提出',
            Description = '予防保全の仕組み化を検討中。'),
        new Opportunity(AccountId = acc.Id, Name = 'アストロ製作所 - 基幹システム連携開発',
            StageName = 'Proposal/Price Quote', Amount = 6000000, CloseDate = today.addDays(35),
            LeadSource = 'Web', NextStep = '技術要件のすり合わせ',
            Description = '既存ERPとのAPI連携。'),
        new Opportunity(AccountId = acc.Id, Name = 'アストロ製作所 - 保守契約更新',
            StageName = 'Negotiation/Review', Amount = 1200000, CloseDate = today.addDays(20),
            LeadSource = 'Phone Inquiry', NextStep = '契約書レビュー',
            Description = '年間保守契約の更新。値引き交渉中。'),
        new Opportunity(AccountId = acc.Id, Name = 'アストロ製作所 - 品質管理ツール',
            StageName = 'Closed Won', Amount = 2400000, CloseDate = today.addDays(-15),
            LeadSource = 'Web', NextStep = '導入後フォロー',
            Description = '受注済み。導入完了済み。'),
        new Opportunity(AccountId = acc.Id, Name = 'アストロ製作所 - 従業員向け研修プログラム',
            StageName = 'Closed Won', Amount = 3600000, CloseDate = today.addDays(-70),
            LeadSource = 'Partner Referral', NextStep = '効果測定のレビュー',
            Description = '全拠点で実施した研修パッケージ。'),
        new Opportunity(AccountId = acc.Id, Name = 'アストロ製作所 - 在庫最適化PoC',
            StageName = 'Closed Lost', Amount = 800000, CloseDate = today.addDays(-30),
            LeadSource = 'Other', NextStep = '失注理由の振り返り',
            Description = '競合製品を採用されたため失注。')
    };
    insert opps;

    System.debug('✅ 作成完了: Account=' + acc.Id + ', Opportunity=' + opps.size());
} catch (Exception e) {
    Database.rollback(sp);
    System.debug(LoggingLevel.ERROR, '❌ エラー: ' + e.getMessage() + ' / ' + e.getStackTraceString());
}

// ============================================================
// 【削除用スクリプト】(必要なときだけ別途実行)
// List<Account> a = [SELECT Id FROM Account WHERE Name = 'アストロ製作所'];
// delete [SELECT Id FROM Opportunity WHERE AccountId IN :a];
// delete a;
// ============================================================

試し終わってデータを消したいときは、末尾の【削除用スクリプト】のコメントを外した部分だけを、別のファイルで実行してください。

取引先「アストロ製作所」を開いて、商談が入っていれば準備完了です。

ステップ 4：ページを作る

それではページを作ってみましょう。

• アプリケーションランチャーで「ページ」と検索し、「Quick Pages (Beta)」を開く
• 「New Quick Page」ボタンを押す

右側のチャット欄に、作りたいページを日本語で説明して送ります。今回は次のように入力しました。

取引先"アストロ製作所"の商談ダッシュボードを作成して。商談数や金額合計をタイルで表示、またフェーズごとの数量を棒グラフで見せて

現時点でのハマりどころ：日本語入力の Enter で送信されてしまう
現在のベータ版では、日本語入力のかな漢字変換を確定する Enter で、入力途中の指示が送信されてしまうことがあります。別の場所（テキストエディターなど）で書いた指示を貼り付けて送るのがおすすめです。(改修対応中)

送信すると、エージェントがページを組み立て始めます。今回は 20 秒ほどで、次のようなページができあがりました。上には商談数と金額合計のタイル、その下にはフェーズ別件数の棒グラフと、商談の一覧が並んでいます。

プロンプトは短く具体的に書くのがコツです。現時点では、長いプロンプトは 2 分でタイムアウトします。

ステップ 5：会話で直す

次は、できたページを会話で直していきます。
チャット欄を見ると、エージェントが「NEXT」として、次に直せそうなことを候補で出してくれています。今回は「商談を完了予定日の昇順で並べ替える」を押してみます。
商談の一覧が完了予定日の順に並び替わりました。

続けて、次の候補「商談をフェーズで絞り込んで表示する」を押します。ページの上にフェーズのドロップダウンができました。

ドロップダウンでフェーズを選ぶと、その場で商談が絞り込まれます。チャットで頼んだ機能が、そのまま動くページになっています。
もちろん候補を押すだけでなく、チャット欄に自分で指示を書いて直すこともできます。

ステップ 6：保存して共有する

できあがったら、保存して共有します。

• 画面右上の「Save」ボタンを押す
• 「Name your page」にページ名を入力し、「Save」ボタンを押す

現時点の仕様: 保存したあとはページ名を変えられません。 ここで決めておきましょう。

保存すると、画面右上に「Edit」「Share」「Delete」ボタンが出ます。

直すときは「Edit」です。保存した変更は、共有先にもそのまま反映されます。保存しないで終えた変更は下書きに残り、共有先に見えるのは最後に保存した版です。
共有するときは「Share」ボタンを押します。

• 組織全体に共有する場合: 「All org」にチェックを入れる
• 特定の人に共有する場合: 「Add people or groups」で個人や公開グループを検索して追加する
• 「Save」ボタンを押す

ダイアログにも書かれているとおり、見る人には、その人がアクセスできるデータだけが表示されます。 同じページでも、見る人の権限によって表示される内容が変わります。
以上で、ページの作成から共有までは完了です。

ベータ中の制約

Considerations and Limitations for Quick Pages (Beta) から、試すときに気にしておきたいものを抜き出しました（2026 年 11 月時点）。

• ページは読み取り専用です。ページからレコードの作成・更新・削除はできません。データを変えたい場合は元のレコードを直して、ページを再読み込みします。
• プロンプトは短く具体的に。長いプロンプトは 2 分でタイムアウトします。
• 保存したあとはページ名を変えられません。
• 管理者は他の人のページを見たり共有したりできますが、編集・削除はできません。
• Connect REST API や Apex クラスからデータを取ること、Data 360 や外部 API とつなぐこと、Salesforce CMS やファイルの素材を使うことはできません。
• データエクスポートで組織間を移すことや、パッケージに入れることはできません。

これらは正式リリースの際には変わっている可能性があります。最新の情報は公式ドキュメントをご確認ください。

おわりに

この記事では、Developer Edition で Quick Pages (Beta) を有効化し、ダミーデータを入れて、ページを作る・会話で直す・保存して共有するまでの流れを紹介しました。振り返ると、やることは次のとおりです。

• 機能をオンにして、権限セット「クイックページを作成」を割り当てる
• データが無ければ、Anonymous Apex でダミーデータを作る
• 作りたいページを説明して、会話で直して、保存して共有する

これまで、ちょっとした集計や一覧のページがほしいときは、レポートやダッシュボードを組んだり、Lightning Web Components で画面を作ったりする必要がありました。Quick Pages を使えば、話しかけるだけで、組織の実データを使ったページを、管理者権限なしで作れます。 見る人の権限もそのまま尊重されるので、気軽にチームへ共有できるのもうれしいところです。
ぜひ Developer Edition で Quick Pages を試してみてください。

参考資料

• Introducing Quick Pages（Salesforce ブログ）
• Bring Custom UIs to Life with Quick Pages (Beta)（Winter ’27 リリースノート）
• Set Up Quick Pages (Beta)
• Create and Share Quick Pages (Beta)
• Considerations and Limitations for Quick Pages (Beta)

The post Quick Pages (Beta) を Developer Edition で試す : 有効化からページの作成まで appeared first on Salesforce Developers Blog.

Salesforce Hosted MCP Server を使うと、ChatGPT や Claude などの AI アプリだけでなく、自分で作った AI エージェントからも、MCP (Model Context Protocol) で Salesforce のデータを扱えます。

この記事では、AWS のオープンソースの AI エージェント SDK、Strands Agents でエージェントを作り、Salesforce のケースを読んで、Amazon Bedrock のモデルが判断した優先度を書き戻すまでを解説します。

※この記事の内容を試すには、Salesforce 組織と AWS アカウントが必要です。Salesforce の環境は、無料で取得できる Developer Edition で試せます。Amazon Bedrock の利用には料金がかかります (この記事のエージェントは、1 回の実行で入力が約 1 万トークン、出力が約 3,500 トークンでした)。Hosted MCP Server も組織によっては請求の対象になるので、本番組織では、設定の「MCP サーバー」の画面に出る Flex Credits の案内を確認してください。

※2026 年 11 月時点の情報で作成しています。

この記事のポイント

• Strands Agents の MCPClient にサーバー URL とアクセストークンを渡すと、Salesforce の標準ツールをそのまま使える
• 読み取りと書き込みをサーバーの単位で分け、渡すツールも絞れる。動かせるのは、認可したユーザーの権限の範囲だけ
• 書き込みの結果は、エージェント自身に読み直して確かめさせる

1. 今回作るもの

Python のエージェントを実行すると、Amazon Bedrock のモデルが Salesforce の未対応のケースを読み、件名と説明から優先度を判断して、Priority 項目を書き換えます。ケースの読み書きには Hosted MCP Server のツールを使うので、Salesforce の API を呼ぶコードは書きません。

処理の流れは次のとおりです。

権限の絞り方

エージェントに触らせる範囲は、外側から順に 4 段で絞れます。

1. ユーザーの権限: 認可したユーザーに許された範囲 (オブジェクトの権限、項目レベルセキュリティ、共有ルール) しか動かせません
2. サーバー: 書き込みには、削除のツールを持たない sobject-mutations を使います
3. ツール: Strands の tool_filters で、渡すツールを soqlQuery と updateSobjectRecord に絞ります
4. 人の確認: この記事では省いていますが、Strands の Interrupts で、書き込みの前に人が確認する仕組みも入れられます

2. 事前準備

次のものを用意します。所要時間は 1 時間ほどです。

• Salesforce 組織 (この記事では Developer Edition) と、システム管理者のユーザー
• Salesforce CLI (sf)。古い場合は sf update で更新します (詳しくは Update Salesforce CLI)
• AWS アカウント (Amazon Bedrock を使える権限)
• Python のパッケージ管理ツールの uv (Python 3.12 は uv が入れます)。古い場合は uv self update で更新します (詳しくは Upgrading uv)

※設定のクイック検索に「MCP」と入れて「MCP サーバー」が出ない組織では、Hosted MCP Server を使えません。新しく Developer Edition を取得してください。

この記事は、Python 3.12.14、strands-agents 1.64.0、mcp 2.3.0、Salesforce CLI 2.157.8 で動作を確認しています。

最初に、作業用のプロジェクトを作ります。このあと作るファイルは、すべてこのフォルダに置きます。

uv init --python 3.12 bedrock-case-agent
cd bedrock-case-agent
uv add strands-agents python-dotenv

作り終えたときのファイル構成は次のとおりです (uv が作るファイルは省いています)。

bedrock-case-agent/
├── .env              # 4 で作成。接続情報なので、リポジトリに含めない
├── agent.py          # 6 で作成
├── sf_auth.py        # 5 で作成
├── reset_cases.apex  # 7 で作成 (試し直すとき用)
└── data/
    └── cases.json    # 3 で作成

3. Salesforce 側の設定

ステップ 1：MCP サーバーを有効化する

Hosted MCP Server は、初期状態ではすべて無効になっています。

1. 設定のクイック検索で「MCP サーバー」と入力し、API カタログの「MCP サーバー」を開く
2. 一覧から「sobject-reads」を開き、「有効化」をクリックする
3. 同じように「sobject-mutations」も有効化する

サーバーの状態が「稼働中」になれば完了です。有効化してから使えるようになるまで、最大 2 分ほどかかります。

続けて、sobject-reads と sobject-mutations の詳細画面を開き、「サーバー URL」をそれぞれコピーしておきます。4 のステップ 2 で .env に書きます。

Developer Edition では、次の形の URL が表示されます。

https://api.salesforce.com/platform/mcp/v1/d/<My Domain 名>/develop/platform/sobject-reads
https://api.salesforce.com/platform/mcp/v1/d/<My Domain 名>/develop/platform/sobject-mutations

※URL には組織の My Domain 名が入ります。本番組織や Sandbox では形が少し変わるので、画面の URL をそのまま使ってください (形式の一覧は Find Your Server URL)。

ステップ 2：外部クライアントアプリケーションを作成する

エージェントが OAuth で接続するための外部クライアントアプリケーションを作成します。画面の流れは「Salesforce Hosted MCP Server 使い始め」で詳しく解説されているので、ここでは設定する値をまとめます。

1. 設定のクイック検索で「外部クライアントアプリケーションマネージャー」を開き、「新規外部クライアントアプリケーション」をクリックする
2. 下の表の値を設定して、「作成」をクリックする
3. 作成したら「設定」タブの「OAuth 設定」で「コンシューマー鍵と秘密」をクリックし、メールの確認コードを入力して、コンシューマー鍵をコピーする

※外部クライアントアプリケーションは、作成してから使えるようになるまで、最大 30 分かかることがあります。

※コールバック URL は複数登録できるので、ほかの MCP クライアント (Claude や Postman など) のものも足せば、同じアプリを使い回せます。本番の組織では、クライアントごとにアプリを分けると管理しやすくなります。

ステップ 3：試すためのケースを投入する

エージェントが触るケースを絞るため、ケースの「会社名」 (SuppliedCompany) に目印の BEDROCK-DEMO を入れて投入し、エージェントの SOQL でもこの値で絞ります。

緊急度にばらつきのある 6 件を、優先度はすべて Medium で用意します。data/cases.json を次の内容で作ります。

{
  "records": [
    {
      "attributes": { "type": "Case", "referenceId": "Case01" },
      "Subject": "本番環境で全ユーザーがログインできない",
      "Description": "本日 9:30 頃から全ユーザーが管理ポータルにログインできず、受注処理が止まっています。至急対応をお願いします。",
      "Status": "New", "Priority": "Medium", "SuppliedCompany": "BEDROCK-DEMO"
    },
    {
      "attributes": { "type": "Case", "referenceId": "Case02" },
      "Subject": "夜間バッチ後に取引先の住所データが消えている",
      "Description": "昨夜の連携バッチの後、取引先の約 300 件で住所が空になりました。請求書の発送に影響します。",
      "Status": "New", "Priority": "Medium", "SuppliedCompany": "BEDROCK-DEMO"
    },
    {
      "attributes": { "type": "Case", "referenceId": "Case03" },
      "Subject": "心当たりのない海外 IP からのログイン成功通知が届いた",
      "Description": "今朝、海外の IP アドレスからのログイン成功通知が届きました。チームの誰も海外にはいません。",
      "Status": "New", "Priority": "Medium", "SuppliedCompany": "BEDROCK-DEMO"
    },
    {
      "attributes": { "type": "Case", "referenceId": "Case04" },
      "Subject": "営業ダッシュボードの表示が遅い",
      "Description": "ダッシュボードの表示に 30 秒以上かかるようになりました。使えてはいますが、朝会で待たされています。",
      "Status": "New", "Priority": "Medium", "SuppliedCompany": "BEDROCK-DEMO"
    },
    {
      "attributes": { "type": "Case", "referenceId": "Case05" },
      "Subject": "二要素認証の設定手順書はありますか",
      "Description": "新入社員向けに、二要素認証の設定手順の資料があれば共有してください。急ぎではありません。",
      "Status": "New", "Priority": "Medium", "SuppliedCompany": "BEDROCK-DEMO"
    },
    {
      "attributes": { "type": "Case", "referenceId": "Case06" },
      "Subject": "見積書テンプレートに会社ロゴを入れたい",
      "Description": "見積書のテンプレートに、自社ロゴを入れられるようにしてほしいという要望です。",
      "Status": "New", "Priority": "Medium", "SuppliedCompany": "BEDROCK-DEMO"
    }
  ]
}

Salesforce CLI で組織にログインし、ケースを投入します。1 行目でブラウザが開くので、使う組織でログインします。–alias my-de で付けた別名は、このあとのコマンドの –target-org で使います。

※既定のブラウザでは、使う組織にだけログインしておきます。ほかの組織にもログインしていると、別の組織を認可してしまうことがあります (5 の sf_auth.py も同じです)。

sf org login web --alias my-de
sf data import tree --files data/cases.json --target-org my-de

次のコマンドで、6 件の優先度がすべて Medium になっていれば準備完了です。

sf data query --query "SELECT CaseNumber, Subject, Priority FROM Case WHERE SuppliedCompany = 'BEDROCK-DEMO' ORDER BY CaseNumber" --target-org my-de

画面では、ケースの「私のケース」のリストビューで確かめられます。

4. AWS 側の設定

ステップ 1：Bedrock API キーを発行する

今回は、Amazon Bedrock の API キーで認証します。

1. AWS マネジメントコンソールのリージョンを「アジアパシフィック (東京)」にする
2. Amazon Bedrock のコンソールで、左のメニューの「API キー」を開く
3. 「短期 API キー」タブの「短期 API キーを生成」をクリックし、表示されたキーをコピーする (キーは一度しか表示されません)

※短期 API キーは、発行したリージョンでしか使えません。Amazon Nova のモデルは、利用開始の手続きなしで使えます。

モデルは Amazon Nova 2 Lite を、推論プロファイル jp.amazon.nova-2-lite-v1:0 (東京と大阪のリージョンで処理する ID) で呼び出します。

ステップ 2：.env に接続情報を書く

プロジェクトの直下に .env を作り、次の値を入れます。.env はリポジトリに含めないでください。

# Salesforce
SF_CONSUMER_KEY=<コンシューマー鍵>
SF_LOGIN_URL=https://login.salesforce.com
SF_MCP_READS_URL=<sobject-reads のサーバー URL>
SF_MCP_MUTATIONS_URL=<sobject-mutations のサーバー URL>

# Amazon Bedrock
AWS_BEARER_TOKEN_BEDROCK=<Bedrock API キー>
AWS_REGION=ap-northeast-1
BEDROCK_MODEL_ID=jp.amazon.nova-2-lite-v1:0

SF_MCP_READS_URL と SF_MCP_MUTATIONS_URL には、3 のステップ 1 でコピーしたサーバー URL を書きます。

AWS_BEARER_TOKEN_BEDROCK は、AWS の SDK が Bedrock の API キーとして読み取る環境変数なので、コードでキーを扱う必要はありません。

5. Salesforce の認可を通す

Hosted MCP Server には、OAuth 2.0 の認可コードフロー (PKCE 付き) で取得したアクセストークンで接続します。ブラウザで認可してトークンを保存する、小さなスクリプト sf_auth.py を用意します。

"""Salesforce Hosted MCP Server 用のアクセストークンを、認可コードフロー + PKCE で取得する。

  uv run sf_auth.py login   ブラウザで認可し、トークンを保存する
  uv run sf_auth.py token   アクセストークンを出力する (MCP Inspector での疎通確認用)
"""
import base64
import hashlib
import http.server
import json
import os
import secrets
import sys
import time
import urllib.error
import urllib.parse
import urllib.request
import webbrowser
from pathlib import Path

from dotenv import load_dotenv

load_dotenv()

LOGIN_URL = os.environ.get("SF_LOGIN_URL", "https://login.salesforce.com").rstrip("/")
CLIENT_ID = os.environ.get("SF_CONSUMER_KEY", "")
REDIRECT_URI = "http://localhost:8765/callback"  # 外部クライアントアプリケーションのコールバック URL と同じにする
SCOPES = "mcp_api refresh_token"
TOKEN_FILE = Path("~/.config/bedrock-case-agent/sf_token.json").expanduser()


def _b64url(data: bytes) -> str:
    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()


def _post_token(form: dict) -> dict:
    req = urllib.request.Request(
        f"{LOGIN_URL}/services/oauth2/token",
        data=urllib.parse.urlencode(form).encode(),
        headers={"Content-Type": "application/x-www-form-urlencoded"},
    )
    try:
        with urllib.request.urlopen(req, timeout=30) as res:
            return json.loads(res.read())
    except urllib.error.HTTPError as e:
        sys.exit(f"トークンの取得に失敗しました (HTTP {e.code}): {e.read().decode()}")


def _save(tokens: dict) -> None:
    tokens["saved_at"] = int(time.time())
    TOKEN_FILE.parent.mkdir(parents=True, exist_ok=True)
    TOKEN_FILE.write_text(json.dumps(tokens))
    TOKEN_FILE.chmod(0o600)  # 自分だけが読めるようにする


def login() -> None:
    if not CLIENT_ID:
        sys.exit(".env に SF_CONSUMER_KEY (コンシューマー鍵) を設定してください。")

    # PKCE: code_verifier から code_challenge を作り、認可画面に渡す
    verifier = _b64url(secrets.token_bytes(64))
    challenge = _b64url(hashlib.sha256(verifier.encode()).digest())
    state = secrets.token_urlsafe(16)
    params = {
        "response_type": "code",
        "client_id": CLIENT_ID,
        "redirect_uri": REDIRECT_URI,
        "scope": SCOPES,
        "code_challenge": challenge,
        "code_challenge_method": "S256",
        "state": state,
    }

    result: dict = {}

    class CallbackHandler(http.server.BaseHTTPRequestHandler):
        def do_GET(self):
            url = urllib.parse.urlparse(self.path)
            if url.path == "/callback":
                result.update(urllib.parse.parse_qsl(url.query))
            self.send_response(200)
            self.send_header("Content-Type", "text/plain; charset=utf-8")
            self.end_headers()
            self.wfile.write("認可が完了しました。ターミナルに戻ってください。".encode())

        def log_message(self, *args):
            pass

    server = http.server.HTTPServer(("localhost", 8765), CallbackHandler)
    webbrowser.open(f"{LOGIN_URL}/services/oauth2/authorize?" + urllib.parse.urlencode(params))
    while "code" not in result and "error" not in result:
        server.handle_request()  # コールバックが届くまで待つ
    server.server_close()

    if "error" in result or result.get("state") != state:
        sys.exit(f"認可に失敗しました: {result.get('error_description', result)}")

    # PKCE: トークンを取るときに code_verifier を送る
    tokens = _post_token({
        "grant_type": "authorization_code",
        "code": result["code"],
        "client_id": CLIENT_ID,
        "redirect_uri": REDIRECT_URI,
        "code_verifier": verifier,
    })
    _save(tokens)
    print(f"トークンを保存しました: {TOKEN_FILE}")


def get_access_token(max_age_sec: int = 3600) -> str:
    if not TOKEN_FILE.exists():
        sys.exit("トークンがありません。先に `uv run sf_auth.py login` を実行してください。")
    tokens = json.loads(TOKEN_FILE.read_text())
    if time.time() - tokens["saved_at"] > max_age_sec:  # 保存から時間が経っていたら取り直す
        new = _post_token({
            "grant_type": "refresh_token",
            "refresh_token": tokens["refresh_token"],
            "client_id": CLIENT_ID,
        })
        tokens = {**tokens, **new}
        _save(tokens)
    return tokens["access_token"]


if __name__ == "__main__":
    command = sys.argv[1] if len(sys.argv) > 1 else ""
    if command == "login":
        login()
    elif command == "token":
        print(get_access_token())
    else:
        sys.exit("使い方: uv run sf_auth.py login | token")

ポイントは 2 つです。

• PKCE: 認可画面を開くときに code_challenge を付け、トークンを取るときに code_verifier を送ります。認可コードの横取りを防ぐ仕組みで、コンシューマーの秘密は要りません
• トークンの保存: プロジェクトの外 (~/.config/) に自分だけが読める権限で保存し、60 分を過ぎたらリフレッシュトークンで取り直します

uv run sf_auth.py login

許可の画面が開いたら、要求しているアプリが自分で作った外部クライアントアプリケーションであることを確かめて、「許可」をクリックします。

ターミナルに「トークンを保存しました」と表示されれば完了です。

※MCP Inspector などで接続を確かめたいときは、uv run sf_auth.py token で出力したアクセストークンを使えます。

6. エージェントを書く

agent.py は次のとおりです。

import os

from dotenv import load_dotenv
from strands import Agent
from strands.models import BedrockModel
from strands.tools.mcp import MCPClient

from sf_auth import get_access_token

load_dotenv()  # .env の値 (Bedrock の API キーを含む) を環境変数に読み込む

headers = {"Authorization": f"Bearer {get_access_token()}"}

# 読み取り用: sobject-reads の soqlQuery だけを渡す
reads = MCPClient(
    url=os.environ["SF_MCP_READS_URL"],  # sobject-reads のサーバー URL
    headers=headers,
    tool_filters={"allowed": ["soqlQuery"]},
)

# 書き込み用: sobject-mutations の updateSobjectRecord だけを渡す
mutations = MCPClient(
    url=os.environ["SF_MCP_MUTATIONS_URL"],  # sobject-mutations のサーバー URL
    headers=headers,
    tool_filters={"allowed": ["updateSobjectRecord"]},
)

model = BedrockModel(
    model_id=os.environ["BEDROCK_MODEL_ID"],  # 例: jp.amazon.nova-2-lite-v1:0
    region_name=os.environ["AWS_REGION"],  # 例: ap-northeast-1
    temperature=0,
    # Nova 2 の推論 (考えてから答える機能) をオンにする。オフのままだと、更新のツールを呼ばないことがあった
    additional_request_fields={"reasoningConfig": {"type": "enabled", "maxReasoningEffort": "low"}},
)

SYSTEM_PROMPT = """あなたは Salesforce のサポートケース (Case) をトリアージする日本語の AI エージェントです。

# 手順
1. 次の SOQL を soqlQuery で実行して、未対応のケースを取得する (そのまま使うこと)。
   SELECT Id, CaseNumber, Subject, Description, Priority FROM Case
   WHERE Status = 'New' AND SuppliedCompany = 'BEDROCK-DEMO'
   ORDER BY CaseNumber LIMIT 10
2. 各ケースの件名と説明から、優先度を High、Medium、Low のどれかに判断する。
   - High: 業務停止、データ消失、セキュリティ、法令、本番障害など緊急性が高いもの
   - Medium: 不具合や設定の問題だが、業務は継続できるもの
   - Low: 操作方法の質問、軽微な要望、情報提供の依頼など
3. 判断した優先度が、1 で取得した Priority と異なるケースは、すべて updateSobjectRecord で更新する。
   High への変更も Low への変更も、同じように 1 件ずつ更新する。
   sobject-name は "Case"、id は 1 の結果の Id をそのまま使い、body は {"Priority": "Low"} の形にする。
   Priority 以外の項目は変更しない。
4. 更新が終わったら、1 と同じ SOQL をもう一度 soqlQuery で実行し、Priority が判断どおりになったかを確かめる。
   判断どおりになっていないケースがあれば、もう一度 updateSobjectRecord で更新してから、もう一度確かめる。
5. 最後に、4 で確かめた結果を Markdown の表でまとめる (列: CaseNumber、件名、更新前の Priority、判定、理由、更新後の Priority)。
"""

agent = Agent(model=model, system_prompt=SYSTEM_PROMPT, tools=[reads, mutations])
agent("未対応のケースの優先度を判断して、Priority を更新してください。")

ポイントは 3 つです。

• MCPClient を 2 つ作る: sobject-reads と sobject-mutations に分け、tool_filters で渡すツールを 1 つずつに絞ります。接続の開始と終了は Strands Agents が管理します
• 推論をオンにする: additional_request_fields で Nova 2 の推論 (考えてから答える機能) をオンにしています。オフのままだと、更新のツールを呼ばないことがありました
• 指示文: 使う SOQL と判断基準を固定し、更新のあとに読み直して確かめる手順まで書いています。結果の表の「更新後の Priority」は、読み直した値です

7. 動かしてみる

uv run agent.py

エージェントが soqlQuery でケースを取得し、優先度が変わる 5 件について updateSobjectRecord を呼び出したあと、もう一度 soqlQuery で読み直します。

ログの [REDACTED]. は、推論の中身が表示されない部分です。

最後に、判断の結果が表にまとめて出力されます。

3 の sf data query をもう一度実行するか、リストビューを更新すると、Priority が書き換わっていることを確認できます。

もう一度実行しても、優先度はすでに判断どおりなので、更新は行われません。最初から試し直すときは、次の reset_cases.apex を作って実行し、優先度を Medium に戻します。

// BEDROCK-DEMO の目印が付いたケースを、優先度 Medium、状況 New に戻す
List<Case> cases = [SELECT Id FROM Case WHERE SuppliedCompany = 'BEDROCK-DEMO'];
for (Case c : cases) {
    c.Priority = 'Medium';
    c.Status = 'New';
}
update cases;

sf apex run --file reset_cases.apex --target-org my-de

戻して実行するのを 3 回繰り返したところ、3 回とも同じ結果になりました。

8. 活用法

対象のオブジェクトと指示文を変えれば、同じ形で、期限を過ぎた商談のフェーズの一括更新や、フォローアップの ToDo の作成などにも使えます。読み取りだけで足りる使い方なら、sobject-reads のクライアントだけを渡します。ほかのサービスの MCP サーバーのツールと組み合わせることもできます。

9. よくあるエラーと対処法

invalid_client_id

原因: コンシューマー鍵が違うか、外部クライアントアプリケーションを作成した直後で、まだ使えない

対処: 鍵を確かめてください。作成した直後なら、最大 30 分待ってからやり直します (待ち続けている sf_auth.py は Ctrl + C で止めます)

redirect_uri_mismatch

原因: 外部クライアントアプリケーションのコールバック URL と、sf_auth.py の REDIRECT_URI が違う

対処: どちらも http://localhost:8765/callback にしてください

MCP サーバーに接続できない (404)

原因: MCP サーバーを有効化していない (Server ‘sobject-reads’ exists but is not active. と返ります)

対処: 3 のステップ 1 でサーバーを有効化し、最大 2 分ほど待ってください

ValidationException (モデル ID の指定)

原因: モデル ID に、推論プロファイルではない ID (amazon.nova-2-lite-v1:0 など) を指定している

対処: jp.amazon.nova-2-lite-v1:0 のように、推論プロファイルの ID を指定してください

Bedrock の認証が通らない

原因: 短期 API キーを発行したリージョンが AWS_REGION と違うか、キーの期限 (最長 12 時間) が切れている

対処: AWS_REGION と同じリージョンで、キーを発行し直してください

Your account is currently being verified

原因: AWS アカウントを作った直後で、確認が終わっていない

対処: 確認は通常 2 時間以内に終わるので、待ってから実行してください

更新していないのに「更新しました」と表示される

原因: モデルが、更新のツールを呼ばないまま結果の表を書くことがあります。この記事のエージェントでも、推論をオフにしていたときに起きました

対処: 推論をオンにし、更新のあとに読み直して確かめる手順を指示文に入れたところ、3 回続けて想定どおりに動きました。それでも表はモデルの報告なので、書き込みを伴うエージェントでは、sf data query などで実際の値も確かめてください

まとめ

Strands Agents と Salesforce Hosted MCP Server を組み合わせると、Amazon Bedrock の AI エージェントから、ユーザーの権限の範囲で Salesforce のデータを読み書きできます。ほかのフレームワークのエージェントでも、OAuth で取得したアクセストークンを付けて MCP サーバーに接続する考え方は同じです。書き込みを伴う場合は、読み直して確かめる手順を指示文に入れておくと安心です。

まずは無料で取得できる Developer Edition で試してみてください。

参考リソース

• Salesforce Developers (英語): Hosted MCP Servers: Get Started / Find Your Server URL
• Salesforce Developers (英語): SObject Reads / SObject Mutations
• Salesforce Developers (英語): Create an External Client App / Log In to Your Org
• Strands Agents (英語): Connect your agent to MCP tools / MCP Transports / Amazon Bedrock / Interrupts
• Amazon Bedrock: API キー / Nova 2 Lite
• Amazon Nova: ツールの使用 (関数呼び出し) / トラブルシューティング

The post Amazon Bedrock から MCP サーバー経由で Salesforce を触る appeared first on Salesforce Developers Blog.

Coding agents can already explore your org with the Salesforce CLI, but that means listing metadata one type at a time, across hundreds of types and thousands of components. The Metadata Grounding MCP Server (Beta) searches a pre-indexed catalog of your org’s metadata instead, so the agent can find what already exists before it builds something new.

In this post, you’ll learn how Metadata Grounding works, how to connect it, and how to use it in two examples from a food delivery org called Pronto. 

Why coding agents need your org’s metadata

The Headless Toolkit is how Salesforce brings your org to any agent, app, and experience. Three pieces matter when you build with a coding agent:

• Skills teach the agent how to build on Salesforce. They carry the patterns, the APIs, and the guardrails.
• The Headless 360 MCP Server lets the agent act. It can configure, provision, and change things in your org.
• Metadata Grounding lets the agent see what already exists. It answers the question the other two can’t: what is currently in this org?

Without that third piece, an agent can write correct Apex against the wrong object. With it, the agent checks the org first.

If you’ve read our announcement of the Headless 360 MCP Server Beta, you’ve seen how the Discover tool finds the right Salesforce action to run. Metadata Grounding answers a different question. It finds the things that already exist in your org, such as an object, a field, or a component, so the agent knows what to point that action at.

Here’s how the options an agent has today compare:

How Metadata Grounding works

Metadata Grounding exposes three read-only tools:

As of this writing, it covers more than 70 metadata types, including objects, fields, Lightning web components, Apex classes, flows, and permission sets. Behind it is Salesforce Catalog, where your org’s metadata is stored and indexed. 

The pattern the tools are built for is describe, search, then query. Let the agent learn what exists, narrow to the right type, and read the record before it writes any code.

Note: 

• Metadata Grounding runs as the authenticated user and returns only the metadata that the user is permitted to access. It’s read-only, so it can find and explain, but never change your org.
• Metadata Grounding currently covers core Salesforce metadata. If you need to ground your agents on Data 360 metadata, use the Data 360 MCP Server.

What’s behind the tools

Metadata Grounding reads from Salesforce Catalog, which Data 360 powers. Four pieces matter:

• Extraction. Metadata extractors read your standard and custom metadata from the org. When you turn Salesforce Catalog on, Data 360 runs an initial full sync. How long that takes depends on the size of your org.
• Storage. Data 360 stores the metadata in a metadata data lake object and maps it into a Catalog data model.
• Search index. A hybrid index combines a vector index, which matches on meaning, with a keyword index, which matches on exact terms. That’s why a plain-English query can find MenuBrowserController without the agent knowing its name.
• Access. The Metadata Grounding MCP Server queries that index and returns only what the authenticated user may see.

Salesforce Catalog stays current in two ways. For supported metadata types, it picks up changes without waiting for the scheduled refresh. A full refresh also runs every 24 hours to cover all types, including those that incremental sync doesn’t support yet.

Metadata Grounding MCP Server in action

Most work in an org starts with a question about what’s already there. Where’s the code behind this bug? Do we already have this logic?

The two use cases below answer those questions in that order. Each one ran in Pronto, our sample food delivery org, so the queries and results are real. Both ran in Claude Code with Metadata Grounding connected and a project rule in place that tells the agent to check the org first. You’ll find the rule at the end of this section. Your results depend on your org’s metadata and how well it’s described.

Find the metadata component behind a bug

Here’s the ticket I used in an org installed with Pronto sample app:

“On the menu page, clicking a category doesn’t do anything. I click Breakfast and it still shows me the whole menu. It works when the page first loads, then breaks the moment you touch it. The All Categories button does nothing at all.”

The developer isn’t familiar with this feature, and the org has hundreds of components. There’s no field name to search for, only a symptom. The project folder is empty, so there’s nothing local to grep. I gave the ticket to Claude Code with Metadata Grounding connected and added: “Find whatever is behind that. I don’t know what it’s called. Search by type: look through Apex classes first, then Lightning web components.”

The agent starts with describe_metadata to see what’s available. Then it searches Apex classes by plain English, not by name:

{
  "query": "code that loads a restaurant menu and its categories and items",
  "metadataType": "ApexClass",
  "limit": 8
}

Among the results is MenuBrowserController, whose name and purpose match the symptom. A second search, limited to Lightning web components, finds the component that goes with it:

{
  "query": "menu",
  "metadataType": "LightningComponentBundle",
  "limit": 8
}

In my org that returns c__menuBrowser as the first match. A query_metadata call on it shows the targets it’s exposed on, including record pages, app pages, and Experience Cloud pages.

Metadata Grounding tells the agent what exists and where it lives. It doesn’t return source code. To read the code, the agent switches tools and retrieves only the items it needs into the empty project, such as the controller and the component. The org stays on the server, and only what the fix touches comes down.

Two things to notice. The match came from a business symptom, not a name the developer already knew. And the type filter did real work. The same query without metadataType returns standard fields from across the platform, which is noise.

Note: The Lightning web component record currently has no description, so the ranking relies on the component name and its properties. The richer the descriptions in your org, the better the search gets. More on that in the roadmap “What’s next” section below.

Extend what exists instead of rebuilding it

A developer asks the agent to add a customer review summary to a storefront page for the Pronto app. The project rule tells the agent to check the org first, so before writing anything it searches Apex classes:

{
  "query": "summarize customer reviews for a restaurant",
  "metadataType": "ApexClass",
  "limit": 8
}

The first result is AgentSummarizeReviewsActions, which already exists in the org. A query_metadata call on it returns the full class, including an invocable method labeled “Summarize Reviews” that retrieves recent reviews for a storefront and returns summary statistics. The agent can see the inputs it requires: an account ID and a storefront ID, as well as optional limits for how many days back to look and how many reviews to return.

So the agent builds on the existing class instead of writing a new query. The developer keeps working code, and the team doesn’t end up with two classes that do the same job.

You can make this behavior the default. Add an instruction like this to your project rules or agent instructions:

Before you write code that references an object, field, component, or Apex class, search my org with Metadata Grounding. Query the record you plan to use and confirm it exists. If something similar already exists, extend it instead of creating a new one.

You can also install skills instead of writing the rule yourself. The platform-metadata-grounding-get skill teaches your agent how to use Metadata Grounding. The platform-metadata-discovery-get skill helps it choose between Metadata Grounding, SOQL, and the Salesforce CLI. Both are in the public sf-skills repo.

Choose where to connect

Metadata Grounding is available on two servers, both of which are in Beta.

The Metadata Grounding MCP Server (Beta) is the best way to get started today. It’s read-only, and it works with any MCP-compatible client such as Claude Code, Cursor, or ChatGPT. If you want discovery and reuse and nothing else, start here.

The Metadata Grounding MCP Server will be available out of the box in Agentforce Vibes and included in the Salesforce Development Plugin for Claude Code.

The Headless 360 MCP Server (Beta) is where Metadata Grounding is headed. It’s the one-stop MCP for the Headless Toolkit, exposing the same Metadata Grounding capabilities, along with the tools an agent uses to act on your org. One connection and one place to manage access, with grounding next to action.

The shape differs a little. The standalone server gives your agent three tools directly. Inside the Headless 360 MCP Server, the agent reaches the same capability through the four tools it already uses: 

• Discover finds the grounding workflow, 
• Describe shows its steps, and 
• Dispatch / Dispatch Read Only runs the search and query.

If you build prompts or tests around the three tool names exposed in the standalone MCP server, they won’t carry over unchanged.

Note: We’re working to bring the Headless 360 MCP Server to full parity with the standalone server. We’ll publish guidance on any change before it affects you, and we’ll update this post. The Headless 360 MCP Server will be renamed to the Salesforce MCP Server when it reaches general availability.

Before you begin

• Your org needs an edition that Data 360 supports, with Data 360 provisioned and API Enabled. Salesforce Catalog is opt-in through Data Cloud Setup Feature Manager.
• Data 360 isn’t supported in scratch orgs. Salesforce Catalog isn’t available in Developer Edition orgs that use namespaces.
• An admin sets up the connection and activates the server. All Platform Hosted MCP Servers require admin activation.
• The server returns only the metadata that the authorized user is permitted to access.

Note: The Metadata Grounding MCP Server is a beta service that is subject to the Beta Services Terms. Use of this beta service is at the Customer’s sole discretion.

Tip: Try Metadata Grounding in a sandbox or developer org first, then move to production once your team is comfortable with how the agent uses it.

Connect the Metadata Grounding MCP Server

1. Follow the Platform Hosted MCP Server setup guide to create an External Client App and log in to your org.
2. In Setup, find the Salesforce Hosted MCP Servers section, locate Metadata Grounding Beta, and click Activate.
3. Add the server to your MCP client and authorize.
4. Ask a first question to confirm it works, such as “Which objects track reservations?”

What to know before you rely on it

• Search finds candidates; query confirms them. Have your agent read the full record before it writes code against it.
• Results can lag a change. Something you deployed a moment ago can take time to appear. See the “What’s behind the tools” section for how refresh works.
• The set of types is broad but not complete. Use describe_metadata to see exactly which types your org exposes, and don’t treat a search as an exhaustive inventory.
• It’s read-only. To change your org, pair it with the Headless 360 MCP Server or your existing deployment tools.
• It returns metadata, not source code. The agent can find the Apex class or component and see its properties. To read or edit the code, it retrieves that one item with the Salesforce CLI or the Metadata API.
• Billing. Metadata Grounding usage, including the underlying Data 360 consumption, is metered in production orgs and unmetered in pre-production orgs such as sandboxes and Developer Edition. See Billing Considerations for Salesforce Catalog for details.

What’s next

We’re working on two additions that build on this foundation. AI-Generated Metadata Descriptions will make metadata more meaningful to agents, so searches like the menu example get sharper even when a component has no description today. The Metadata Graph will let an agent use dependency analysis to see what could break before it acts. Want to try them early? Sign up for early access.

Conclusion

Coding agents are only as good as their view of your org. Skills tell them how to build, and the Headless 360 MCP Server lets them act. Metadata Grounding lets them see, so they extend what you have rather than rebuild it.

A good place to start: activate the Metadata Grounding MCP Server in a sandbox that has Salesforce Catalog enabled, add the project rule above, and give your agent a ticket for a feature you suspect already exists somewhere in the org. We welcome your feedback to help shape what ships next.

Watch the Salesforce Developers website for documentation, release notes, and hands-on content.

Resources

• Discover Org Metadata with the Metadata Grounding MCP Server (Beta)
• Metadata Grounding MCP Server (Beta) Dev Documentation
• Platform Hosted MCP Server Setup Guide
• Metadata Grounding Skill (sf-skills)
• Metadata Discovery Skill (sf-skills)
• Ground Users and Agents in Your Metadata with Salesforce Catalog (Generally Available)
• Salesforce Catalog Documentation
• Announcing the Headless 360 MCP Server Beta

About the author

Gonzalo Gambino is a Senior Director of Product Management at Salesforce and the product domain lead for Platform Metadata and Schema. Gonzalo’s domain covers the schema and metadata foundation for the platform, including Metadata Grounding.

The post Metadata Grounding: Let Your Coding Agent Search Your Org by Intent appeared first on Salesforce Developers Blog.

This is the third and final post in our series on Lightning Web Component (LWC) anti-patterns. The first post covered security and platform compatibility. The second post covered the wire service, public properties, and events. In this post, you’ll learn the most common mistakes in DOM access, asynchronous timing, the component lifecycle, performance, and base component usage.

DOM access anti-patterns

LWC renders each component into its own shadow DOM. A component should only read or modify elements it owns. The patterns below cover the ways that boundary gets crossed, accidentally or not.

Don’t query the global document

Calling document.querySelector() or document.getElementById() searches the entire page instead of your component’s shadow tree. Inside Lightning Web Security, these calls are scoped to your sandbox and won’t find elements owned by other components. Outside that environment (in a Jest test without proper mocking, for instance) they may appear to work but behave differently in production.

renderedCallback() {
    // Searches the global document — won't find elements in another component's shadow
    const field = document.querySelector('.my-input-field');
    field?.focus();
}

Scope the query to your own template instead:

renderedCallback() {
    const field = this.template.querySelector('.my-input-field');
    field?.focus();

}

For a cleaner approach that avoids selector fragility altogether, use lwc:ref:

<template>
    <input lwc:ref="inputField" type="text" />
</template>

renderedCallback() {
    this.refs.inputField.focus();
}

Don’t set innerHTML

Setting innerHTML is an XSS risk whenever any part of the string comes from user input, and it bypasses LWC’s reactive rendering pipeline; a later template re-render can overwrite or conflict with markup you injected imperatively. Lightning Web Security sanitizes innerHTML on shared elements such as <body>, but it doesn’t protect the markup inside your own component, so that responsibility stays with you. The no-inner-html rule in the LWC ESLint plugin flags this pattern automatically.

renderedCallback() {
    const el = this.template.querySelector('.output');
    el.innerHTML = `<strong>${this.label}</strong>`;
}

Express the markup declaratively in the template instead:

<template>
    <div class="output"><strong>{label}</strong></div>
</template>

If you need to render arbitrary HTML from a trusted source, such as rich text from a CMS, use the lightning-formatted-rich-text base component, which applies platform-level sanitization.

Don’t use ID selectors in querySelector

LWC rewrites id attributes in templates into globally unique values at render time, to prevent collisions across components on the same page. The id you wrote in your HTML won’t match what’s in the rendered DOM, so this.template.querySelector('#myId') is unreliable.

<template>
    <input id="nameInput" type="text" />
</template>

renderedCallback() {
    // The rendered id will be something like "nameInput-123", not "nameInput"
    const input = this.template.querySelector('#nameInput');
}

Use class selectors, data attributes, or lwc:ref instead:

<template>
    <input lwc:ref="nameInput" type="text" />
</template>

renderedCallback() {
    const input = this.refs.nameInput;
}

Asynchronous timing anti-patterns

setTimeout shows up as a timing workaround in two very different LWC scenarios, and both are fragile for the same underlying reason: they couple your logic to an arbitrary wall-clock delay instead of to the thing you’re actually waiting for.

Don’t use setTimeout to wait for async data

Wrapping data processing in a timeout, hoping a fetch or state update has “finished” by the time it fires, is unreliable. The timeout can fire before or after the data is ready depending on load, and there’s no signal telling you it actually completed.

handleUpdate() {
    this.isLoading = true;
    // Hoping 100ms is enough for the data to arrive
    setTimeout(() => {
        this.processData();
        this.isLoading = false;
    }, 100);
}

Use async/await so the work runs exactly when the data is ready:

data; // holds the loaded data
async handleUpdate() {
    this.isLoading = true;
    try {
        this.data = await loadData();
    } finally {
        this.isLoading = false;
    }
}

Don’t use setTimeout to wait for a re-render

Setting a reactive property and immediately trying to read the updated DOM also fails, because LWC batches and applies DOM updates asynchronously. setTimeout(..., 0) often appears to work in testing, but it isn’t guaranteed because it depends on timing rather than a signal from the engine, and it breaks under load.

handleShowPanel() {
    this.showPanel = true;
    // DOM hasn't updated yet — querySelector returns null
    setTimeout(() => {
        this.template.querySelector('.panel input').focus();
    }, 0);
}

Use renderedCallback() instead. The engine calls it after every render cycle, guaranteeing the DOM reflects the latest state:

_shouldFocusInput = false;

handleShowPanel() {
    this.showPanel = true;
    this._shouldFocusInput = true;
}

renderedCallback() {
    if (this._shouldFocusInput) {
        this._shouldFocusInput = false;
        const input = this.template.querySelector('.panel input');
        input?.focus();
    }
}

Lifecycle anti-patterns

Several APIs are unavailable, or unreliable, at specific points in a component’s lifecycle. Most lifecycle bugs come from reaching for one of these APIs one hook too early.

Don’t access @api properties in the constructor

The constructor() runs before the parent has set any @api property values. Reading one in the constructor returns undefined, which leads to incorrect initialization.

export default class MyComponent extends LightningElement {
    @api recordId;

    constructor() {
        super();
        // recordId has not been set yet — this.recordId is undefined
        this.fetchData(this.recordId);
    }
}

To be clear about what is fine in a constructor: setting default values for your own class properties is a perfectly normal use of it. The restriction is specifically on reading @api properties (their values haven’t been set yet) and touching the DOM (nothing has rendered; see the next pattern). For initialization logic that depends on an @api value, use connectedCallback(), or better, drive it with @wire, which re-runs automatically when the reactive property changes:

export default class MyComponent extends LightningElement {
    @api recordId;

    @wire(getRecord, { recordId: '$recordId', fields: [NAME_FIELD] })
    record;
}

Don’t access the DOM in the constructor or connectedCallback()

The rendering pipeline is asynchronous. When constructor() runs, nothing has been rendered yet, so this.template.querySelector() returns null. connectedCallback() fires when the component is inserted into the DOM tree, but its children have not rendered yet either. On first connection, a query in either hook returns null, so the code either throws a TypeError or, if you use optional chaining, silently does nothing.

export default class MyComponent extends LightningElement {
    constructor() {
        super();
        // DOM not rendered yet — returns null
        const input = this.template.querySelector('input');
        input.focus(); // throws: Cannot read properties of null
    }

    connectedCallback() {
        // Child elements don't exist yet, so this returns null
        const panel = this.template.querySelector('.panel');
        panel.classList.add('active'); // throws: Cannot read properties of null
    }
}

Use renderedCallback() for anything that reads or modifies rendered DOM elements, guarded with a flag if the setup should run only once:

export default class MyComponent extends LightningElement {
    _initialized = false;

    renderedCallback() {
        if (this._initialized) return;
        this._initialized = true;

        const input = this.template.querySelector('input');

        input?.focus();

    }
}

renderedCallback() fires after every render, not just the first, so the guard matters. For DOM updates that should track ongoing data changes rather than run once, let the template handle them declaratively instead of reaching for imperative DOM code at all.

Don’t access this.template.children

this.template.children returns the immediate children of your component’s template root, but the LWC engine makes no guarantee about their structure or order. Reading them directly ties your logic to rendered DOM structure instead of component intent, and that structure can shift with unrelated template changes.

renderedCallback() {
    const firstChild = this.template.children[0];
    firstChild.classList.add('active');
}

Use this.template.querySelector() with a stable selector, or lwc:ref, to reference elements by intent rather than by position:

<template>
    <div class="main-panel" lwc:ref="panel"></div>
</template>

renderedCallback() {
    this.refs.panel.classList.add('active');
}

Performance anti-patterns

Lightning Web Security introduces proxy overhead at the boundary between the host environment and your component’s sandbox. For most components, this overhead is negligible, but it becomes measurable when a component processes large volumes of data or crosses that boundary repeatedly in a tight loop.

Clone host-environment data before processing it in a loop

Data returned by Apex controllers and Lightning Data Service (LDS) wire adapters originates outside your component’s sandbox. Every property access on that data crosses the proxy boundary. For a handful of fields, this cost is imperceptible. Over thousands of rows, across every sort, filter, and render cycle, it adds up to noticeably degraded responsiveness.

@wire(getOpportunities)
wiredOpps({ data }) {
    if (data) {
        // Each access to opp.Amount and opp.StageName crosses the proxy boundary
        this.total = data.reduce((sum, opp) => sum + opp.Amount, 0);
        this.openOpps = data.filter(opp => opp.StageName !== 'Closed Won');
    }
}

Clone the data into your own namespace once, on arrival, and process the local copy from then on:

@wire(getOpportunities)
wiredOpps({ data }) {
    if (data) {
        // Clone once on arrival so subsequent processing uses local objects
        const local = JSON.parse(JSON.stringify(data));
        this.total = local.reduce((sum, opp) => sum + opp.Amount, 0);
        this.openOpps = local.filter(opp => opp.StageName !== 'Closed Won');
    }
}

Where possible, push the aggregation itself server-side into Apex, so the client receives a precomputed result instead of a large collection to iterate over.

Prefer plain objects and arrays over Set and Map for large collections

Set, Map, and typed arrays carry the same proxy overhead as host-environment data when accessed inside a namespace sandbox. Processing tens of thousands of items through these structures produces performance degradation you wouldn’t see in an equivalent non-sandboxed environment.

processIds(records) {
    // Map and Set carry proxy overhead per operation at scale
    const seen = new Set(); // passed through the loop
    const index = new Map();
    records.forEach(r => {
        seen.add(r.Id);
        index.set(r.Id, r);
    });
    return index;
}

Use plain objects and arrays for large collections instead:

processIds(records) {
    const seen = {}; // passed through the loop
    const index = {};
    records.forEach(r => {
        seen[r.Id] = true;
        index[r.Id] = r;
    });
    return index;
}

Reserve Set and Map for small collections, where the overhead is negligible, or for cases where their semantics (non-string keys, insertion-order iteration) are genuinely required.

Base component usage anti-patterns

Base Lightning components behave differently across the runtimes your component can end up in, including Lightning Experience, Lightning Web Runtime (LWR) sites, Experience Cloud, and the Salesforce Mobile App. Several of the following failures are silent: nothing throws, the component just doesn’t do what you expect.

Don’t use platformShowToastEvent outside Lightning Experience

lightning/platformShowToastEvent dispatches a toast using an event-based mechanism that’s only supported in Salesforce Classic, Lightning Experience, and the mobile app. It’s a silent no-op in LWR sites and Experience Cloud. No error; no toast.

import { ShowToastEvent } from 'lightning/platformShowToastEvent';

handleSuccess() {
    // Silent no-op in LWR and Experience Cloud
    this.dispatchEvent(new ShowToastEvent({
        title: 'Success',
        message: 'Record saved.',
        variant: 'success'
    }));
}

Use lightning/toast instead, which works across all supported containers:

import LightningToast from 'lightning/toast';

handleSuccess() {
    LightningToast.show({
        label: 'Success',
        message: 'Record saved.',
        variant: 'success'
    });
}

Don’t extend unsupported base components

Only two base components officially support class extension: lightning/modal and lightning/datatable. Extending any other base component relies on internal implementation details that can change in any release without notice.

import LightningCombobox from 'lightning/combobox';

// Extending an unsupported base component
export default class CustomCombobox extends LightningCombobox {
    connectedCallback() {
        super.connectedCallback();
        this.doCustomSetup();
    }
}

Wrap the base component instead, and delegate to it through @api properties and events:

export default class CustomCombobox extends LightningElement {
    @api label;
    @api options;
    @api value;

    handleChange(event) {
        this.dispatchEvent(new CustomEvent('change', {
            detail: { value: event.detail.value }
        }));
    }
}

<template>
    <lightning-combobox
        label={label}
        options={options}
        value={value}
        onchange={handleChange}>
    </lightning-combobox>
</template>

Consuming components use c-custom-combobox exactly as they would the base component. The wrapper’s @api properties and change event give it the same surface:

<c-custom-combobox
    label="Status"
    options={statusOptions}
    value={status}
    onchange={handleStatusChange}>
</c-custom-combobox>

Don’t read the record ID from the submit event

When lightning-record-form or lightning-record-edit-form creates a new record, the record’s ID doesn’t exist yet at submit time. Reading event.detail.id in an onsubmit handler returns undefined silently, with no error.

handleSubmit(event) {
    // undefined for new records — the record hasn't been created yet
    const newRecordId = event.detail.id;
    this.navigateToRecord(newRecordId);
}

Use the success event instead, which fires after the record is saved and the server has assigned an ID:

handleSuccess(event) {
    const newRecordId = event.detail.id;
    this.dispatchEvent(new CustomEvent('recordcreated', {
        detail: { recordId: newRecordId }
    }));
}

<lightning-record-form
    object-api-name="Account"
    fields={fields}
    onsuccess={handleSuccess}>
</lightning-record-form>

submit is still the right event for intercepting or modifying a form submission before it goes out; just not for reading the ID that comes back.

Don’t override a base component’s internal SLDS styles

Base components like lightning-button and lightning-input render their internal markup inside the LWC shadow DOM. Their internal class names, such as .slds-button_brand, .slds-input, and similar, are implementation details, not a public API. CSS that reaches into a base component’s shadow to target these classes is unsupported, and it breaks silently whenever SLDS changes internal markup or styling, including changes made for accessibility fixes or SLDS token updates.

/* Targeting an internal SLDS class inside lightning-button — unsupported */
.slds-button_brand {
    background-color: #e07d00 !important;
}

Use the public styling hooks (--slds-* CSS custom properties) that the component exposes as its actual styling API. For example, to restyle a brand lightning-button, set its component hooks (which currently apply only to SLDS 1) from your own stylesheet:

:host {
    --slds-c-button-brand-color-background: var(--slds-g-orange-70);
    --slds-c-button-brand-color-border: var(--slds-g-orange-70);
}

Stick to the public --slds-* hooks. The older --lwc-* hooks are legacy and discouraged, and overriding them can trigger validation warnings. If the component doesn’t expose a hook for what you need, wrap it and style the wrapper, or build the element from scratch if the customization runs deep enough.

Check mobile support before using a base component on a mobile-facing page

The Salesforce Mobile App uses a different rendering pipeline than the desktop browser, and some base components have no mobile implementation, or a reduced one. Using one on a page that also renders in the mobile app fails silently. The component renders incompletely or blank, with no error.

The most common case is lightning-datatable, which is not supported in the Salesforce Mobile App. It renders correctly in a desktop browser and even in a mobile browser’s responsive mode, which makes the failure easy to miss until it’s tested in the native app itself.

<!-- lightning-datatable is not supported in the Salesforce Mobile App -->
<template>
    <lightning-datatable
        key-field="id"
        data={products}
        columns={columns}
        onrowaction={handleRowAction}>
    </lightning-datatable>
</template>

Detect the form factor at runtime and render a mobile-appropriate alternative:

import FORM_FACTOR from '@salesforce/client/formFactor';

export default class MyProductList extends LightningElement {
    isMobile = FORM_FACTOR === 'Small';
}

<template lwc:if={isMobile}>
    <template for:each={products} for:item="product">
        <c-product-tile key={product.id} record={product}></c-product-tile>
    </template>
</template>
<template lwc:else>
    <lightning-datatable
        key-field="id"
        data={products}
        columns={columns}
        onrowaction={handleRowAction}>
    </lightning-datatable>
</template>

If the mobile and desktop experiences differ substantially, consider rendering multiple templates instead of stacking lwc:if blocks. This approach lets a component ship separate templates and choose between them in a render() method.

Before deploying a custom component to a page that appears in the mobile app, check the Component Reference for mobile support, and test in the native app, since desktop responsive mode doesn’t accurately simulate the mobile runtime.

Conclusion

The patterns in this post share a common root: assuming something is ready before it actually is. The DOM isn’t there yet in the constructor. A render hasn’t finished just because you set a property. An @api value isn’t set until the parent sets it. A base component that works in Lightning Experience isn’t guaranteed to work in LWR, Experience Cloud, or the mobile app.

Across this series, the underlying lesson has been the same: LWC guarantees are specific and narrower than they first appear. Security layers namespace and sanitize more than they block. The wire service is a subscription, not a fetch. And the runtime a component renders in shapes what’s actually available to it. Once those models are correct, most of the anti-patterns in this series stop looking like traps and start looking obvious.

Resources

• Component lifecycle documentation
• Create DOM elements
• lwc:ref documentation
• lightning/toast documentation
• @salesforce/client/formFactor
• @lwc/eslint-plugin-lwc rules

About the author

Tim Dionne is a Principal Member of Technical Staff (PMTS) on the Customer Centric Engineering team. He’s worked on many UI features of Salesforce over the years, starting with VisualForce, Aura Components, and Lightning Web Components with an emphasis on Lightning Web Security and Lightning Data Service.

The post Runtime Behavior Anti-Patterns in Lightning Web Components appeared first on Salesforce Developers Blog.

The October 2026 release of B2C Commerce gives you the tools to see and control both. The SCAPI zone (the eCDN zone in front of your Commerce API traffic) is now manageable in Business Manager and the CDN API. The new SCAPI Identity Header (SIH) lets you accept Shopper API traffic only from Managed Runtime (MRT). Verified-bot fields let you identify AI crawlers and agents on any eCDN zone.

This post covers:

• What the SCAPI zone is and what you can control there
• How to restrict Shopper API traffic to Managed Runtime traffic with the SIH
• How to allow your other legitimate API clients
• How to harden SLAS, the login service behind SCAPI
• How to identify AI crawlers and shopping agents, and manage them with rate limits and SEO controls

The SCAPI zone and what you can control there

The SCAPI zone is provisioned automatically. You can’t create it or change its hostnames, and it appears alongside your storefront zones in the zone list. One SCAPI zone is shared across your Development, Staging, and Production instances, and you manage it from Production only. Business Manager shows a shared-zone banner, and some Salesforce-managed rules are locked.

What you can control: custom firewall rules, rate limiting, IP access lists, HTTP and security analytics, and cache purge.

What isn’t available: WAF managed rulesets, mutual TLS (mTLS), TLS 1.3 settings, HTTP Strict Transport Security (HSTS), Page Shield, and Under Attack Mode. The Crypto tab is read-only.

Restrict Shopper API traffic to Managed Runtime with the SCAPI Identity Header

If all your Shopper API traffic comes from MRT (Composable Storefront or Storefront Next), you can close the direct-to-API path that bots use to get around your CDN and MRT.

First, turn on the Managed Runtime SCAPI Request Identification feature in each instance you want to protect. Managed Runtime then attaches the SIH, a shared secret that Salesforce generates and rotates for you, to every request it forwards to SCAPI. A locked, Salesforce-managed allow rule appears in the SCAPI zone. It’s scoped to the instance by an org-specific path segment, for example f_ecom_abcd_prd for Production.

Next, add a custom firewall rule on the SCAPI zone’s Security Rules tab that blocks everything else for the same path segment:

# Block direct Shopper API traffic for the Production instance
Expression: URI Path contains "f_ecom_abcd_prd" and URI Path contains "/shopper"
Action:     Log first to verify matches, then Block

Start with the Log action and confirm what traffic matches. Then switch to Block and drag the rule directly after that instance’s managed allow rule. Rules run in order, so the allow rule passes legitimate Managed Runtime traffic before your block rule runs.

Allow your other API clients

A custom Backend for Frontend (BFF), mobile app backend, or partner integration may call the Shopper API directly by design. It can’t present the Managed Runtime SIH, so the block rule will catch it too. Give each integration its own allow rule, placed above the block rule:

# Allow a custom BFF integration for Production
Expression: URI Path contains "f_ecom_abcd_prd" and URI Path contains "/shopper"
            and HTTP Request Header "X-Integration-Secret" equals "<your-shared-secret>"
Action:     Skip (remaining custom rules)

Generate a long random value for <your-shared-secret>, store it server-side, rotate it regularly, and treat it like any other API credential. Never send it from a browser or mobile client, because anyone can read it there. Use a separate secret and allow rules for each integration.

Harden SLAS

Every Shopper API call needs a shopper access token, and SLAS (Shopper Login and API Access Service) issues those tokens. A bot that can’t get a token can’t call Shopper API, so attackers go after SLAS itself, for example by running credential stuffing against its /login endpoint. Harden SLAS along with the SCAPI zone.

Turn on Strict Client Auth for private clients. SLAS then requires every /login and /authorize request to carry this header:

x-slas-client-auth: Base64(client_id:client_secret)

A missing or wrong secret gets a 401, so a leaked or guessed client_id alone can no longer drive your login endpoints. Keep private-client secrets server-side.

Compatibility: Composable Storefront (PWA Kit) and Storefront Next don’t send this header yet. If you turn on Strict Client Auth for a private client either storefront uses, /login and /authorize return 401 and shoppers can’t log in. Until support ships, enable it only for private clients called from your own server-side code, such as a custom BFF. Check SLAS Best Practices for current status.

Let the refresh-token throttle work for you. SLAS allows 3 refresh-token exchanges per 60 seconds and returns a 429 with a Retry-After header beyond that. Reused, revoked, or unknown tokens count toward the same limit.

Forward c_* headers into your bot logic. SLAS passes custom headers prefixed with c_ from the /login request through to B2C Commerce. Use them to give a third-party bot manager or your own origin checks per-request context.

For client types, guest-token rotation, and token validation, see SLAS Best Practices.

Identify AI crawlers and shopping agents

Blocking unwanted API access is one half of the problem. The other half is traffic you may want, just not at any volume: AI crawlers, AI search, and shopping agents acting for shoppers. eCDN gives you two fields to identify it, with no extra entitlement, on every eCDN zone, both storefront and SCAPI:

• Known Bot (cf.client.bot): true when the request comes from a bot Cloudflare has verified, such as a search engine crawler or AI agent.
• Verified Bot Category (cf.verified_bot_category): sorts verified bots into categories, so you can tell a model-training crawler from a shopping agent or a search indexer.

Use them alongside signals you already see in logs and analytics, such as a rising share of “direct” traffic with no referrer or UTM landing straight on product detail pages, or near-identical queries repeating at machine speed.

To act on them, add a condition to a custom firewall rule, for example:

cf.verified_bot_category in {"AI Crawler" "AI Search"}

Then choose an action such as Log, Managed Challenge, Block, or Skip.

The Verified Bot Category field covers 17 categories. Here are the most relevant ones:

Treating categories differently is the point. For example, you can let Search Engine Crawler traffic index your catalog while rate limiting AI Crawler and AI Search traffic on your most expensive endpoints.

Act on AI traffic: rate limit, then steer

Some AI training controls exist only in robots.txt. For example, Google-Extended controls whether Google uses your content for Gemini, but Google crawls with Googlebot, so an edge rule can’t single it out. Once you can identify AI traffic, rate limit it on your most expensive endpoints instead of blocking it outright. Search and recommendation calls are the usual cost drivers. Here’s an example rate-limiting rule that works on a storefront zone or the SCAPI zone:

# Rate limit AI crawlers and AI search on product search
Expression: cf.verified_bot_category in {"AI Crawler" "AI Search"}
            and URI Path contains "/product-search"
Counting:   per IP
Threshold:  30 requests per 60 seconds   (example; tune from your logs)
Action:     Log first, then Block for 10 minutes

On the SCAPI zone, which Development, Staging, and Production share, add and URI Path contains "f_ecom_abcd_prd" (your org+instance-specific path segment) to scope the rule to one instance. Storefront zones belong to a single instance, so they don’t need this condition.

For Storefront Reference Architecture (SFRA) storefronts, scope the path to your search controller instead, for example Search-Show. Run the rule in Log mode and check the matches in Security Analytics before you enforce it. Set thresholds well above real shopper behavior; a shopper applying eight refinements, for example, shouldn’t trip a limit meant for agents.

Match your edge rules to what you publish: use robots directives and crawler settings to tell crawlers what they may access, and let eCDN rules enforce it. See SEO & Discoverability for B2C Commerce.

Known Bot and Verified Bot Category only identify bots that Cloudflare has verified. To catch unverified or spoofed automation, you need behavioral detection such as bot scores and fingerprinting. That’s available from a third-party bot mitigation partner, a stacked CDN, or your own Cloudflare zone with Bot Management in front of eCDN. See the Bot Management Developer Guide for the options.

Conclusion

Bots that skip the storefront and AI agents that don’t need to are two sides of the same shift. With the October 2026 release you can see your SCAPI traffic, accept the Shopper API traffic only from Managed Runtime and the integrations you trust, harden SLAS, and decide how much AI traffic each endpoint should take. Start every new rule in Log mode, confirm what it catches, then enforce. For edge protection of your login forms, see our companion post, Stop Credential Stuffing at the Edge with B2C Commerce eCDN.

Resources

• SCAPI Zone overview
• Restrict SCAPI Access to Managed Runtime Traffic (SCAPI Identity Header)
• SLAS Best Practices
• SCAPI Security
• Allow Traffic from Search Engine and Other Verified Bots with eCDN Rules
• Create a Custom Firewall Rule for an eCDN Zone
• Create a Rate Limiting Rule for an eCDN Zone
• SEO & Discoverability for B2C Commerce Overview
• Knowledge Article: Mitigating Scrapers and AI Crawlers
• Knowledge Article: AI Crawler and Agent Traffic
• Bot Management Developer Guide

About the Author

Raghu Venkatraman is a Director of Product Management at Salesforce, where he drives product and bot mitigation strategy for B2C Commerce. With extensive experience in enterprise software and a passion for building user-centric solutions, Raghu focuses on delivering products that help organizations work more efficiently and effectively. Follow him on LinkedIn.

The post Protect Your Salesforce Commerce API (SCAPI) from Bots and AI Agents with eCDN appeared first on Salesforce Developers Blog.

Salesforce Data 360 provides the foundation for bringing data, semantics, and AI-powered analytics together on the Salesforce Platform. Data lake objects (DLOs) hold ingested data, and data model objects (DMOs) organize it into a consistent structure. A Tableau semantic data model (SDM) enriches that data with reusable business definitions, relationships, and calculations. Agentforce Agent uses this shared foundation to answer analytical questions, while Model Context Protocol (MCP) extends access to connected AI clients. Together, these capabilities keep data and business logic on one platform while supporting consistent answers across conversational experiences.

By bringing Data 360, Tableau Semantics, and AIforce together, you can:

• Keep metrics consistent: Reuse the same calculations across reports, applications, and agent responses.
• Ask questions in business terms: Explore data using familiar language without needing to know underlying object and field names.
• Ground AI answers in business context: Give agents shared definitions to help interpret questions and return relevant results.
• Reduce development effort: Reuse established relationships and calculations instead of rebuilding logic for each experience.
• Maintain definitions in one place: Update shared business logic as requirements evolve.
• Keep data, semantics, and analytics on one platform: Bring together your Data 360 data, Tableau semantic model, and Agentforce analytics experience without adding a separate analytics platform.
• Apply governance across your analytics foundation: Use Data 360 classifications, governance tags, and policies to help control access to sensitive data and support governed analytical experiences.

This post explores how AIforce, Data 360, and Tableau Semantics work together to ground conversational analytics in shared business definitions and deliver more consistent, trusted answers.

How Data 360 and Tableau Semantics power conversational analytics

Delivering trusted conversational analytics requires data ingestion, shared business definitions, and end-user experiences to work together.

The workflow begins in Data 360. Data streams map Salesforce CRM objects and fields to corresponding data lake objects (DLOs) and fields, then ingest CRM records into those DLOs.

Next, you define the business context in an Open Semantic Interchange (OSI) specification that references the ingested DLOs and their fields. The Salesforce converter translates supported definitions into an initial Tableau semantic data model (SDM) definition. You then complete any missing relationships, metrics, and calculations before creating and validating the SDM in Tableau Semantics.

Applications query the SDM through the Semantic Query API. An MCP server exposes this capability to connected AI clients, while Agentforce agents can also use the same SDM to answer business questions. These experiences draw on shared business definitions and calculations, helping users get consistent answers across applications and conversational interfaces.

Defining business meaning with OSI YAML

To build the semantic model, you first create an OSI YAML specification that captures the business meaning of the data. Its object and field references match the data available in Data 360, and it brings together four elements:

For example, “pipeline value” could mean all open deals, deals expected to close this quarter, or their probability-weighted value. The business chooses the meaning that fits its reporting needs, and you capture it in the YAML specification so connected experiences use the same definition.

You then use this YAML file as the input to the Salesforce conversion workflow. After importing the supported definitions into Tableau Semantics, you complete and validate any calculations and metrics that aren’t carried through conversion.

How to create and validate a semantic data model

With the OSI YAML specification in place, you can turn the business definitions into a semantic data model that applications and agents can query. The workflow below takes you from preparing the data in Data 360 to converting the specification, creating and validating the model, and checking its results.

The following steps use Salesforce APIs to create, validate, and query the semantic model. These API calls can also be incorporated into scripts or deployment workflows to automate the process.

1. Prepare the data in Data 360

Connect Salesforce CRM to Data 360 and ingest the required records through data streams into DLOs. Before converting the specification, confirm that the YAML’s object and field references match the corresponding Data 360 object API names, field names, and object types (DLO or DMO). Add the required Data 360 metadata to the YAML—including the data space API name, source object API name, object type, and field data types—before running the converter, as described in the OSI workflow.

2. Convert the OSI YAML to SDM JSON

Use the Salesforce Ossie converter to translate supported YAML definitions into a Tableau Next SDM definition in JSON. After setting up the converter, run:

java -jar <converter.jar> toSF <specification.yaml>

The command generates a JSON file named after the model’s API name, such as sales_pipeline_health_and_deal_risk.json. This file provides the starting definition for creating the SDM in Data 360.

3. Complete and create the semantic model

Review the generated JSON to confirm that it references the correct Data 360 objects, and complete any missing calculations, metrics, and descriptions. Then submit the completed definition to create the semantic model:

sf api request rest /services/data/v65.0/ssot/semantic/models \
  --target-org '<alias>' --method POST \
  --body @sales_pipeline_health_and_deal_risk.json

4. Validate the semantic model

Validate the saved model to check its definitions and references:

sf api request rest \
  /services/data/v65.0/ssot/semantic/models/sales_pipeline_health_and_deal_risk/validate \
  --target-org '<alias>'

Review any validation errors and correct the model as needed. Confirm that validation returns isValid: true before checking the model’s query results.

5. Query the model and verify results

Create a query file that references your saved semantic model and selects the measures you want to retrieve, as shown below:

{
  "semanticModelApiName": "sales_pipeline_health_and_deal_risk",
  "structuredSemanticQuery": {
    "fields": [{
      "expression": {
        "semanticField": { "name": "open_pipeline_amount" }
      },
      "alias": "open_pipeline_amount"
    }]
  }
}

sf api request rest /services/data/v65.0/semantic-engine/gateway \
  --target-org '<alias>' --method POST \
  --body @<query-file.json>

Check that the response includes the requested measures and that the results match the underlying data for the same filters and business definitions.

How business preferences guide the answer

Along with relationships and calculations, the deployed SDM includes business preferences that guide how agents interpret and explain results. These preferences can guide agents to:

• Use the organization’s business terminology.
• State the reporting period and scope.
• Highlight missing data and explain relevant context.

How verified questions guide answers

After deploying the SDM, you manually create verified questions through Q&A Calibration. You enter representative business questions, review the generated answers, and verify that they use the intended metrics, filters, and business definitions. These verified examples help the agent answer similar questions more consistently.

Conversational analytics with Agentforce and Claude (via MCP)

The following examples show an Agentforce agent and Claude (connected through MCP) answering the same business question:

“How much open pipeline do we have for Q4 2026, and how many opportunities does it include?”

The following experiences use the Semantic Query API to query the Tableau Next SDM for the quarter’s open pipeline amount and opportunity count.

In Agentforce, the agent uses the semantic model to retrieve the requested metrics and explain the results.

In Claude Code, the client accesses the same semantic model through Tableau Next MCP, using the same business definitions to answer the question.

In Claude Desktop, the client accesses the same semantic model through Tableau Next MCP, using the same business definitions to answer the question.

Conclusion

With your data in Data 360, Tableau Semantics and Agentforce bring data, business definitions, and conversational analytics together on the same platform. You can build on this foundation without adding a separate analytics platform, while MCP extends access to the same semantic model through clients such as Claude Code.

OSI helps capture reusable semantic definitions, and the SDM puts those definitions to work through shared relationships and calculations. Model validation, business preferences, and verified questions help align analytical results and explanations with business expectations. Data 360 classifications, governance tags, and policies complement this foundation by helping control access to sensitive data.

Together, these capabilities let you reuse business logic across experiences, reduce duplicated development effort, and maintain definitions as requirements evolve. Start with a business question, establish what its terms mean, and validate the results. Then, extend that shared foundation to more questions and agents.

Resources

• OSI / Apache Ossie project — Open semantic metadata specification and conversion tooling.
• Tableau Semantics concepts — Models, dimensions, measures, and relationships.
• Semantic Query API overview — Querying a model through named fields and query context.
• Aggregation and totals — Aggregation behavior and relationship cardinality.
• Semantic authoring API entities — Metadata used to define Tableau Next SDMs.
• Business preferences best practices — Business context and guidance for analytical answers.
• Optimize and test a semantic model — Testing, calibration, and verified questions.
• Salesforce OSI converter — Setup and commands for converting OSI YAML into SDM JSON.
• OSI workflow — Conversion requirements and steps for importing semantic definitions.
• Tableau Next MCP reference — Connecting AI clients to Tableau Next analytics capabilities.
• Data 360 governance considerations — Support and considerations for governance tags and policies.

About the authors

Ravindra Varshney is a Senior Director, Software Engineering at Salesforce. You can find him on LinkedIn.

Gaurav Tewari is a Senior Product Manager at Salesforce. You can find him on LinkedIn.

Chandan Agarwal is a Principal Member of Technical Staff at Salesforce. You can find him on LinkedIn.

Special shoutout for their contribution to this post: Sonu Sharma is a Senior Director, Software Engineering at Salesforce. You can find him on LinkedIn 

The post Build Trusted Conversational Analytics with AIforce, Data 360, and Tableau Semantics appeared first on Salesforce Developers Blog.

TDX is Salesforce’s developer conference where thousands of builders come together to explore the latest innovations in enterprise AI and development.Presenting is a powerful way to share your technical expertise, build your personal brand, and position yourself as a leader in the Salesforce ecosystem. Help us co-create the TDX session experience by submitting your proposals for compelling, high-quality content that will inspire and teach others by showcasing your expertise through deep technical dives, real-world implementations, and innovative solutions.

Whether you are an experienced speaker or new to the stage, we invite you to share your unique perspective and contribute to the community’s collective knowledge. In this post, we’ll share tips on putting together a standout CFP for TDX 2027 to increase your chances of being selected. The submission deadline is November 16, 2026.

Session topics that resonate with the developer community

We’ve reviewed the highest-performing sessions from TDX 2026 to understand what resonated most with our developer community and the biggest takeaway is: developers want authentic, hands-on, code-first, AI-native content.

The most successful sessions went beyond high-level concepts and dove deep into the technical details. They showcased real-world implementations, explored architectural trade-offs, and shared practical insights from debugging and solving complex challenges.

When submitting a developer session, show us the code (Apex, LWC, Python, Agent Script, etc.), dive into the architecture, and highlight practical, innovative solutions that attendees can learn from and put into practice.

Choose your TDX 2027 session format

When submitting your proposal, you can choose from the following session formats:

• Theater Sessions (20 minutes): Fast-paced presentations in a high-energy, open theater space. Ideal for quick technical solutions, live demos, career lessons, or thought leadership. There’s no audience Q&A during the session, but speakers will have opportunities to engage with attendee questions in a separate space afterward. Maximum of two presenters
• Breakout Sessions (40 minutes): Held in dedicated rooms, these longer sessions are ideal for deep technical dives and in-depth explorations of architecture or governance topics. We recommend allocating 35 minutes for the presentation and reserving the final 5 minutes for live audience Q&A. Maximum of three presenters.
• Community Networking (45 minutes): Community-led networking and peer-learning sessions designed to foster meaningful connections and knowledge sharing. Through guided discussions, Trailblazers exchange ideas, tackle shared challenges, and learn from diverse perspectives across roles and career stages.

Note: You may share your preferred session format and length upon submitting, however, Salesforce reserves the right to incorporate more than one session proposal into a confirmed TDX 2027 session and change the session type/length.

How to craft a compelling submission

To maximize your chances of being selected for the TDX 2027 Developer Track, your proposal should clearly outline the technical lessons the audience will learn. Follow the below developer-focused best practices:

• Craft a memorable title. Start with a strong verb and explicitly name the product or technology your session will cover (e.g., Build with Salesforce’s New Dev Plugin for Claude Code, Scale API Governance with Lessons from Salesforce, Automate Search and Retrieval Deployments via DataKits). Be specific about what attendees will learn. 
  • Tip: Be careful with AI-generated titles and abstracts as they often feel overly generic and inauthentic, especially when combined with excessive em dashes.
• Write a clear, actionable abstract. Structure your abstract around three key questions: What technical challenge are you addressing? What specific solution will you demonstrate? What practical, actionable takeaways will attendees walk away with?
• Be agent-native. Show an agent doing real work or agent development best practices. Cover evals, traces, guardrails, costs, and what happened when things went wrong. 
• Bring in the new stuff. Audiences love it when you pair what’s new in the industry with what’s new at Salesforce. For example, show how you build an app in Claude using Salesforce Skills, or how an MCP-connected agent takes action on Salesforce data. 
• Focus on depth over breadth. Don’t try to cover the entire Salesforce Platform in 40 minutes. Pick a specific topic and go deep (e.g., utilizing parallel subscriptions for Agent actions or optimizing Data 360 queries).
• Share real-world experience. Features in Pilot and Beta are highly valued, as are innovative ways of using established technologies. 
• Use cross-cloud use cases. Showcase real-world solutions that span multiple Salesforce clouds and products, such as Salesforce Platform and Slack. Examples include: Integrate Slackbot with Agentforce via MCP and Automate Data 360 Pipelines via MuleSoft and Slack.
• Show something you built. Focus on a solution you’ve personally built, sharing real-world lessons, technical decisions, and honest trade-offs. Practical, experience-driven sessions resonate more than feature tours. For example: Observe Agent Behavior with Traces, Evals, and Alerts.
• Bring working proof. A repo, a skill, or an MCP tool that attendees can reuse makes your session more useful.

Best practices for your submission

Here are some best practices and guidelines for your TDX CFP proposal:

• Write a one-line title (within 60 characters) that clearly states the session outcome.
• Begin the abstract (within 120 characters) with a challenge, then state what attendees will learn.
• List three takeaways and name the products, APIs, or tools you will use.
• Add a short speaker bio with proof of experience, such as past talks, community work, or code.
• Submit more than one idea (maximum of three). Different angles raise your odds of being accepted.
• Ask for a peer review before you submit.

Common submission pitfalls to avoid

Based on what we’ve learned from past submissions, here are some things to avoid:

• Generic marketing topics, sales pitches, and roadmap talk. Keep sessions technical and focused on what developers can build today.
• Company or organization-specific product pitches. Showcase how you’ve used Salesforce technologies to build unique solutions and solve real-world challenges. Focus on the technical approach and practical takeaways, not just your employer’s story.
• Broad titles like “Intro to Agentforce”. Name the specific outcome, tool, or skill.
• Abstracts with no demo, code, or practical takeaways. Tell attendees what they will see, learn,  and be able to do afterward.
• Retired product names. Check the latest naming before you submit.

Access speaker support and resources

Once you submit your proposal, you’ll receive a confirmation email. All submissions will be reviewed after the CFP closes, and acceptance decisions will be communicated in December 2026.

If your proposal is accepted, you’ll become the content owner for your session and receive instructions for next steps. A Salesforce session owner will also be assigned to help you build your content and prepare for your TDX session(s).

If your proposal isn’t accepted, your submission will be kept on file for future event consideration. You can also explore opportunities to share your expertise at other Salesforce events, including Trailblazer Community conferences and Trailblazer Community group meetings.

Ready to submit your proposal?

Before submitting your session proposal, review the CFP FAQ and choose a preferred session format, prepare your title, abstract, three concrete takeaways, and a short speaker bio.

Submit your proposal here by November 16, 2026. We look forward to seeing the creativity and innovation you’ll bring to TDX 2027.

About the author

Akshata Sawant is a Lead Developer Advocate at Salesforce and co-author of a book titled “MuleSoft for Salesforce Developers,” published by Packt Publication. For a more in-depth look at Akshata’s accomplishments, visit her LinkedIn profile. 

Alba Rivas works as a Principal Developer Advocate at Salesforce. You can follow her on Linkedin.

The post The TDX 2027 Call for Participation Is Now Open appeared first on Salesforce Developers Blog.