As the Salesforce Developer Advocacy team lead, I recently posted on the future of the Salesforce Developer role. In that post, I argued that AI is reshaping our work around system design, quality engineering, and cross-system thinking. Headless 360 is the platform shift that turns those arguments into daily practice.

The platform provides context and capability

The LLM provides intelligence. The platform provides everything else: identity, access, capabilities, governance, and the context that makes intelligence useful. When an agent calls an MCP tool, it’s invoking accumulated state. Without it, the agent has nothing to reason over, no permissions to inherit, no business process to follow.

This was always true. Every customer record, every workflow, every approval chain, every permission boundary your org has accumulated – that’s not overhead. That’s the business itself, encoded in a system that enforces it.

That combination of intelligence from the model and everything else from the platform is what separates a prototype from a production system. It’s also what makes Headless 360 different from “just expose some APIs”.

Two kinds of MCP tools

When we talk about MCP tools in the Salesforce ecosystem, we mean two things:

• MCP tools for coding agents. These enable developers to connect Claude Code, Cursor, or any MCP-compatible coding agent to their org and read metadata, generate Apex, run tests, or deploy through the pipeline. The consumer is a developer building software.
• MCP tools for business agents. These enable users to access Salesforce capabilities from any MCP-compatible client: including Slack, ChatGPT, and Claude, among others. These MCP tools also allow agents to access Salesforce capabilities autonomously. The consumer is an agent serving an end user.

Both kinds of MCP tools share the same open surface and the same trust layer. The difference is who’s calling and why. Headless 360 covers both, and both have implications for the expertise you’ve built.

Headless 360 changes how the platform can be consumed. Coding agents can now reach into your org through MCP tools to build and deploy. Business agents can call the same platform to serve customers in Slack, ChatGPT, Claude, or any MCP-compatible client. The Salesforce browser-based UI is one surface among many..

How software is built, delivered, and used is changing all at once

Agentic AI is changing three things simultaneously.

How software is written. Agents are becoming the development team. The first draft of an Apex class, an LWC, a test suite, or an Agentforce agent arrives in seconds. Your job shifts from writing code to specifying intent, evaluating output, and deciding what fits your existing system design.

How quickly it is delivered. Implementations compress from months to days. When an agent can execute against a development org, with human review gates before anything reaches production, the bottleneck moves from execution to clarity of intent.

How it is used. Humans will use Salesforce from anywhere, not necessarily the Salesforce UI. A sales rep gets a customer summary in Slack. A support agent resolves a case in Teams. And increasingly, the consumer isn’t a human at all; it’s a business agent reasoning over your data. The destination isn’t a Lightning Experience tab. It’s wherever the work is already happening.

These three changes are happening simultaneously, and they put pressure on the platform itself. Headless 360 is the platform shift designed to address all three at once.

In addition to these three core dimensions, Headless 360 also changes how governance is enforced and how you think about channel strategy. When the UI is no longer the primary surface, you can’t rely on a mix of UI constraints and schema rules for governance; instead, full schema-level enforcement (via validation rules, your sharing model, and Apex) is required. And rather than building per-channel UIs (for Lightning, mobile, and community, for example), with Headless 360 you define a capability once and let it render wherever it’s called, including Slack, ChatGPT, mobile, or web.

What Headless 360 actually is

Headless 360 makes every major Salesforce capability openly composable by agents, not just by code paths a human developer wrote in advance. The full surface, including 60+ MCP tools, 30+ coding skills, 4,000+ existing APIs, and 220+ CLI commands, is accessible to any authenticated caller that your trust layer authorizes.

This isn’t new territory for Salesforce developers. You’ve been building headless for years. This includes Experience Cloud sites with React frontends, Node.js apps over REST APIs, and mobile apps via the Mobile SDK. What’s new is that AI models can now dynamically discover, use, and compose capabilities at runtime, without custom integration code written in advance for each one. 

When we say “openly composable by agents” the openly matters. Openness is the default posture. Governance is what makes it safe.

Headless 360 in practice

The capabilities Headless 360 unlocks aren’t abstract. Here’s what they look like in practice. 

Build with any coding agent

The 60+ MCP tools and 30+ preconfigured coding skills give any compatible coding agent live access to your org. Agentforce Vibes 2.0 brings that natively inside Salesforce, but the MCP surface is the same regardless of which agent you choose.

Here is a typical session: your coding agent connects to a scratch org via MCP, reads the object model, scaffolds an Apex service class with governor-limit-aware test coverage, and pushes it through your DevOps pipeline. Same deployment gates, same quality checks, same review process as code written by hand. The pipeline doesn’t care who initiated it. It cares whether the gates pass.

The platform doesn’t privilege one agent over another. Your org’s capabilities are the constant. The tooling around it is your choice. For more on the MCP tools and how they work, see our post Introducing MCP Support Across Salesforce.

Render in any UI framework

Headless decouples capability from rendering. In practice, this means the platform no longer constrains your UI framework. A clear example of this is multi-framework support.

With multi-framework support, React developers can now build on Salesforce using the same patterns they already know, with no requirement to use LWC. A front-end engineer who’s never touched Salesforce can build a governed, data-connected application using familiar tools, because the platform adapts to their stack.

That hiring constraint where you needed someone who knew LWC or Aura? It’s no longer a hard constraint. The platform meets developers where they already are.

Deploy on any surface

The Headless Experience Layer is a new runtime that decouples capability definitions from their rendering surface. You define a UI fragment and the Headless Experience Layer (HXL) handles rendering it as a Slack block, a mobile card, a ChatGPT response, or a voice interaction. Business logic, data, and permissions stay separated from the screen, so you define intent once and render natively everywhere, including Slack, mobile, ChatGPT, Claude, Teams, or any MCP-compatible client.

This is where the two MCP lanes start to converge. The same openness that lets a coding agent build against your org will also let a business agent serve your customers from it. Today, the build-time surface is mature. The runtime surface already supports straightforward use cases, such as a support agent pulling a case summary inside a Slack thread. The broader vision is that the same capability can be delivered across surfaces such as voice interactions or partner mobile apps, and that ultimately capabilities can be made available on any surface.

Protect with built-in governance

Headless doesn’t mean ungoverned. Governance is what makes it safe to build with any coding agent, render in any UI framework, and deploy on any surface. 

When a coding agent pushes an Apex class, it goes through the same validation, tests, and deployment gates as code written by a human. When an agent queries customer data through MCP, it hits the same sharing rules and field-level security as a user in Lightning.

Four things are enforced on every API call, every MCP tool invocation, and every CLI command:

• Identity. The agent acts as a specific user, not an anonymous caller. Permissions are scoped to that identity.
• Access. Sharing rules, field-level security, and permission sets enforce what the caller can see and do.
• Invocation scope. The agent can invoke only those tools and actions that have been explicitly exposed.
• Governance. Validation rules, triggers, approval chains, and governor limits all fire regardless of entry point.

The platform is open about what can be accessed. It is not open about who can access it, or how. That’s what makes it safe for openness to be the default posture.

Why most agentic prototypes don’t reach production

If you’ve tried to ship an agent, you’ve likely encountered this problem. The demo works. The stakeholder asks a question that breaks it. For example:

• “Will it respect the sharing rule on this object?”
• “What happens if the user doesn’t have permission to update that field?”
• “How does it know which approval policy applies?”

The LLM alone is not enough. The hard part is everything around it: business context, identity-aware permissions, policy enforcement, and the operational guarantees that make a system safe to run autonomously.

That gap is exactly what the Salesforce platform fills. The context an agent needs didn’t show up because someone wrote a clever prompt. It accumulated over years, in your data model, your validation rules, your sharing architecture, your trigger framework. Headless 360 makes that platform accessible to agents through a governed surface. You don’t rebuild context, permissions, or policy for your agents. They inherit it.

Testing is part of this too. Testing agents is different from testing deterministic code. You’re evaluating whether an agent’s reasoning led to an acceptable outcome across a distribution of inputs. Session tracing, custom scoring evals, and the Agentforce Testing Center are how you build confidence that an agent does the right thing in production. The discipline is familiar if you’ve built test suites for complex Apex, but the techniques are new.

What comes next

Headless 360 ships with MCP tools for coding and business agents, coding skills, multi-framework support, and the Experience Layer. That’s its surface. What makes it work is everything underneath: the state, the governance, the accumulated business logic of a platform you already know.

On the Salesforce Developer Blog and YouTube, we’re going deep on every building block, including skills for coding agents, multi-framework walkthroughs, trust and governance deep dives, testing and observability patterns, and more. Follow along and tell us where to go deeper.

The platform is open. Build on it.

Related Reading

• The Future of the Salesforce Developer in the Agentic AI Era
• Introducing Salesforce Headless 360
• Agentforce Vibes 2.0
• Headless Experience Layer
• Salesforce Multi-Framework
• Agentforce Labs
• Open Source Agentforce Skills

About the Author

Rene Winkelmeyer leads the Developer Advocacy team at Salesforce. His team focuses on Agentforce, Data 360, and the Salesforce Platform. In his spare time, you might find him still coding on GitHub. Follow Rene on LinkedIn.

The post What Salesforce Headless 360 Means For Developers appeared first on Salesforce Developers Blog.

Picture your customer rolling out a Flexcard for quick account overviews. It’s looking great on desktop, but on mobile? Actions don’t fire, data doesn’t render, and users bounce in frustration. These aren’t rare moments; they’re everyday headaches that slow deployments, breaking trust. End-to-end (E2E) testing fixes this mess by mimicking real journeys, so you can catch issues early and deploy with confidence.

Why E2E testing matters for Omnistudio

So, why do we need to test the entire journey rather than just checking if a button works? Testing the full user journey is critical because Omniscripts, Flexcards, and Data Mappers interact across boundaries where unit tests cannot validate the complete process. E2E testing plays out the full story of what a real user does, from start to finish across your components, like a demo of an actual customer journey. 

E2E testing also helps you:

• Simulate full user journeys across Omnistudio components: E2E testing plays out that whole flow, just like a real person clicking through components, spotting weird hiccups along the way.
• Catch integration issues early for partners building solutions: E2E grabs those sneaky spots where Data Mappers don’t feed data right into an Omniscript, saving you from frantic fixes right before demo day.
• Reduce post-go-live bugs: E2E irons out production surprises, reducing post-deployment defect tickets for your teams, giving you greater confidence in deployments.
• Validate real-world flows to record creation: Unit tests poke single buttons (like does this button click? Does that data pull?). E2E runs the full race, like submitting a lead form, watching it zip through conditions, and landing as a shiny new record in Salesforce.
• Find the real problem: When tests flake, E2E pinpoints the issue past the pretty interface and discovers whether or not the backend logic is actually the part causing the crash.
• Confirm that the handoff works: Picture Omniscript passing data to a Flexcard. E2E checks that the pass doesn’t drop, enabling easy jumps between your UI pieces.
• Manage your own path: Users don’t always go straight. E2E tests the sunny “submit and succeed” path plus detours like errors or save-for-later resumes, covering all those branching stories.

High risk components to test first

When figuring out where to focus your testing energy, it helps to know which parts of the system are most likely to break. Based on what teams see in the real world, here are the high-risk areas you need to watch.

Omniscripts account for approximately 50% of reported Omnistudio UI bugs, making them the highest-priority target for E2E testing. Because this is the layer the user interacts with directly and is also most visible, it typically receives the highest number of reported bugs. They juggle steps, conditions, inputs, and data swaps with Data Mappers all in one go. Mess up here, and your whole customer journey, like a service request form, grinds to a halt.

Next is Flexcards because these cards are used to display critical data and handle user actions, and any glitch here is immediately obvious to the user. 

Finally, we have Data Mappers. If mappings fail (say, wrong field names or null values), Omniscripts starve for information, also breaking Flexcards downstream.

Note: All data presented above is derived from internal testing.

Tools for Omnistudio test automation: UTAM, Playwright, and Selenium

Automation sounds cool, but here’s the headache: Omnistudio pieces shift a lot. You might spend days building a perfect test script, and it runs beautifully, until the next release drops. Suddenly, everything breaks. Why? The main culprit here is dynamic element IDs. Because Omniscripts and Flexcards are built on Lightning Web Components (LWC), they sit inside a Shadow DOM. So your usual CSS or XPath selectors become fragile and start failing whenever Salesforce moves with seasonal updates. It breaks everything at the backend. One day your test clicks Submit just fine, and the next, it hunts for a button that moves and your whole pipeline stalls.

To solve this problem, Salesforce created the UI test automation model (UTAM), a proprietary tool designed specifically for LWC in Omnistudio. Omnistudio components are wrapped in Shadow Roots (that’s the Shadow DOM), which blocks standard Selenium selectors like CSS or XPath from reaching elements reliably, especially after Salesforce updates.

<!-- Source: https://mvnrepository.com/artifact/com.salesforce.utam/salesforce-pageobjects -->
<dependency>
    <groupId>com.salesforce.utam</groupId>
    <artifactId>salesforce-pageobjects</artifactId>
    <version>12.0.0</version>
    <scope>compile</scope>
</dependency>

Instead of relying on brittle selectors in scripts, UTAM uses JSON-based page objects. When a button’s location or structure changes in an Omnistudio update, you just update the JSON metadata once, and all your tests are instantly back on track. It creates a stable layer and lets scripts identify UI components consistently, no matter what changes underneath.

Choosing between UTAM, Playwright, and Selenium

Instead of relying on fragile identifiers, a smart move would be to grab the right tools that don’t flake. Use a combination of industry-standard tools and Salesforce-specific frameworks. Here’s when to use what:

• UTAM: Best for long-term maintenance and Salesforce-native components, giving you those stable JSON selectors that survive Omnistudio updates.
• Playwright: Playwright is best for speed and headless CI/CD pipelines. Fire it up without a visible browser to debug fast across browsers. 
• Cucumber with Selenium: Cucumber with Selenium is best for business stakeholder sign-off (BDD). You write tests in plain English and your team reads and approves it.

Launch with tweaks like test parameters (sandbox mode? Slow it down?). Then poke issues using element properties. Is it visible? Enabled? That’s how you spot and squash the real culprits without endless rewrites.

Testing scenarios by Omnistudio component

Now that we’ve covered the hurdles, let’s get practical: what exact scenarios should you click, check, and validate in your Omnistudio flows? Since Omnistudio is made up of different building blocks, we need to look at them individually. Here are the recommended testing scenarios to keep your application running smoothly.

These are the must-hit spots to make sure everything hangs together for real users.

Omniscript testing

These are your flow bosses, so test the moves that users make every day.

• Check step transitions & logic: Don’t just check if the Next button works. You need to validate the conditional visibility. This is the if/else logic, if a user selects Option A, does the form show them the correct follow-up question? If they select Option B, does it take them down the alternative path?
  
  
• Validation rules: Try to break it. Enter the wrong date format or leave a required field blank. Does the system stop you with a helpful error message (validation failure), or does it let you proceed and crash later?
  
  
• Save and resume: This is a big one. For long applications, users might not finish in one sitting. You must test the “Save for Later” functionality to ensure that their data is actually saved and can be resumed exactly where they left off without data loss.
  
  
• The ID trap: When automating these tests, avoid using dynamic IDs generated by the browser as these change frequently. Instead, use data-testid or stable CSS selectors. This keeps your test from breaking every time Salesforce updates the platform.
  
  

Flexcard testing

If Omniscript is the form, the Flexcard is the dashboard that needs to look sharp and act right. It displays data and offers quick actions.

• Validate data rendering: First, perform simple visual checks. Is the data showing up? Whether it is static info or contextual data pulled from the system, it needs to render correctly on the screen.
  
  
• Action buttons: Flexcards aren’t just for looking, they have buttons. Test these actions specifically. Does clicking the button successfully launch the correct Omniscript or navigate the user to the right page?
  
  
• Conditional states: Just like Omniscripts, Flexcards can change based on data. Test these conditional states, such as hover effects or expanded details, to ensure that the card looks different when it is supposed to.
  
  
• Selectors: Stick to application programming interface (API) name–based selectors for your automation to keep things stable. They stay reliable when Salesforce tweaks the UI.

Data Mapper testing

Now we are moving backstage. Data Mappers are responsible for moving data in and out of Salesforce. Even if the UI looks fine, a broken Data Mapper means the process fails.

• Test separately: You don’t always need the UI to test these. Isolate them to see if they work on their own since they’re data pipes.
  
  
• Input and mappings: Check the input payload correctness. If you send data in, does it map to the correct fields in the database?
  
  
• Edge cases: What happens if a field is missing or comes through as null? You need to test these edge cases to make sure that the Data Mapper doesn’t just crash when the data isn’t perfect.
  
  

Integration Procedures (IPs) testing 

Omnistudio’s Integration Procedures is like an engine room that handles multiple steps and actions at once.

• Orchestration sequence: Verify that the sequence fires in the right order without skips. Does the Integration Procedure call the Data Mapper, then the external API, and then send the email?
  
  
• Error branching and timeouts: It’s critical to test system failures.” What happens if an external service takes too long to respond (timeout handling)? Does the IP handle the error gracefully, or does the whole screen freeze?
• Mock services: In your lower testing environments (like sandbox), use mock services to simulate external responses. This lets you test the logic without relying on (or waiting for) real-world third-party systems.

Pretesting checklist for Omnistudio 

Before you even write your first test script or click Run, there are some best practices that you should keep in mind. Testing isn’t just about finding bugs; it’s about making sure that the design actually works for the human using it.

Here is a checklist of what to consider before you start testing.

Verify backend object updates

Don’t get too distracted by the flashy buttons just yet. Start with the win you want. Your primary goal is to verify that the business actually got what it needed. We call this testing the “happy path,” the core journey where everything goes right.

Ask yourself: When the user hits Submit, did the data actually land where it was supposed to? You need to confirm that the backend S-objects or business objects were updated correctly. If the form looks great but the database is empty, the test has failed.

Test dynamic UI state changes

Omnistudio interfaces are dynamic. They change based on who is looking at them. For example, a Flexcard might display different contextual data depending on the customer.

Before testing, verify that the UI visibility logic is sound. Does the screen state change correctly when new info is added? Are buttons going gray when they’re not ready? You need to ensure that the interface is displaying the right information at the right time.

Validate responsive UX

Step back and think about the user: does the flow feel natural on a phone or desktop? Test responsive tweaks and little touches like smooth transitions — no janky jumps that make users ditch the app mid-task. The Omniscript is the “face” of your application, and because it is the part that users touch, it usually receives the highest number of bug reports.

However, remember that a bad UX isn’t always a code error, sometimes it’s just a confusing design. When planning your tests, think about the flow. Is it intuitive? Since the root cause of a UI bug is often actually a backend configuration issue, ensuring a smooth UX means making sure that the backend supports the frontend easily.

Test error messaging paths

What happens when things go wrong? Your testing plan needs to cover more than just success stories. You must account for “unhappy paths,” such as validation failures where a user enters the wrong data.

You also need to verify how the system handles big failures, like an Integration Procedure timeout or an Apex exception. Does the user get a helpful error message, or does the screen just freeze? Check that success pop-ups say things like “Claim submitted, thanks!” and errors spell out next steps, like “Missing phone number, add it here,” instead of vague tech jargon.

Accessibility verification

Don’t leave anyone behind — this is non-negotiable. When designing and testing Omniscripts, you must consider accessibility because the UI needs to work for everyone.

Your tests should ensure that the application caters to all customers, including those who may be visually impaired. Test for screen readers announcing fields correctly, keyboard-only navigation through your Flexcards, and color contrasts that pop for all eyes.

Conditional navigation outcomes

Finally, where does the user go next? Omnistudio relies heavily on conditional logic, basically if/else statements that send users down different paths based on their choices.

You need to verify these alternative paths. If a user clicks Save for Later, does the system actually let them resume later without losing data? If they answer Yes to a specific question, does the navigation direct them to the correct follow-up screen? Make sure that every road leads to the right destination.

Next steps

There you have it. Tackling Omnistudio testing in the simplest way possible without it being a nightmare of flaky scripts and hidden bugs. Start with your highest-traffic Omniscript. Write one UTAM page object for its first step, validate a single field input and step transition, and run it against your sandbox. Once that passes reliably across two Salesforce releases, expand coverage to the scenarios listed above. Build rock-solid flows with clear messaging and confident deployments that your customers love.

Resources

Video: FlexCards and OmniScripts | Salesforce Industries 

Trailhead: Omnistudio Development Essentials 

Trailhead: Omnistudio Omniscript Fundamentals

Video: Build Low-Code Digital Experiences with All-New OmniStudio  | TDX Bengaluru 

About the authors

Anjali Gupta is a Senior Product Manager at Salesforce who is specialised in horizontal cloud and platform. She is focused on Omnistudio roadmap and strategies ensuring customer growth and success. Follow her on LinkedIn.

Payal Verma is a Content Marketing Analyst at Salesforce with over four years of professional experience in product, brand, and content marketing. She has worked across both B2B and B2C markets, developing and executing content strategies for a wide range of formats, including blogs, social media, scripts, eBooks, and guides. Follow her on LinkedIn.

The post Conduct End-to-End Testing for Salesforce Omnistudio-based UIs appeared first on Salesforce Developers Blog.

Custom Lightning types (CLTs) meet this need. They let you render Lightning Web Components (LWC) directly within Agentforce experiences in Lightning Experience, Enhanced Chat v2, and Experience Builder. You can collect structured input through a custom form and display results as rich, styled cards or in your own custom-designed user interface. CLTs are also the foundation of Headless Experience Layer, announced at TDX 2026, which extends rich agentic UI beyond Salesforce — to Slack, ChatGPT, and more. Define Once, Deploy Anywhere, Secure Everywhere — that’s the headless experience layer vision. Building with CLTs today means you’re already working with the primitives that power the next generation of multi-surface agentic experiences.

This post walks through how to work with CLTs in Agent Script to render a rich experience within Agentforce. All code examples come from the Agent Script Custom Lightning Type example recipe.

What are custom Lightning types in Agentforce?

Custom Lightning types create a bridge between your Agent Script, your actions backed by Apex or flows, and your LWC components. They override the default text-based UI with custom LWC components for both input and output.

Below is an example of custom Lightning types in action within the Agentforce experience.

The connection flows through three layers:

• Agent Script declares which action parameters need custom UI
• A Lightning Type Bundle maps each parameter type to an Apex data shape and an LWC component
• An LWC renders the user interface inside the conversation

This three-layer wiring enables you to keep a clean separation of concerns. Your Agent Script handles orchestration, Apex handles the data shape definition and the business logic, and LWC handles the final user experience.

The following diagram shows how a custom Lightning type is mapped with Agent Script and LWCs.

The following sections describe how to build and wire this connection step-by-step.

Step 1: Prepare and deploy your Apex and LWC 

Defining the Apex data shape

Each CLT needs an Apex class that defines the data structure. Use inner classes within your service class, with each field annotated with @InvocableVariable. The Lightning Type Bundle references these inner classes as the schema source.

public class CaseInput {
    @InvocableVariable(label='Subject' required=true)
    public String subject;

    @InvocableVariable(label='Priority')
    public String priority;

    @InvocableVariable(label='Description')
    public String description;
}

One important detail: the wrapper class field names must exactly match the action parameter names from your Agent Script. If your action input is called case_data, the request wrapper field must also be named case_data. A mismatch here silently breaks the entire CLT connection.

View the code: See the full CaseSubmissionService.cls for the complete Apex implementation including the request/response wrappers.

Building the editor and renderer LWC

The editor LWC collects user input inside the chat. Two things make it work with Agentforce: the meta XML must target lightning__AgentforceInput with a targetType matching the CLT name, and the component must dispatch a valuechange event whenever the user modifies the form.

 <target>lightning__AgentforceInput</target>
 <targetType name="c__caseInput" />

The valuechange event payload field names must match the Apex CaseInput class fields. The platform listens for this event to capture and forward the form data to your Apex action.

Here is the simple example snippet showing the valuechange event in practice:

import { LightningElement } from 'lwc';

export default class CustomCaseForm extends LightningElement {
    // Local state variables for the form
    subject = '';
    priority = 'Medium';
    description = '';

    // Handler triggered when the user types in the Subject input
    handleSubjectChange(event) {
        // 1. Update the specific field that changed
        this.subject = event.target.value;

        // 2. Dispatch the FULL state of the form
        this.dispatchFormState();
    }

    // You would have similar handlers for Priority and Description...

    // Centralized method to dispatch the complete current state
    dispatchFormState() {
        this.dispatchEvent(
            new CustomEvent('valuechange', {
                detail: {
                    value: {
                        // ALWAYS include all fields to match the Apex CaseInput class
                        subject: this.subject,
                        priority: this.priority,
                        description: this.description
                    }
                }
            })
        );
    }
}

The renderer LWC displays the result card after the action completes. It targets lightning__AgentforceOutput with a sourceType (not targetType). The component receives the full result object via @api value and uses getters to render the fields with Salesforce Lightning Design System styling.

<target>lightning__AgentforceOutput</target>
<sourceType name="c__caseResult" />

View the code: See the full caseInputEditor and caseResultRenderer components in the repo.

Wiring Lightning type bundles

The Lightning Type Bundle is a folder containing JSON configuration files. The schema.json file points to your Apex inner class using $ syntax. For example, c__CaseSubmissionService$CaseInput references the CaseInput inner class.

{
    "title": "Case Input",
    "lightning:type": "@apexClassType/c__CaseSubmissionService$CaseInput"
}

A second file tells the platform which LWC component to render. Input types use an editor.json file. Output types use a renderer.json file. The "$" root key means “override the UI for the entire type”.

{
    "editor": {
        "componentOverrides": {
            "$": { "definition": "c/caseInput" }
        }
    }
}

View the code: See the complete Lightning Type Bundle files in the repository

Step 2: Create the agent action asset

The GenAiFunction is the metadata layer that registers your action with Agentforce. Without it, Agentforce cannot resolve your CLT bindings. Every CLT-based action needs a corresponding GenAiFunction in the genAiFunctions folder.

The function metadata XML points to your Apex invocable class:

<GenAiFunction xmlns="http://soap.sforce.com/2006/04/metadata">
    <developerName>Submit_Case</developerName>
    <invocationTarget>CaseSubmissionService</invocationTarget>
    <invocationTargetType>apex</invocationTargetType>
    <masterLabel>Submit Case</masterLabel>
</GenAiFunction>

Alongside this XML, you define input and output schema JSON files. These schemas declare the lightning:type for each parameter, which is how the platform knows to look up your Lightning Type Bundle.

The input schema marks case_data as a user input with the CLT type c__caseInput:

{
    "properties": {
        "case_data": {
            "lightning:type": "c__caseInput",
            "copilotAction:isUserInput": true
        }
    }
}

The output schema marks case_result as displayable with the CLT type c__caseResult:

{
    "properties": {
        "case_result": {
            "lightning:type": "c__caseResult",
            "copilotAction:isDisplayable": true
        }
    }
}

See the full GenAI Function files in the repository.

You can build the Agent action metadata directly in the Salesforce user interface. 

To do this, navigate from Setup to Agentforce Assets, then select Actions and create a new agent action by following below steps.

1. Setup → Agentforce Assets → Click on Actions → Click on New Agent Action
2. Fill in the agent action details like Inputs and Outputs description and data types.
3. Ensure you are setting up the Input Rendering and Output Rendering with the right custom Lightning types

Step 3: Define the action in Agent Script

While the following sections cover action definition via metadata in detail, the Agentforce Builder UI enforces proper naming constraints automatically and is the recommended starting point for most teams.

Everything hinges on the action definition in your Agent Script. Two properties control CLT rendering: complex_data_type_name links a parameter to a Lightning type, and is_user_input or is_displayable tells the platform to render the custom component.

actions:
   submit_case:
      inputs:
         case_data: object
            is_user_input: True
            complex_data_type_name: "c__caseInput"
      outputs:
         case_result: object
            complex_data_type_name: "c__caseResult"
            is_displayable: True
      target: "apex://CaseSubmissionService"
      source: "Submit_Case"

Notice the source property at the bottom. This is a critical piece that connects Agent Script to an Agentforce action (represented as GenAiFunction in the metadata as discussed in step 2). The value “Submit_Case" must match the developer name of a GenAiFunction metadata file in your project.

Triggering the CLT editor in Agent Script

One detail that is easy to miss: your Agent Script subagent instructions must include the user_input keyword when calling the action. This tells the platform to render the CLT editor component instead of collecting input through plain text.

reasoning:
   instructions: ->
      | Call {!@actions.submit_case} action's user_input tool to collect the case details.

Without this phrase, the platform falls back to text-based input collection. The user_input keyword is what activates the entire CLT editor rendering pipeline.

Important note: In Agent Script the subagent’s action name and the subagent reasoning action name should be exactly the same.

View the code: See the full instructions for the Agent Script in the repository.

The alignment checklist

CLTs require precise naming across multiple files. If any link in the chain breaks, the platform silently falls back to the default text UI with no error message. The following table shows what must stay aligned:

Check these connections first when debugging. The silent fallback behavior makes misalignment hard to spot.

Conclusion

Custom Lightning types bring the power of Lightning Web Components into Agentforce conversations. You can collect precise, validated data through custom forms and present results in rich, branded cards, all without leaving the Agentforce experience.

The key pieces are the Agent Script action definition and the action in the Agentforce assets, the Lightning Type Bundle, and the LWC components. Each layer has a specific job, and the naming alignment across all four layers is what makes the whole system work.

This pattern opens up new possibilities for building enterprise-grade agent experiences. Forms with dropdowns and validation, structured result cards with conditional styling, and multistep workflows can all be rendered inline within the conversation.

The complete working example is available in the Agent Script Recipes repository under the customLightningTypes recipe. Clone the repo, deploy to a scratch org or Developer Edition org, and start building your own CLT-powered Agentforce agents.

Resources

• Lightning Types Developer Guide
• Agent Script Recipes Sample App
• Agent Script Documentation

About the authors

Mohith Shrivastava is a Principal Developer Advocate at Salesforce with 15 years of experience building enterprise-scale products on the Agentforce 360 Platform. Mohith is currently among the lead contributors on Salesforce Stack Exchange, a developer forum where Salesforce Developers can ask questions and share knowledge. You can follow him on LinkedIn.

Parvinder Singh is a Senior Forward Deployed Engineer at Salesforce with deep expertise in Agentforce and Agent Script, specializing in building intelligent, customized agent experiences for enterprise customers. He is passionate about sharing developer insights with the community and bringing practical, field-tested patterns to life through hands-on content.

The post Use Custom Lightning Types in Agent Script for Rich Agent UI appeared first on Salesforce Developers Blog.

As a Salesforce developer, you know that a new building experience usually means changes under the hood. To support this faster, safer way of working, the underlying metadata had to evolve. This post walks through the new developer workflow, why the metadata changed, and how to structure your packages for deployment.

The new authoring workflow: from script to metadata

To understand the metadata changes, it helps to understand the new mental model for building agents. The new Agentforce Builder introduces a clear separation between your “intent” (what you want the agent to do) and the engine’s “execution” (the active metadata).

Here is how the lifecycle works:

1. Write and build: You author your agent using the Agentforce Builder UI or directly via an Agent Script. This human-readable script is saved as a single .agent file within a new AiAuthoringBundle metadata type, representing your agent’s configuration. At this stage, your work is a draft.
2. Iterate and preview: You test your draft using preview modes (like Simulation mode, which safely isolates your tests from org data).
3. Publish: When you are happy with the draft, you commit your version. This is the crucial moment. It is only during commit that the platform translates your .agent script into the active Bot and GenAiPlannerBundle metadata that is actually used to run your agent.

Why the metadata changed: bundling local assets

So, why did we change the GenAiPlannerBundle metadata structure for this new builder? The answer comes down to isolation and deployment reliability.

Historically, Agentforce assets were global. If you modified a shared subagent for one agent, you triggered a “global ripple” that instantly impacted every other agent using that subagent. To solve this, Salesforce introduced Local Assets (including local subagents and local actions), which clone a global asset and anchor it specifically to one agent version. Once local, you can edit it safely without breaking anything else.

While Local Assets have been available for a while, the GenAiPlannerBundle metadata needed to be updated to fully support them in CI/CD pipelines. Previously, agent metadata was distributed across metadata types. The main change in the new GenAiPlannerBundle is bundleization. In short, we restructured the metadata to ensure that all dependent agent assets related to any given version are deployed and available in one centralized folder structure. This prevents deployment errors and ensures your agent has everything it needs to function exactly as it did in preview.

Under the hood: the new metadata structure

Instead of scattered files, the directory structure now cleanly encapsulates everything specific to each agent version.

AiAuthoringBundles is a directory that contains all the design-time artifacts for the agent. The bundle supports multiple versioned subdirectories (e.g., AgentName_1, AgentName_2, etc.), each with its own .agent file and .bundle-meta.xml descriptor. These correspond to different lifecycle states such as draft and committed versions of the agent. Within each version:

• The .agent file holds the agent’s configuration written in Agent Script: name, label, description, system instructions, subagent definitions, reasoning instructions, variables, conditionals, and tool/action references.
• The metadata descriptor (.bundle-meta.xml) declares the bundleType (e.g., AGENT) and the target agent version it points to.

Bot contains information common to all versions of the agent, such as the agent type and useful settings like whether to log private data. It also holds agent-level context variables, which are distinct from the conversation variables that live inside each BotVersion. BotVersion details include conversation variables, welcome message, and transfer conversation message.

GenAiPlannerBundle contains all data relevant to each published version of an agent. Within each version you can find:

• .genAiPlannerBundle, which is the main metadata file containing the agent’s runtime configuration: subagents, instructions, actions, and orchestration logic.
• agentGraph, a .json file encoding all transitions and conditions between subagents.
• agentScript, an encoded copy of the version agent script. This is a snapshot kept for sync-detection purposes, so Agent Builder can tell the user if the script is out of sync with the published/committed metadata.
• plannerActions, agent-level actions (not tied to any specific subagent).
• localActions, subagent-scoped actions, nested under their subagent folder. The input/schema.json and output/schema.json files define the typed parameters for each action.

Note: GenAiPlannerBundle versions are auto-incremented in commit order, so they won’t necessarily match AiAuthoringBundle version numbers.

Remember that both Bot and GenAiPlannerBundle metadata are created automatically when a version is committed, and AiAuthoringBundle, agentScript, and agentGraph are only present on the new Agentforce Builder agent metadata.

Example: GenAiPlannerBundle XML

When you look at the XML, you’ll see it now clearly reflects these localized subagents and actions:

<GenAiPlannerBundle>
   <description>New agent description</description>
   <localTopicLinks>
       <genAiPluginName>Retrieve_data_from_the_Knowledge_Base_16jxx0000001234</genAiPluginName>
   </localTopicLinks>
   <localTopics>
       <fullName>Retrieve_data_from_the_Knowledge_Base_16jxx0000001234</fullName>
       <description>Use the retriever action</description>
       <pluginType>Topic</pluginType>
       <masterLabel>Retrieve data from Knowledge Base</masterLabel>
       <genAiPluginInstructions>
           <description>You are an AI Agent.</description>
           <sortOrder>1</sortOrder>
       </genAiPluginInstructions>
       <localActionLinks>
            <functionName>File_test_retriever_179xx0000001234</functionName>
       </localActionLinks>
       <localActions>
           <fullName>File_test_retriever_179xx0000001234</fullName>
           <invocationTarget>File_test_retriever_1234</invocationTarget>
           <invocationTargetType>apex:testRetriever</invocationTargetType>
           <source>File_test_retriever</source>
       </localActions>
   </localTopics>
   <plannerType>AiCopilot__ReAct</plannerType>
</GenAiPlannerBundle>

Each <localTopics> block defines a subagent’s full configuration: its unique API name, description, plugin type, deterministically ordered instructions, and all the local actions available to it. Optionally, a reference to the source subagent may also be present.

Each <localActions> block defines the action’s name, master label, invocation target and type, and optionally a source reference to the global action it was cloned from. Additional UX-related settings, such as confirmation behavior and loading text configuration, may also be included.

Sample package.xml with metadata of new model

To successfully retrieve and deploy your agents built with the new Agentforce Builder, ensure your package.xml includes the new bundle types. Below is a sample manifest designed for the Spring ’26 metadata structure.

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>*</members>
        <name>GenAiFunction</name>
    </types>
    <types>
        <members>*</members>
        <name>Bot</name>
    </types>
    <types>
        <members>*</members>
        <name>GenAiPlannerBundle</name>
    </types>
    <types>
        <members>*</members>
        <name>GenAiPlugin</name>
    </types>
    <types>
        <members>*</members>
        <name>AiAuthoringBundle</name>
    </types>
    <version>66.0</version>
</Package>

Note: This manifest uses API version 66.0, which is required to support GenAiPlannerBundle and the new agent metadata types in this example.

Developer tips for the new Agentforce Builder

Here are two ways to take advantage of development lifecycle improvements enabled by this new architecture:

• Use human-readable script files to streamline code reviews. In the legacy Agentforce Builder world, reviewing agent changes meant comparing complex, scattered XML files in your pull requests. Now, you can compare the human-readable .agent script files. This makes peer reviews significantly faster and easier to understand.
• Use AiAuthoringBundle to simplify CI/CD. For most pipelines, you can keep just the AiAuthoringBundle in your source control. When you need the agent in a new org, you deploy it, version commit to generate the runtime metadata, and finally activate it. This can be done automatically using the following commands:sf project deploy start --metadata AiAuthoringBundle --target-org my-orgsf agent publish authoring-bundle --api-name MyAuthoringBundle --target-org my-org

sf agent activate --api-name MyAuthoringBundle --version 2 --target-org my-orgIf your team wants a fully automated pipeline with no manual steps, you can maintain both AiAuthoringBundle and GenAiPlannerBundle in your source control and deploy them simultaneously, achieving a committed state. The system recognizes the incoming script alongside its pre-realized metadata and skips the manual commit step entirely, so your agent is live immediately after deployment.sf project deploy start --metadata AiAuthoringBundle,GenAiPlannerBundle --target-org my-org

Conclusion

The bundleized metadata structure is what makes the isolated, version-safe authoring possible in the new Agentforce Builder. With it, your metadata is cleaner, your code reviews are easier, and your deployments are more reliable. 

Get started with Agent Script and the new Agentforce Builder by completing this Trailhead module, reading more on our blog, watching our Agent Script decoded playlist on YouTube, or registering for one of the upcoming Agentforce Builder workshops.

Resources

• Release Notes:
  • Versioning and Editing Agents
  • Test and Customize your Agents with Improved Agent Versions
• Help Docs:
  • Editing Standard Agent Action Reference Actions 
• Packaging:
  • Package Agentforce Metadata Components
  • Develop and Package Agent Templates Using Scratch Orgs 
• Metadata updates:
  • GenAiPlannerBundle
  • GenAiFunction
  • GenAiPlugin
  • GenAiPluginInstructionDef

Shreyas is a Lead Software Engineer at Salesforce AI in San Francisco and a Fellow of the Institute of Analytics (FIoA). As a lead member of the Agentforce Core Platform team, he co-designed and led the Agentforce Versioning System and Local Assets Configuration changes to bring enterprise-grade ALM to Agentforce. You can follow him on Linkedin.

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

The post The New Agentforce Metadata and Development Lifecycle appeared first on Salesforce Developers Blog.

Headless 360 and Salesforce Hosted MCP Servers introduce a shift from UI-first to agent-first. Every capability on the platform — data access, business logic, automation — becomes consumable through CLIs, APIs, and the Model Context Protocol (MCP), an open standard that lets AI agents discover and call tools hosted on external servers. AI agents running in Slack, Claude, ChatGPT, Cursor, or any MCP-compatible client can now reach into Salesforce and invoke your business logic directly. No login screen. No navigation. No UI at all.

In this blog post, we’ll show you how to write custom Apex business logic, expose it as a Hosted MCP Server on Salesforce, deploy the necessary metadata to configure authentication, and connect an external AI agent like Claude to invoke your logic.

What makes Salesforce Hosted MCP different

A Salesforce Hosted MCP Server is a platform-managed endpoint that exposes Apex actions, Apex REST, and external APIs as discoverable tools for AI agents through the Model Context Protocol. Unlike self-hosted MCP servers, it runs on Salesforce infrastructure handling authentication, tool discovery, and request routing without external deployment.

A Salesforce Hosted MCP tool delivers three things that no raw database can match out-of-the-box: 

• Pre-built business object graphs (e.g., Account → Opportunity → Product → Revenue) with relationships already modeled 
• A record-level sharing model that automatically scopes results to what this specific caller is allowed to see 
• Decades of accumulated business process metadata that each customer’s org has already encoded over years of operation

Example: Pipeline intelligence

The example exposes a pipeline intelligence tool built in Apex. An AI agent passes an account name, and the tool returns a complete analysis: open deals with risk levels, weighted pipeline value, product line items, and an overall health assessment.

The Apex @InvocableMethod (see docs) that powers flows and Agentforce actions now also serves external AI agents through MCP. Write the logic once; it runs everywhere.

The Apex class uses global access (required for MCP tool discovery) and structures the method as a deep module, absorbing interpretive logic so that the Agent receives insight, not raw data.

The method starts by resolving the account using fuzzy matching: trying an exact name match first, then falling back to a LIKE pattern.

global with sharing class AccountPipelineService {
    @InvocableMethod(
        label='Get Account Pipeline'
        description='Returns open opportunities with line items and computed business intelligence (risk levels, weighted pipeline, health summary) for a given account name. Supports fuzzy matching.'
    )
global static List getAccountPipeline(List requests) {
  // All private methods is invoked here..
}
private static Account resolveAccount(String accountName, PipelineResult result) {
     List accounts = [
         SELECT Id, Name, Industry, AnnualRevenue
         FROM Account
         WHERE Name = :accountName
         WITH USER_MODE
         LIMIT 1
     ];

     if (!accounts.isEmpty()) {
         result.matchType = 'exact';
         return accounts[0];
     }

     String fuzzyPattern = '%' + accountName + '%';
     accounts = [
         SELECT Id, Name, Industry, AnnualRevenue
         FROM Account
         WHERE Name LIKE :fuzzyPattern
         WITH USER_MODE
         LIMIT 1
     ];

     if (!accounts.isEmpty()) {
         result.matchType = 'partial';
         return accounts[0];
     }

     result.accountFound = false;
     result.message = 'No account found matching: ' + accountName;
     return null;
 }

}

When no account matches, the tool returns a structured response with accountFound: false and a descriptive message, giving the AI agent a clear signal to ask the user for clarification rather than failing silently.

Once the account is resolved, a single SOQL query traverses the full business object graph.

List opportunities = [
     SELECT Id, Name, Amount, StageName, Probability, CloseDate,
         Owner.Name,
         (SELECT Id, Product2.Name, Quantity, UnitPrice, TotalPrice
          FROM OpportunityLineItems)
     FROM Opportunity
     WHERE AccountId = :acc.Id
         AND IsClosed = false
     WITH USER_MODE
     ORDER BY Amount DESC NULLS LAST
 ];

Each deal is then scored for risk based on probability and proximity to close date.

private static String assessRisk(Decimal probability, Integer daysUntilClose) {
     if (daysUntilClose <= 30 && (probability == null || probability < 60)) {
         return 'High';
     }
     if (probability == null || probability < 50) {
         return 'Medium';
     }
     return 'Low';
 }

The overall pipeline health is a multi-factor assessment combining high-risk ratio and weighted conversion strength.

private static String assessPipelineHealth(
     Integer totalDeals, Integer highRiskCount,
     Decimal weightedValue, Decimal totalValue
 ) {
     if (totalDeals == 0) {
         return 'Empty — no open deals';
     }
     Decimal highRiskRatio = (Decimal) highRiskCount / totalDeals;
     Decimal conversionStrength = totalValue > 0 ? weightedValue / totalValue : 0;

     if (highRiskRatio > 0.5) {
         return 'Weak — majority of deals are high risk';
     }
     if (conversionStrength < 0.4) {
         return 'At Risk — low weighted conversion across pipeline';
     }
     if (highRiskRatio <= 0.2 && conversionStrength >= 0.6) {
         return 'Strong — high confidence, low risk';
     }
     return 'Moderate — mixed signals, review recommended';
 }

Key design decisions:

• Fuzzy matching: The tool resolves partial account names (“Acme” finds “Acme Corporation”), reducing errors for AI agents that may not know exact names.
• Computed fields: riskLevel, weightedPipelineValue, and pipelineHealthSummary are calculated inside the method. The AI agent never needs to interpret raw probabilities or close dates.
• WITH USER_MODE: SOQL queries enforce the running user’s field-level and object-level security automatically.
• Cross-object traversal: This is a single tool call that spans Account, Opportunity, OpportunityLineItem, Product2, and User.

Registering the Hosted MCP Server

With the Apex class deployed, the next step is the MCP Server Definition, the metadata that maps your Apex action to a named tool and controls how AI agents discover it.

Below is an example deployable metadata for registering the hosted MCP server. The metadata can be source controlled and CI/CD deployed alongside the Apex class.

<?xml version="1.0" encoding="UTF-8"?>
<McpServerDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>Analyzes account pipeline health with deal risk scoring
    and weighted forecasts by traversing Salesforce's native business
    object graph.</description>
    <masterLabel>Pipeline Intelligence</masterLabel>
    <tools>
        <apiDefinition>
            <apiIdentifier>aa:apex-AccountPipelineService</apiIdentifier>
            <apiSource>API_CATALOG</apiSource>
            <operation>AccountPipelineService</operation>
        </apiDefinition>
        <descriptionOverride>Returns open opportunities with line items
        and computed business intelligence (risk levels, weighted pipeline,
        health summary) for a given account name.
        Supports fuzzy matching.</descriptionOverride>
        <toolName>getAccountPipeline</toolName>
        <toolTitle>Get Account Pipeline</toolTitle>
    </tools>
</McpServerDefinition>

Note: MCP Registration can also be done via Salesforce User Interface. The steps are documented in the official documentation.

Why every field here matters

AI agents don’t read your code. When an MCP client calls tools/list, the agent sees exactly four things per tool: a name, a description, an inputSchema, and an outputSchema. That’s the entire basis for deciding whether to call your tool, what to pass, and how to interpret the response.

Each metadata field controls part of that picture.

From Apex annotations to agent-readable schemas

The apiDefinition is the bridge. It references the API Catalog entry auto-created from your global class. Salesforce reads the @InvocableVariable annotations on your input and output classes and generates the inputSchema and outputSchema that agents see.

// Input class → becomes inputSchema (wrapped in an inputs[] array)
 @InvocableVariable(required=true description='The name of the Account to look up pipeline for. Supports partial matching.')
 global String accountName;

 // Output class → becomes outputSchema (nested inside a response envelope as outputValues)
 @InvocableVariable(description='Overall pipeline health: Strong, Moderate, At Risk, or Weak')
 global String pipelineHealthSummary;

 @InvocableVariable(description='Pipeline value weighted by probability — realistic expected revenue')
 global Decimal weightedPipelineValue;

The description text you write in each @InvocableVariable annotation becomes the documentation that the agent reads. Without it, the agent sees field types but not meaning. Write them with the agent as your audience for example:

• Input fields: What to provide. “Supports partial matching” tells the agent it doesn’t need an exact name.
• Output fields: How to interpret. “Negative means overdue” on daysUntilClose prevents misreading.
• Enumerated values: List them. “Strong, Moderate, At Risk, or Weak” — no guessing.

Writing an effective descriptionOverride

The descriptionOverride drives tool selection for the Agent. A good description answers three questions:

1. What does it return?  “Returns open opportunities with line items and computed business intelligence (risk levels, weighted pipeline, health summary)”
2. What input does it need?  “For a given account name”
3. Any behavioral nuances?  “Supports fuzzy matching”

Anti-patterns to avoid:

1. Too vague: A description like “Gets pipeline data” gives the agent no signal about what makes this tool different from a generic query tool. The agent is unlikely to select it when multiple tools are available
2. Too implementation-focused: A description like “Executes SOQL against Opportunity with USER_MODE” tells the agent how the tool is built rather than what it delivers. The agent needs to know what business value the tool provides, not the internal mechanics.
3. Missing input guidance: If the description does not mention that the tool expects an account name, the agent has no way to know whether it should pass an account ID, an opportunity name, or something else entirely.

Activate the MCP Servers

After deploying, verify the server appears in Setup → MCP Servers and activate it. The server must be active before any MCP client can connect.

Setting up the External Client App

For an MCP client like Claude to authenticate, an External Client App with OAuth is required. This is configured through Setup as follows:

1. Navigate to Setup → External Client App Manager → New External Client App
2. Provide a label, description, and contact email
3. Enable OAuth with the following settings:

Once saved, the Consumer Key becomes available under Settings → Consumer Key and Secret. This is the client identifier that Claude uses to initiate the OAuth flow.

Note: External Client Apps can take up to 30 minutes to become fully active after creation. If Claude’s connection fails immediately after setup, wait and retry.

Connecting Claude

Connecting Claude to a Hosted MCP Server requires a server URL and an OAuth Client ID — nothing else.

1. In Claude.ai on the web, navigate to Settings → Connectors → Add custom connector.Note this assumes you have a Claude account and you are signed in. If you are signed in you can also directly add a connector.
2. Copy the Server URL from Salesforce Setup:

• Navigate to Setup → Integrations → MCP Servers
• Click the MCP Server name (e.g., “Pipeline Intelligence”)
• Under Authentication Details, copy the Server URL

The URL follows the pattern below:

For this project, the URL is https://api.salesforce.com/platform/mcp/v1/sandbox/Pipeline_Intelligence

Note: You can also copy this from the user interface by navigating to the following: 

1. Set the Server URL in Claude by pasting the URL from Step 2
2. Paste the OAuth Consumer Key from the External Client App settings
3. Click Connect and authenticate with the Salesforce org credentials

Once connected, Claude can invoke the tool naturally:

“What’s happening with Acme’s pipeline?”

The response includes the matched account, open deals with per-deal risk levels, weighted pipeline value, product line items, and an overall health assessment — all computed by the Apex running on Salesforce, all respecting the user’s security context.

Note: If you are having issues connecting to MCP servers refer to the troubleshooting section in the official docs.

The Headless 360 shift

For Apex developers, Headless 360 is a fundamental shift in how you design code. The consumer is no longer a human clicking through a UI; it’s an AI agent that reads tool descriptions, passes structured inputs, and reasons over structured outputs.

Designing for agents means returning computed insight (not raw fields), writing precise descriptions (not UI labels), and building tools that are self-contained (not steps in a wizard).

For AI developers exploring MCP, Salesforce is a uniquely deep server: a pre-modeled business graph, governed security, and computed intelligence — not just another database behind an API.

A note on tool governance

Too many MCP tools overwhelm AI agents, they struggle to pick the right one, leading to irrelevant calls or confused responses. As more teams expose Apex logic as MCP tools, governance becomes important. The Salesforce Hosted MCP Servers Best Practices guide recommends keeping tools self-contained (each returns a useful result on its own), avoiding both over-granular tools that require prescribed sequences and over-broad tools that bundle unrelated operations. Give each tool

Get started

The complete source code for this blog post, setup scripts, and sample data are available on GitHub: headless-apex-mcp-tool. 

While this post demonstrates the connection with Claude, MCP is an open protocol. Any MCP-compatible agent — Slack, ChatGPT, or your own custom agent — can connect to the same Hosted MCP Server using the same URL and OAuth flow. Check the resources below to learn more.

Resources

• Connect MCP Clients
• External Client App Setup for MCP
• Connecting Claude to Salesforce MCP
• Hosted MCP Servers Developer Guide
• GitHub: Headless Apex MCP Tool

About the author

Mohith Shrivastava is a Principal Developer Advocate at Salesforce with 15 years of experience building enterprise-scale products on the Agentforce 360 Platform. Mohith is currently among the lead contributors on Salesforce Stack Exchange, a developer forum where Salesforce Developers can ask questions and share knowledge. You can follow him on LinkedIn.

The post Expose Custom Apex as a Hosted MCP Tool for Agents appeared first on Salesforce Developers Blog.

I built AgentLens when I was writing Agent Script recipes, the declarative definitions that control how Agentforce route, respond, and invoke tools. I needed a way to quickly debug what my agents were doing during execution in order to build a clear mental model of their orchestration. Whether I was reviewing agent behavior, or instructing a coding agent like Agentforce Vibes or Claude Code to modify Agent Script, I needed to understand the flow. Which subagents talked to each other? What does the state machine look like inside each one of these subagents? Where do handoffs happen, and why?.

Agentforce already provides a powerful agent platform tracing capabilities. Every execution is captured — subagent routing, LLM calls, tool invocations, variable mutations, all of it. That trace data is rich and complete, but what was missing for me was a fast, intuitive way to visualize it. I wanted a tool that would allow me to build a mental model in minutes, so I could describe orchestration clearly to a coding agent, judge whether its output was correct, or spot patterns in how my Agentforce agents behave.

That’s why I built AgentLens.

How Agentforce orchestration works (and why it matters for debugging)

Before diving into the tool, it helps to understand the two core structures that define how an Agentforce agent executes.

An Agentforce agent is composed of subagents, and each is responsible for a specific capability, such as order lookup, case routing, or knowledge retrieval for an order management agent. When a user sends a message, the orchestrator decides which subagent should handle the request and hands off the conversation. That subagent may invoke another in turn. The result is a directed acyclic graph (DAG), a network of subagents connected by handoff edges, where each edge represents one subagent passing control to another. Understanding this DAG tells you which subagent participated in a conversation and in what order.

Inside each subagent, execution follows a finite-state machine (FSM), a sequence of states connected by transitions. The subagent moves from state to state; it might start by calling the LLM, transition to a tool execution based on the LLM’s decision, then transition to a response or hand off to another subagent. Each state has defined transitions that determine what happens next. Understanding the FSM helps you see not just what a subagent did, but how it made decisions at each step: which tools it invoked, why transitions occurred, and where execution paths diverged.

When you’re debugging an Agentforce agent — or prompting a coding agent to fix one — you’re ultimately trying to answer two questions: 

1. “Did the right subagents get involved, in the right order?” (the DAG) 
2. “Did each subagent behave correctly internally?” (the FSM) 

The first tells you how the orchestration flowed across the system. The second tells you how decisions were made within each subagent. AgentLens makes both visible.

Visualize agent orchestration at three levels

AgentLens takes a single Agentforce trace JSON file and presents three connected views, each one level deeper than the last.

Agent Graph (the DAG): See which subagents communicated and in what order. Each node is a subagent, and each edge is a handoff. The graph shows you the full routing path that the conversation took, making it easy to spot unexpected routing, circular handoffs, or subagents that never got invoked when they should have been.

Finite-State Machine Diagram: Pick any subagent and see its internal execution as an interactive FSM. Nodes are color-coded: blue for LLM calls, teal for tool executions, green for responses. Each arrow is a state transition. Backward arrows reveal retries and loops — places where the subagent repeated a step, usually because a tool returned unexpected results or the LLM needed another pass. This is what tells you how a subagent made its decisions, and it’s what you describe to a coding agent when you want it to change the behavior.

In one of my recipes, the FSM showed the Routing subagent handing off to Fulfillment four times in a loop. The backward arrow made the pattern obvious: the handoff condition was matching too broadly. I described the FSM to Agentforce Vibes, and it tightened the guard clause in seconds.

Step-by-Step Trace Inspector: Walk through every agent execution event in sequence: the exact system prompt the model received, what it responded to, tool inputs and outputs, and variable diffs showing what changed. Use the arrow keys to navigate and handoffs automatically jump to the next agent, so you never lose the thread.

Filter controls let you toggle the visibility of variable updates, reasoning steps, enabled tools, and internal system variables. Show only what matters for the question you’re asking.

Debug Agent Script in VS Code or your browser

Analyzing Agentforce execution traces is the best way to understand its internal decision-making process. Let’s look at how you can easily visualize and debug these traces with AgentLens.

VS Code Extension: Search for AgentLens Visualizer in the Extensions panel or install it from the VS Code Marketplace. Once installed, right-click any trace JSON and select Open with AgentLens. You can still search for AgentLens Visualizer in Cursor or other IDEs, since the extension is available on the Open VSX Registry.

If your traces live at .sfdx/agents/**/traces/*.json (the default location used by the Salesforce CLI), the extension automatically adds an inline Open in AgentLens CodeLens at the top of the file. AgentLens also integrates with your VS Code theme, with support for light, dark, and high-contrast modes.

Web App: Head to msrivastav13.github.io/AgentLens, paste or upload a trace, and you’ll immediately see the agent graph — no install needed. 

For full offline use, download the index.html from the GitHub repo, open it in your browser, and paste the trace JSON from Agentforce Builder. Everything runs locally on your machine, and no trace data leaves your environment.

Where do Agentforce traces come from?

You can export traces from several places in the Agentforce ecosystem:

• SF CLI: Run sf agent preview -o <org>. Traces save to .sfdx/agents/ in your project.
• Agentforce DX Extension: Copy the plan response JSON directly from the trace viewer.
• Agentforce Builder: Run a conversation in the preview panel, then copy the trace JSON from conversation details.

The screenshot below shows how to copy trace JSON from the Agentforce Builder trace panel.

Once you’ve copied the trace, simply paste it into the AgentLens user interface to visualize the agent graph and step through the execution trace interactively. The screenshot below shows how AgentLens transforms the raw JSON copied from Agentforce Builder into an interactive debugging experience.

Development versus production: Pick the right tool

AgentLens is designed for the development loop, when you’re iterating on Agent Script, testing behavior in preview, and refining how your agent orchestrates. It helps you understand what happened in a test run, so you can make the next change with confidence.

For production observability, monitoring live agent conversations, tracking performance, and diagnosing issues in deployed agents, use Agent Platform Tracing. That’s the built-in platform capability for tracing agent execution at scale in your org.

A useful way to think about it:

• AgentLens is the workbench microscope you use while building
• Agent Platform Tracing is the production dashboard you use after shipping

Get started with AgentLens

AgentLens is open source and MIT licensed on GitHub. Try it on your own Agentforce agent traces, and if there’s a visualization that would help you debug faster, or a feature you’d like to see added, open an issue.

I built AgentLens because feedback loops matter. Whether you’re debugging Agentforce agents yourself or prompting a coding agent to do it for you, having a clear mental model changes how effectively you work. You write better prompts, catch orchestration issues faster, and gain a deeper understanding of how your agents actually behave.

Resources

• AgentLens web app
• AgentLens VSCode extension
• AgentLens open source repository
• Agent Script Recipes sample app

About the author

Mohith Shrivastava is a Principal Developer Advocate at Salesforce with 15 years of experience building enterprise-scale products on the Agentforce 360 Platform. Mohith is currently among the lead contributors on Salesforce Stack Exchange, a developer forum where Salesforce Developers can ask questions and share knowledge. You can follow him on LinkedIn.

The post AgentLens: Debug Agentforce with Interactive Visualizations appeared first on Salesforce Developers Blog.

By leveraging RAG-based semantic retrieval, Abilities solves the growing tool selection problem by identifying the most relevant Salesforce DX MCP Server tools for every request. This approach keeps your execution environment focused while improving output quality and reducing token usage. 

In this post, we’ll examine the challenges of tool explosion, define how Abilities function, and dive into the mechanics of semantic retrieval and tool dependency expansion.

The problem: Tool explosion and manual configuration

In Agentforce Vibes, context is everything. As the Salesforce Platform grows, the number of MCP (Model Context Protocol) servers grows with it, and today, there are more than 80 Salesforce DX MCP Server tools available from within Agentforce Vibes, including task-based tools that handle CLI commands, testing, code analysis, accessibility checks, DevOps operations, mobile, and more.

Turning them all on at once creates problems: the prompt becomes larger, the model has too many choices, output quality drops, and token costs rise. But the opposite problem exists as well. If too few tools are available, Agentforce Vibes may not have the capabilities it needs to generate metadata, create Apex code, refactor LWCs, or successfully analyze code for security violations.

As the catalog of Salesforce DX MCP Server tools expands, several new challenges arise:

• Default limitations: Given the sheer number of possible tools, we’ve only enabled a limited subset by default. This is due to concerns that activating too many tools might degrade the user experience or overwhelm the model.
• User experience impact: This often leads to sub-optimal code generation where the code may fail to compile, fail deployment, or ignore Salesforce development conventions.
• Manual configuration barriers: Developers can customize available tools, but doing so requires manual editing of the local mcp_config.json file and specific knowledge of internal MCP server tool names. Consequently, most developers never make these changes and rely entirely on the default toolset, even when additional tools would improve outcomes.

We needed a way to give Agentforce Vibes exactly the tools it needs, exactly when it needs them.

The solution: Intelligent context activation with Abilities

Abilities are domain capabilities that define what Agentforce Vibes can do in a given development scenario. There is no manual configuration and no switching between development modes. The system responds directly to the developer’s intent. This keeps the execution environment small and focused while ensuring that Agentforce Vibes has the capabilities required to complete the development task.

Examples include capabilities for:

• Apex, LWC development
• DevOps operations
• Mobile development
• Core platform administration

Each Ability bundles together the DX MCP Server tools associated with that capability.

When a request arrives, Agentforce Vibes evaluates the developer’s prompt and determines which capabilities should be active for the task and exposes only the tools associated with those capabilities. This process is managed by an internal orchestration layer called the Ability Coordinator, which interprets the request and prepares the execution environment before the model is invoked. This happens automatically for every task and requires no configuration from the developer.

Abilities are composable and a request may activate more than one capability. In practical terms, Abilities answer one question: What tools should Agentforce Vibes have access to right now?

How Skills and Abilities work together

Abilities and Skills serve different but complementary roles. Abilities handle context activation; they detect what you’re trying to do and automatically select the right Salesforce DX MCP tools for the task. This improves model focus and keeps output aligned with Salesforce best practices.

Skills are reusable, task-level playbooks. They define how specific work gets done (e.g., refactoring a trigger, generating tests, running a deployment), so you don’t restate instructions every time.

Abilities determine what tools are available. Skills define how the work gets done. Together, they let Vibes intelligently configure itself per task while keeping the developer in control.

What drives Abilities

Abilities use retrieval-augmented generation (RAG) to select tools. Instead of sending the full catalog of available tools to the model, Abilities retrieve the most relevant tools using semantic search. This allows the system to scale as the tool catalog grows while keeping prompts small.

How semantic retrieval works

To ensure that Agentforce Vibes selects the right tools without overwhelming the model, we use a RAG-based retrieval process. This happens in three phases: indexing the tools, matching them to your prompt, and then injecting the tools into the model’s execution context.

Phase 1: Tool embedding and indexing

Before any user interaction occurs, we prepare the tool catalog for retrieval. The following process runs whenever the MCP tool catalog is updated:

• Vector conversion: Each tool definition, including its name, description, parameters, and intended usage context, is normalized and converted into a vector embedding.
• Storage: These embeddings are stored in a vector database. This allows the system to identify tools based on their “meaning” and function rather than just matching keywords.

Phase 2: Prompt-to-tool matching (retrieval)

When you submit a prompt, Agentforce Vibes performs a real-time similarity search:

• Prompt embedding: Your prompt is converted into a vector embedding using the same model used for the tool definitions
• Similarity search: The system performs a cosine similarity search, comparing the prompt vector against the vector index of tools to find the best semantic matches
• Top-K selection: To balance performance and accuracy, the system ranks the results and selects the top matches, typically around ten tools

Phase 3: Execution context

These selected tools are then injected into the model’s execution context as a temporary “function catalog.” This ensures the LLM has all the relevant capabilities it needs to fulfill your request while keeping the prompt size optimized for speed and cost.

Handling tool dependencies

Some MCP tools act as orchestrators that guide a workflow and require additional tools to complete the task. If only the orchestrator tool appears in the retrieved set, execution may fail because required tools are missing.

Abilities address this with post-selection expansion.

This ensures that the agent has the tools needed to complete the task while keeping the overall tool set small.

Conclusion

From intent to execution, Abilities ensure that Agentforce Vibes has exactly what it needs, every time. By utilizing RAG-based semantic retrieval and automated dependency expansion, this system effectively manages the expanding catalog of Salesforce DX MCP tools to deliver high-quality, focused development environments without manual configuration.

As Agentforce Vibes grows, the Abilities intelligent context activation system may expand to support:

• Additional Salesforce and third-party MCP servers
• Integration with Skills for task guidance once the right tools are activated
• Richer tool metadata for retrieval
• Improved dependency discovery

Resources

• Agenforce Vibes Developer Guide: Abilities
• Trailhead: Quick Start: Troubleshoot Code with Agentforce Vibes
• Trailhead: Get Started with Agentforce Vibes
• Video: Agentforce Vibes Decoded

About the authors

Jeff Douglas is a Product Management Director at Salesforce working on Agentforce Vibes and AI-powered developer tools. A Salesforce Developer since 2007, and one of the original Salesforce MVPs, he helped launch Trailhead and build several of its core learning and assessment systems. Jeff is an Army veteran, former brewery owner, foster and adoptive parent, woodworker, and owner of a growing herd of mini Scottish Highland cows. Connect with him on LinkedIn.

Ken Lewis is a Lead Member of Technical Services at Salesforce based in Oakland, CA. He formerly worked on Salesforce products for the Nonprofit sector, and enjoys making Salesforce products work best for all types of customers. Outside of work, you can find Ken playing racquetball, practicing on his home DJ setup, or exploring new restaurants and activities in the Bay Area. Connect with him on LinkedIn.

The post Intent-Driven Tool Selection Using Abilities in Agentforce Vibes appeared first on Salesforce Developers Blog.

The feature is based on the OpenTelemetry standard and stores all span data directly in Data 360, making it queryable alongside the rest of your org’s data with a single toggle flip.

How to enable Agent Platform Tracing

Enabling Agent Platform Tracing takes about two minutes:

1. Toggle it on in Setup. Navigate to Setup → Agent Platform Tracing and flip the toggle to enabled. This starts writing span data to Data 360 for every Agentforce action execution in your org.
2. Verify Data 360 is provisioned. Agent Platform Tracing stores spans in data model objects (DMOs), so your org needs Data 360 provisioned and active. If you’re already using Agentforce, this is likely already in place.
3. Check permissions. Users querying trace data need the Data Cloud Data Access permission set, plus read access to the ssot__TelemetryTraceSpan__dlm and related DMOs.
4. Wait for data. Spans begin populating within minutes of the first Agentforce action execution after enablement. There’s no backfill of historical data.

Once enabled, trace data is queryable via SOQL against the Data 360 DMOs described in the sections below.

How Agent Platform Tracing builds a trace tree

The core concept of Agent Platform Tracing is straightforward: each instrumented service that is called when an Agentforce action executes generates a telemetry record called a span, and every span records its parent’s ID. That parent-child chain lets you reconstruct the execution sequence as a hierarchical tree, from the root interaction down through the instrumented downstream calls.

Here’s what that looks like in practice. The following trace shows an agent action executing a flow that results in an error:

[OK] run.interaction (96afcfefaa6fbfe9) — 2,430ms
└── [OK] run.llmstep (9939b8bc33d12bfa) — 167ms
    └── [OK] run.topic.FlowAgentforce__FlowBuilderAutomationsTopic — 3ms
        └── [OK] run.llmstep (b3595456464fbe93) — 1,341ms
            └── [ERROR] run.action.Get_Account_179SB000000v31B — 481ms
                ├── [OK] run.invokeActions.FLOW — 274ms [InvocableAction]
                │   └── [OK] run.Get_Account.1 — 266ms [Flow]
                │       Attributes: flow.api.name=Get_Account, flow.api.version=1,
                │                   flow.execution.api.version=Spring '26,    
   |                    flow.type=AutolnchNoTrig
                │       └── [OK] run.createrecord.account — 42ms [Flow]
                │           Attributes: db.collection.name=Account, db.rows_affected=0,
                │                       db.operation.name=query
                └── [OK] run.llmstep (b4e5194e749ede24) — 884ms

A few key things to call out here: the ssot__DurationNumber__c field (e.g. 2,430ms) tells you how long each step took, and ssot__StatusCode__c (Status is always either OK or ERROR) tells you exactly where a chain broke.

Note that the flow ran successfully — run.Get_Account.1 returned OK — but the parent action still errored. The reason is in the span attributes: db.rows_affected=0 tells you the Account query returned nothing. Despite the operation being named run.createrecord, the db.operation.name=query attribute reveals it was actually performing a lookup, not a write, and that lookup came back empty. The action expected a result and didn’t get one. Execution continued anyway with a fallback run.llmstep, which is why the overall interaction didn’t terminate immediately.

Without the span attributes, you’d see a failed action and have no idea whether the flow ran, whether it touched the database, or what it found there.

Comparing Agentforce session tracing and Agent Platform Tracing

Agent Platform Tracing stores spans into Data Lake Object (DLOs) which get mapped into Data Model Object (DMOs) using the single source of truth (ssot) prefix. Before going further, it’s worth understanding how Agentforce sSession Tracing and Agent Platform Tracing differ.

Agentforce Session Tracing — centered on ssot__AiAgentInteraction__dlm — is instrumented at the planner level and captures the conversational flow: what the user said, which subagent handled the request, and what the agent returned. Agent Platform Tracing, via ssot__TelemetryTraceSpan__dlm, is instrumented at the service level and captures the back-end execution state that powered that response. The span DMO is self-referential by design: ssot__TelemetryParentSpanId__c maps back to ssot__Id__c, enabling tree traversal from any node in either direction. Furthermore, because both DMOs share the exact same underlying Trace ID, you can join ssot__TelemetryTraceId__c directly to ssot__TelemetryTrace__c. This enables you to connect Agentforce session tracing to the specific back-end code execution provided by Agent Platform Tracing.

Querying trace data with SOQL

With SOQL, you can query these DMOs directly via the API to extract exactly the diagnostics you need. A good starting point is profiling performance by operation type, which quickly surfaces any parts of your agent execution that are consistently slow:

SELECT ssot__OperationName__c,
       AVG(ssot__DurationNumber__c) AvgDuration,
       MAX(ssot__DurationNumber__c) MaxDuration,
       COUNT(Id) SpanCount
FROM ssot__TelemetryTraceSpan__dlm
WHERE ssot__StartDateTime__c > 2026-01-01T00:00:00Z
GROUP BY ssot__OperationName__c
LIMIT 20

Or we can query for all recent spans that have errors:

SELECT ssot__Id__c, ssot__OperationName__c, ssot__TelemetryTrace__c,
       ssot__StartDateTime__c, ssot__DurationNumber__c, ssot__StatusCode__c
FROM ssot__TelemetryTraceSpan__dlm
WHERE ssot__StatusCode__c = 'ERROR'
ORDER BY ssot__StartDateTime__c DESC
LIMIT 20

Or count errors across operation types:

SELECT ssot__OperationName__c, COUNT(Id) SpanCount
FROM ssot__TelemetryTraceSpan__dlm
WHERE ssot__StatusCode__c = 'ERROR'
GROUP BY ssot__OperationName__c
LIMIT 20

Once we find a span we want to investigate, we can query for all related spans via ssot__TelemetryTrace__c:

SELECT ssot__Id__c, ssot__OperationName__c, ssot__TelemetryParentSpanId__c,
       ssot__ServiceName__c, ssot__StatusCode__c, ssot__DurationNumber__c,
       ssot__StartDateTime__c, ssot__EndDateTime__c,
       ssot__TelemetrySpanAttributeText__c
FROM ssot__TelemetryTraceSpan__dlm
WHERE ssot__TelemetryTrace__c = 'YOUR_TRACE_ID'
ORDER BY ssot__StartDateTime__c ASC

We can then reconstruct the tree client-side by matching each span’s ssot__TelemetryParentSpanId__c to another span’s ssot__Id__c, treating null or 0000000000000000 as the root.

Query Agent Platform Tracing data from Slack with Slackbot

Because this data lives in Data 360, you can easily query the data to observe Agentforce. One effective pattern is wiring instructions into a Slack canvas, feeding it to Slackbot, and using it as the natural language interface for our trace data. This makes it easy for anyone to digest the trace information, as long as Slackbot is set up to query the information correctly. Whether you’re responding to a user complaint or proactively checking for errors, the workflow is the same: ask the bot, get the trace tree, pinpoint the issue, and discuss a fix, without ever leaving Slack. No log spelunking, no guesswork. Just a conversation with Slackbot to find the root cause and come up with a potential solution.

The approach I take when providing instructions to Slackbot is simple: I provide the schemas, sample queries, join patterns, and main use cases. You can find some of the instructions I use in my  Agent Platform Tracing Slackbot Instructions GitHub repo. 

You’ll need to make sure that your Slack is connected to an org that has Agent Platform Tracing enabled. Once you do, just add the instructions for Slackbot into a canvas and either add the canvas as a tab for Slackbot or paste it into the chat at the beginning of your conversation.

Here’s a typical Slackbot exchange:

You:  Why did interaction b9e8f7b4 take 4 seconds?

Slackbot:  I queried all spans for trace b9e8f7b4. The interaction
           took 2,690ms total. Here's the breakdown:

           run.interaction           2,690ms  OK
           └─ run.llmstep              139ms  OK
              └─ run.topic               3ms  OK
                 └─ run.llmstep        838ms  OK
                    └─ run.action      327ms  OK
                       └─ run.llmstep 1,011ms  OK   ← slowest span

           The bottleneck is the final run.llmstep span (1,011ms),
           which accounts for 38% of total duration.

Once you have Slackbot set up with Agent Platform Tracing, you can ask things like:

• Why did this agent interaction take 4 seconds?
• Which subagent is responsible for the most errors this week?
• What are the most common errors for a given operation type? 
• What’s the root cause of this issue that a user is asking about? 

Joining Agentforce Session Tracing and Agent Platform Tracing data

With the right instructions, Slackbot can query and join both Agentforce Session Tracing and Agent Platform Tracing data together. Joining them provides a full trace tree for end-to-end observability of Agentforce. With both features, we have complete visibility of agent activity and issues in a couple of minutes.

Use this when you want to correlate a user’s conversational context (Agentforce Session Tracing) with the back-end execution details (Agent Platform Tracing). This is an optional advanced use case; both features work independently.

How the join works

Because ssot__TelemetryTraceId__c on ssot__AiAgentInteraction__dlm matches ssot__TelemetryTrace__c on ssot__TelemetryTraceSpan__dlm, they can be used for a direct join. This means you can fetch all spans for an interaction in a single query.

Full joined hierarchy

Session (ssot__AiAgentSession__dlm)
└── Interaction (ssot__AiAgentInteraction__dlm)
    └── Step (ssot__AiAgentInteractionStep__dlm)
        └── Span (ssot__TelemetryTraceSpan__dlm)
            └── Span (ssot__TelemetryTraceSpan__dlm)
                └── ...

Query pattern: Get all spans for a known interaction

SELECT ssot__Id__c, ssot__OperationName__c, ssot__TelemetryParentSpanId__c,
       ssot__StartDateTime__c, ssot__DurationNumber__c, ssot__StatusCode__c
FROM ssot__TelemetryTraceSpan__dlm
WHERE ssot__TelemetryTrace__c = 'TELEMETRY_TRACE_ID_FROM_INTERACTION'
ORDER BY ssot__StartDateTime__c ASC

Getting started

Generative AI adds complexity to modern stacks that traditional logging wasn’t designed to observe, and the cost of those blind spots compounds the longer they take to find. Agent Platform Tracing removes the blind spots. And, when you combine it with Slackbot, it is far easier to observe, troubleshoot, and fix Agentforce issues in production so your agents can get back to work without issues. Check out the Agent Platform Tracing Slackbot Instructions GitHub repo for working Slackbot instructions that you can copy-and-paste into a canvas to get started, and the Agent Platform Tracing documentation for setup instructions and the full data model reference.

Trevor Scott is a Senior Manager of Product Management at Salesforce, focused on enabling customers with security and telemetry data to help developers and admins ship more confidently.

The post Agent Platform Tracing: Debug Agentforce with Trace Trees, SOQL, and Slack appeared first on Salesforce Developers Blog.

This post covers how the new MCP server works, how to install it locally, and how your feedback will help us shape the future of the tool.

Solving the context window challenge

Data 360 has a massive API surface. Exposing every endpoint directly as a tool quickly overwhelms a large language model’s (LLM) context window. To solve this, our engineering team implemented a novel approach inspired by Cloudflare’s research on MCP server tool management at scale. Instead of registering the approximately 200 REST API operations individually, this MCP server consolidates them behind three facade tools:

• search: Discovers tools by intent, keyword, or family.
• payload_examples: Fetches working JSON payloads so the LLM understands how to structure complex requests.
• execute: Runs the specific underlying tool by name and passes the correct parameters.

When an LLM wants to perform a task, it uses a typical workflow: it searches for the right capability, fetches a payload example to understand the required data structure, and then executes the operation. This approach saves context window space and improves the accuracy of the AI’s actions while remaining flexible enough to support the ever-growing headless capabilities of Data 360 far into the future.

What the Data 360 MCP server includes

Under the hood, the three facade tools give your AI client access to hundreds of REST API operations organized into tool families. These tools connect directly to most of the general availability (GA) APIs on Data 360.

Getting started: installation and authentication

During this Developer Preview, the MCP server is designed for local execution and is not yet multitenant. This means each running instance connects a single user to a single Salesforce org.

To run the server, you need Java 17 or later, Maven 3.9 or later, and a Salesforce org with Data 360 enabled. You can use an Agentforce Developer Edition org or a Data 360-enabled Trailhead playground if you want to test it in an isolated environment. The server communicates via stdio, so it will work with any MCP client that supports this transport layer. Once your org is ready, follow the instructions in the README to connect your agent and start building.

The GitHub repo contains an installer script that helps set up dependencies and configure common MCP clients for use with the server.

Help us shape the general availability release

The new Data 360 MCP Server enables you to connect powerful LLMs to your Salesforce data without hitting context window limits. By using a novel facade tool architecture, we’ve made roughly 200 API operations easily accessible for agents and coding assistants. 

The Developer Preview is a critical step before we integrate this architecture directly into the Salesforce platform for general availability. By releasing it as open-source now, we aim to speed up platform integration and gather direct feedback from developers. Install the server today, test it with your local tools, and share your feedback on GitHub to help us prepare for the GA release. 

When the Data 360 MCP server becomes generally available, we’ll offer it as a Salesforce Hosted MCP Server alongside other product integration MCP servers. In the meantime, our entire Data 360 team will be testing it internally alongside you to build and refine a collection of Data 360 agent skills; stay tuned for more news on those!

About the authors

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

Chris Peterson is a Senior Director of Product Management at Salesforce, currently working on Data 360 Headless.

The post Introducing the Data 360 MCP Server (Developer Preview) appeared first on Salesforce Developers Blog.

We introduced the newest version of the GraphQL wire adapter (lightning/graphql) in Spring ‘26. Now we’re introducing support for using GraphQL beyond just querying in LWC, adding the ability to easily create, update, and delete records via the GraphQL Mutations API.

Executing GraphQL mutations in LWC with executeMutation

In LWC, interacting with the Salesforce GraphQL API for mutations is achieved via the executeMutation function from the lightning/graphql module.
The executeMutation function allows you to execute one or more data changes. The function accepts an object parameter with the same three properties as the GraphQL wire: query, variables, and operationName. For example, to update an Account’s name:

import { gql, executeMutation } from 'lightning/graphql';

const updateRecord = gql(`
            mutation UpdateAccount($input: AccountUpdateInput!) {
                uiapi {
                    AccountUpdate(input: $input) {
                        success
                    }
                }
            }
`);

 await executeMutation({
            query: updateRecord,
            variables: {
                input: {
                    Id: '001xx000003GYiCAAW',
                    Account: {
                        Name: 'Acme[Updated]',
                    },
                },
            },
        });

The executeMutation function supports dynamic query creation, just like the updated GraphQL support provided by lightning/graphql, so you can build these mutation inputs dynamically with JavaScript.

Data consistency considerations

Lightning Data Service keeps Salesforce record data consistent across UIAPI and GraphQL. With GraphQL mutations, this mostly works seamlessly, but we do have a few tips for getting the best results: 

• Newly created records will not appear in existing GraphQL query results until the query is refreshed, depending on its filter criteria and cache state. This applies to create and update mutations that affect records included in a query result set. 
• Updated record fields may be propagated to subscribed Lightning Data Service wire adapters when their cached data overlaps. It may not be necessary to refresh in all scenarios.
• Deleted records will properly be removed from Lightning Data Service wire results. Refreshes are not required for delete operations.

See it in action: The LWC recipes showcase

To help you get started immediately, we have added dedicated examples to the LWC Recipes GitHub repository.

The new graphqlMutation components demonstrate how to use executeMutation to handle create, update, and delete operations through GraphQL. By exploring the source code for the graphqlMutation components, you can see practical implementations of data mutation, success handling, and error display via toast events.

You can clone the LWC Recipes repository to your local machine and deploy the app to your Salesforce org to test this new functionality.

GraphQL Mutations fully unlock bulk updates and tree saves for Lightning Web Components (LWC) without custom Apex. You can now not only view your Salesforce data efficiently but also modify it seamlessly, bringing richer, data-driven applications to life. This capability significantly streamlines the development of complex UIs that require simultaneous creation, update, or deletion of multiple related records. The integration of GraphQL Mutations marks a major step toward empowering LWC developers with a more modern and powerful way to manage data transactions on the Salesforce platform.

Developer Resources

Ready to start mutating your data? Here are the resources you need to dive in:

• Developer Documentation: lightning/graphql
• GitHub repository: LWC Recipes – Find the new graphqlMutation components and other examples.
• API Developer Guide: GraphQL API – Details on the mutation schema and structure.
• Postman Collection: Salesforce Platform APIs/GraphQL – Helpful for testing mutation structure.
• Best Practices Guide: GraphQL Wire Adapter Best Practices – Maximize your GraphQL potential.

About the Authors

Stephen Carraway is a Lead Member of Technical Staff at Salesforce from the Lightning Data Service team. When he’s not building client data libraries, he’s busy woodworking, gardening, and 3D printing. 

Ben Sklar is a Director of Product Management at Salesforce responsible for UI API, the Salesforce GraphQL API, the Lightning Data Service, and AI Developer Kit. Ben is a major fan of GraphQL, but when not using GraphQL, you can find him playing ultimate frisbee or skiing during the winter. Follow him on LinkedIn.

The post GraphQL Mutations Now Available in LWC: Create, Update, and Delete Records appeared first on Salesforce Developers Blog.