But data and actions are only half of the story. When an agent replies with a wall of text, users lose the rich, interactive experience they’re used to inside Salesforce. The Headless Experience Layer (HXL) closes that gap. HXL is the part of the Headless Toolkit that brings interactive experiences to any agent: you define a widget once in declarative JSON, and it renders natively in Agentforce and in any Model Context Protocol (MCP) client that supports MCP Apps. No more rebuilding the same experience for every channel.

In this post, you’ll learn the core concepts, how HXL works, and where it fits in AIforce. We’ll then walk through a real widget from the Pronto sample app, following it from the Apex action to the MCP server.

Understanding the Headless Experience Layer

HXL is a centralized engine built on one principle: write once, render anywhere. Today, most agent actions return a plain-text sentence. With HXL, the same action returns a branded, interactive card that looks and behaves consistently, whether your user is in Agentforce, Slack, or Claude.

Because you build the widget once and reuse it on every supported interface, you don’t maintain a separate UI for each one. This saves development time and keeps the experience consistent. A widget isn’t a Lightning Web Component (LWC) or a React app. It’s a declarative tree of components that each surface renders natively.

Core platform benefits

• Your existing security model. A widget only displays what your action returns. When the action enforces sharing and field-level security, every surface shows each user only what they’re allowed to see.
• One source of truth. The same Apex action and the same widget definition serve every channel. There’s no second copy to keep in sync.
• Less integration code. Custom Lightning Types describe your data shape, so you don’t need custom API bridges between your org and each UI surface.

HXL Essentials: Components, Widgets, and Custom Lightning Types

The HXL architecture relies on three core concepts:

• Components: The foundational building blocks of HXL. Components are reusable UI primitives that can be composed to build different experiences. Each component is surface-aware and knows how to render across supported HXL surfaces.
• Widgets: Composed UI experiences built by combining multiple components to address a specific use case. Widgets define the final UI structure and behavior delivered to the user.
• Custom Lightning Types (CLTs): The bridge between data and UI. A CLT describes the shape of your data. Its renderer tells the platform which widget draws that data and how the fields map onto the widget’s attributes.

Where the widget’s data comes from

A widget doesn’t fetch data on its own. The data arrives through the Custom Lightning Type (CLT), which defines the structure your data must follow. Whatever source you use, its output has to match the CLT structure so its properties can bind to the widget attributes. In this post, the data source is an Apex invocable action, following the pattern used in the HXL docs and the Pronto sample app.

How HXL works

You write the Apex action once and the widget once. Only the wiring between them changes per channel.

What you can build in the beta

In the HXL beta, you can:

• Build widgets as JSON in your Salesforce DX project, or vibe code them with an AI agent using the Salesforce Skills library. 
• Learn the components and preview layouts in the HXL Playground.
• Render widgets in Agentforce and preview them in Agentforce Builder. See how to render a widget in Agentforce.
• Render widgets in MCP clients that support the MCP Apps standard, such as Claude and ChatGPT.
• Make widgets interactive with two client actions, sendMessage and openLink.

Example: a Pronto customer reviews widget

To keep things concrete, we’ll use Pronto, our fictional food-delivery sample app. Pronto ships an Employee_Assistant agent with a Get Customer Reviews action. Ask the agent, “Show me the reviews for The Green Fork,” and it will render a review card instead of a paragraph of text.

The card shows a header with the average rating, followed by one entry per review with the customer’s name, the order date, the star rating, and the comment. It’s built from four pieces:

1. An Apex invocable action that returns the review data.
2. A widget that defines the card’s layout.
3. A Custom Lightning Type that binds the action’s output to the widget.
4. An agent action output (or an MCP tool) that tells the surface to render that type.

How the HXL files map in a Salesforce DX project

Here’s how the four pieces map to files in the Pronto repo. The rest of this post walks through them in this order.

Start with the Apex action

Everything starts with the data. GetCustomerReviewsAction is a global Apex class with an @InvocableMethod. It returns a success flag, a message, and one structured reviews object. That object’s shape is what the widget and CLT bind to. Here’s the Apex class, trimmed to its contract:

global with sharing class GetCustomerReviewsAction {
  @InvocableMethod(label='Get Customer Reviews'
    description='Retrieves customer reviews for a specific storefront')
  global static List<Output> getCustomerReviews(List<Input> inputs) { /* ... */ }

  global class Output {
    @InvocableVariable(label='Success') public Boolean isSuccess;
    @InvocableVariable(label='Message') public String message;
    @InvocableVariable(label='Reviews') public ReviewWrapper reviews;
  }

  global class ReviewWrapper {
    @InvocableVariable public Integer reviewCount;
    @InvocableVariable public Decimal averageRating;
    @InvocableVariable public List<ReviewItemWrapper> items;
  }

  global class ReviewItemWrapper {
    @InvocableVariable public String customerName;
    @InvocableVariable public Decimal rating;
    @InvocableVariable public Date orderDate;
    @InvocableVariable public String comments;
  }
}

Note: The Apex class computes averageRating and reviewCount itself. The widget can’t do math, so the action hands it display-ready values.

Define the widget: layout, contract, and registration

A widget lives in a UiWidgetBundle under uiWidgets/<widgetName>/. The bundle holds up to three files, each with one job:

• customerReviews.uiwidget-meta.xml registers the bundle and sets widgetType to JSON.
• customerReviews.json is the composition file. It’s the layout, built from tile/* blocks.
• schema.json is optional. It declares the type of each attribute, so tools can validate your bindings before you deploy.

Every composition starts with a lightning__agentforceWidget root and a tile/widget tree. Values that change per record are {!$attrs.<name>} placeholders. To repeat a component for each item in a list, you add a forEach meta property and name the loop variable with forItem. Here’s the core of Pronto’s reviews widget, trimmed for brevity:

{
  "type": "lightning__agentforceWidget",
  "contentBody": {
    "widgetBody": {
      "definition": "tile/widget",
      "children": [
        {
          "definition": "tile/column",
          "attributes": { "gap": "lg" },
          "children": [
            {
              "definition": "tile/text",
              "attributes": {
                "text": "Average: {!$attrs.averageRating}/5 ({!$attrs.reviewCount} reviews)",
                "variant": "body",
                "color": "muted"
              }
            },
            {
              "definition": "tile/column",
              "attributes": { "gap": "md" },
              "meta": { "forEach": "{!$attrs.items}", "forItem": "$review" },
              "children": [
                {
                  "definition": "tile/text",
                  "attributes": { "text": "{!$review.customerName}", "variant": "h4", "weight": "semibold" }
                },
                {
                  "definition": "tile/text",
                  "attributes": { "text": "{!$review.rating}/5", "variant": "body", "weight": "semibold" }
                },
                {
                  "definition": "tile/text",
                  "attributes": { "text": "{!$review.comments}", "variant": "body", "color": "muted" }
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Inside the loop, $review is the current item. You reach each field with {!$review.<field>}. There’s no JavaScript in a widget, so the layout only places and styles values.

The schema is the widget’s contract. It names each attribute and gives it a lightning:type.
Notice that items is a list whose items point at an Apex class you just saw:

{
  "title": "Customer Reviews Widget",
  "type": "object",
  "properties": {
    "attributes": {
      "lightning:type": "lightning__objectType",
      "properties": {
        "reviewCount":   { "lightning:type": "lightning__numberType" },
        "averageRating": { "lightning:type": "lightning__numberType" },
        "items": {
          "lightning:type": "lightning__listType",
          "items": {
            "lightning:type": "@apexClassType/c__GetCustomerReviewsAction$ReviewItemWrapper"
          }
        }
      }
    }
  }
}

Preview widgets in the HXL Playground

The HXL Playground is a browser-based learning tool for HXL. It isn’t part of the build or deploy flow, so you don’t need it to ship a widget. It’s simply the fastest way to learn the components and try out a layout.

The Playground has three areas. The Components area documents each component and its attributes. The Widgets area lets you compose components and preview the result on several surfaces. Tutorials walk you from a single text block to a full widget.

To try Pronto’s reviews card, create a widget and paste the composition from customerReviews.json into the Structure tab. Then add sample values for averageRating, reviewCount, and items in the Data tab. The preview updates as you type, so you can fix the layout before you copy it back into your project. Previews can differ from the live experience, so always test on each target surface.

Bind data to UI with a Custom Lightning Type

A Custom Lightning Type (CLT) connects your action’s output to a widget. A widget is a shell until data flows in. For Agentforce, the CLT is typed directly to the Apex class that the action returns. Pronto’s customerReviewsOutput type points at the action’s ReviewWrapper inner class:

{
  "title": "Customer Reviews Output",
  "description": "Customer reviews and rating summary returned by GetCustomerReviewsAction, rendered as a widget",
  "lightning:type": "@apexClassType/c__GetCustomerReviewsAction$ReviewWrapper"
}

The CLT’s renderer.json points at the widget and binds each widget attribute to an output field:

{
  "renderer": {
    "componentOverrides": {
      "$": {
        "definition": "@widget/c/customerReviews",
        "attributes": {
          "reviewCount":   "{!$attrs.reviewCount}",
          "averageRating": "{!$attrs.averageRating}",
          "items":         "{!$attrs.items}"
        }
      }
    }
  }
}

Read each binding from right to left. The output field on the right feeds the widget attribute on the left. Two details matter here. The "$" key means “the whole type,” and the @widget/ prefix tells the platform to resolve a UiWidgetBundle.

Render the widget in Agentforce

The agent needs to know that this output should render. In Pronto’s Agent Script, the action’s reviews output names the CLT and marks itself displayable:

reviews: object
    label: "Reviews"
    complex_data_type_name: "c__customerReviewsOutput"
    filter_from_agent: False
    is_displayable: True

With is_displayable: True, the agent can show the output in the conversation. Agentforce then resolves the CLT, follows its renderer to the widget, and draws the card. Keep filter_from_agent: False so the output also stays in the agent’s context.

The model still decides when to show the card. In our testing, it usually renders on the first question in a fresh conversation. Follow-up questions in the same conversation sometimes come back as text. To make rendering more consistent, name the action explicitly in your subagent’s instructions. Pronto’s Employee_Assistant does exactly that, referencing the action by name: Call {!@actions.getCustomerReviews} to retrieve customer reviews for a storefront.

Render the same widget through MCP

To render the same widget through MCP, you add two nested Custom Lightning Types, and only the outer one carries the renderer. This is where “render anywhere” pays off. Pronto exposes Get Customer Reviews as a tool on its ProntoEmployeeServer MCP server. HXL widgets follow the MCP Apps standard, so any MCP client that supports MCP Apps, such as Claude and ChatGPT, can render the same card.

MCP needs a different CLT shape, though. An MCP tool call wraps the action output in an envelope with actionName, isSuccess, and outputValues. So you add two nested types. The inner type, customerReviewsResponse, mirrors the Apex Output class. The outer type, customerReviews, mirrors the envelope. Only the outer type has a renderer, and its paths read two levels deep:

{
  "renderer": {
    "componentOverrides": {
      "$": {
        "definition": "@widget/c/customerReviews",
        "attributes": {
          "reviewCount":   "{!$attrs.outputValues.reviews.reviewCount}",
          "averageRating": "{!$attrs.outputValues.reviews.averageRating}",
          "items":         "{!$attrs.outputValues.reviews.items}"
        }
      }
    }
  }
}

The widget and the attribute names on the left are identical. Only the paths on the right change. In the MCP server definition, an entry publishes the outer type as a UI resource. The tool then points at that resource by name:

<tools>
    <apiDefinition>
        <apiIdentifier>aa:apex-GetCustomerReviewsAction</apiIdentifier>
        <apiSource>API_CATALOG</apiSource>
        <operation>GetCustomerReviewsAction</operation>
    </apiDefinition>
    <uiResource>customerReviews</uiResource>
    <readOnly>true</readOnly>
    <toolName>getCustomerReviews</toolName>
    <toolTitle>Get Customer Reviews</toolTitle>
</tools>
<resources>
    <resourceName>customerReviews</resourceName>
    <resourceUri>ui://widget/lightningType/c__customerReviews</resourceUri>
    <resourceTitle>Customer Reviews</resourceTitle>
</resources>

Every client that calls getCustomerReviews follows the resource back to the same @widget/c/customerReviews definition. After you deploy, activate the server in Setup under API Catalog > MCP Servers. Then connect your MCP client through an External Client App. The HXL MCP channels guide covers the client setup in detail.

How to get started

First, enable the beta. In Setup, search for Headless Experience Layer Settings under Feature Settings. Turn on Headless Experience Layer (Beta) and accept the beta terms. Your project should use API version 67.0 or later.

Next, explore a working example. Clone the Pronto sample app, install it in your org, and ask the Employee_Assistant for a storefront’s reviews. Then open the customerReviews widget and its two CLT shapes to see how the pieces fit.

When you’re ready to build your own widget, let an AI agent do the heavy lifting. The open-source Salesforce Skills library is optimized for Agentforce Vibes and works with other AI coding tools. Its HXL skills can plan the Apex display fields, the widget, and the Lightning Type from a single prompt. They can also update your Agent Script and generate the nested MCP types.

To try the whole flow hands-on, take the Give Agents UI with the Headless Experience Layer workshop. It builds a Pronto storefront profile card and renders it in both Agentforce and an MCP client.

Conclusion

HXL makes one hard thing easy: shipping consistent, interactive UI to every agent surface your users touch. You build a widget once and map your data with a Custom Lightning Type. The same card then renders inside Agentforce and across MCP clients, backed by the security your action already enforces. That means less UI code, no drift between channels, and faster delivery.

The fastest way to see it is to install Pronto and watch its review card render. Have questions or something to show? Bring them to the Trailblazer Community, or share what you build with us on LinkedIn.

Resources

• Headless Experience Layer: Get Started
• Build Rich UI with HXL
• HXL Playground
• Salesforce CLI
• Trailblazer Community
• Use HXL Widgets on MCP | Build Rich UI | Headless Experience Layer Developer Guide (Beta)
• Use Agentforce Vibes to Build Widgets | Headless Experience Layer Developer Guide (Beta)
• GitHub – forcedotcom/sf-skills: Salesforce’s curated collection of agent skills for building applications. Optimized for Agentforce Vibes, compatible with all AI tools.
• Give Agents UI with the Headless Experience Layer (HXL)

About the author

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

Monika Singh is a Senior Product Manager at Salesforce, focused on Headless Experience Layer (HXL). She has a background in AI/ML product management and is passionate about building intelligent, personalized digital experiences. For more details, visit her LinkedIn profile.

The post Building Interactive UI with Headless Experience Layer appeared first on Salesforce Developers Blog.

Batch data transforms

Data 360’s native batch data transform feature allows for data preparation over DLOs and DMOs, including through operations like joins, filters, and aggregates. You can use the Transform Builder UI to create batch transforms on the platform. The Batch Data Transforms in Data 360 Trailhead module is a great starting point.

Code Extension 

Code Extension is a Data 360 feature that runs custom PySpark logic against DLOs and DMOs inside an isolated Spark compute environment. It powers multiple pipelines, including search-index chunking and batch transform logic, the use case that this post covers.

If you are not familiar with the basics of Code Extension, you can check out the following resources before going deeper into this blog:

• Blog: Extend Data 360 with the Power of Code.
• YouTube: Extend Data 360 with Code Extension.
• Trailhead: Code Extension in Data 360 Module.

Under the hood: the development workflow for Code Extension batch data transform scripts

With Code Extensions, you author a PySpark script that drives the same batch transform pipeline as the one used by native batch transforms. A batch transform Code Extension script runs under strict isolation, using the datacustomcode SDK‘s Client() for reading and writing to DLOs or DMOs.

Here’s a high-level overview of what happens on your (the developer’s) machine and what happens in Data 360:

On the developer machine, a Python virtual environment is used for local execution involving the SDK, your custom PySpark script, and its dependencies. To run the extension locally, you use the following Salesforce Command Line Interface (SF CLI) for Code Extension command: sf data-code-extension script run. The command executes a Spark job on your computer, which reads DLOs or DMOs using the Connect API (by default, the first 1000 rows), and writes only to console output. This is where you’ll iterate until the logic works as intended.

The next step is to deploy to your org. To do so, use the SF CLI command: sf data-code-extension script deploy. The command zips up the project using Docker and uploads it via the Connect API into a Data 360 Transform and Code Extension pair.

When running the transform (now or on a schedule), Data 360 manages the Spark job, which executes your PySpark script to read from and write to DLOs or DMOs.

We recently published Run Complex Data Transformations in Data 360 with Code Extension, which gives you more information about the basics. Below, we build on that introduction and walk through three more examples: rolling up an account hierarchy, exploding a JSON event stream, and scoring leads with a bundled scikit-learn model.

Example 1: Iterative rollup of an account hierarchy

The use case: Roll up each account’s total-tree Annual Recurring Revenue (ARR), including its own plus every descendant’s, at any depth, into Account_Rollup__dll.

The solution: With the Account__dll records having various descendant depths, we can use a loop and keep joining the frontier one hop deeper until nothing new comes back.

from pyspark.sql.functions import col, sum as _sum, coalesce, lit

from datacustomcode.client import Client
from datacustomcode.io.writer.base import WriteMode


def main():
    client = Client()

    accounts = (
        client.read_dlo("Account__dll")
        .select("id__c", "parent_id__c", "arr__c")
        .persist()
    )

    descendants = accounts.select(
        col("id__c").alias("root_id"),
        col("id__c").alias("descendant_id"),
    ).persist()

    frontier = descendants
    while True:
        next_hop = (
            frontier.alias("f")
            .join(
                accounts.alias("a"),
                col("a.parent_id__c") == col("f.descendant_id"),
                "inner",
            )
            .select(
                col("f.root_id").alias("root_id"),
                col("a.id__c").alias("descendant_id"),
            )
        )
        if next_hop.isEmpty():
            break
        descendants = descendants.union(next_hop).persist()
        frontier = next_hop

    totals = (
        descendants.alias("d")
        .join(
            accounts.alias("a"),
            col("d.descendant_id") == col("a.id__c"),
            "left",
        )
        .select(col("d.root_id"), col("a.arr__c"))
        .groupBy("root_id")
        .agg(coalesce(_sum("arr__c"), lit(0)).alias("tree_arr__c"))
        .withColumnRenamed("root_id", "id__c")
    )

    client.write_to_dlo("Account_Rollup__dll", totals, WriteMode.OVERWRITE)


if __name__ == "__main__":
    main()

The convergence check, stop, accumulate loop is plain Python driving DataFrames. NOTE: This convergence check assumes an acyclic hierarchy. If parent_id__c can form a cycle, add a max-depth counter to break the loop so a bad record can’t hang the Spark job indefinitely.

The results written to Account_Rollup__dll are as expected for this sample dataset:

You can find this entire example, including the sample data used, in the SDK’s docs/examples/script/account_rollup directory.

Example 2: Flatten a batched event stream from a JSON-array column

The use case: Analytics SDKs commonly deliver events batched by session. One row per session is stored in a raw landing DLO, with each session’s events packed into a single JSON-array column. Downstream analysis use cases, such as funnel analysis, cohort segmentation, or identity-graph inputs, need one row per event.

The solution: The parse-and-explode logic is worth pulling out of the entrypoint into a reusable helper. With Code Extensions, this can be done by putting files or modules in the payload/py-files/ directory, which needs to have this exact name.

# payload/py-files/events.py
from pyspark.sql.functions import col, explode_outer, from_json, to_timestamp
from pyspark.sql.types import (
    ArrayType, StringType, StructField, StructType,
)


EVENT_SCHEMA = StructType([
    StructField("event_id", StringType(), True),
    StructField("event_type", StringType(), True),
    StructField("ts", StringType(), True),
    StructField("path", StringType(), True),
    StructField("value", StringType(), True),
])
EVENT_ARRAY_SCHEMA = ArrayType(EVENT_SCHEMA, True)

# One row per event, carrying its parent session + user.
def parse_events(df, session_col, user_col, events_col):
    field = next(f for f in df.schema.fields if f.name == events_col)
    events = (
        col(events_col)
        if isinstance(field.dataType, ArrayType)
        else from_json(col(events_col).cast("string"), EVENT_ARRAY_SCHEMA)
    )
    return df.select(
        col(session_col),
        col(user_col),
        explode_outer(events).alias("evt"),
    ).select(
        col("evt.event_id").alias("event_id__c"),
        col(session_col),
        col(user_col),
        col("evt.event_type").alias("event_type__c"),
        to_timestamp(col("evt.ts")).alias("event_ts__c"),
        col("evt.path").alias("path__c"),
        col("evt.value").alias("value__c"),
    )

The entrypoint is now thinner: read, explode, filter, write.

# payload/entrypoint.py
from pyspark.sql.functions import col

from datacustomcode.client import Client
from datacustomcode.io.writer.base import WriteMode
from events import parse_events


def main():
    client = Client()

    sessions = client.read_dlo("User_Sessions__dll").select(
        "session_id__c", "user_id__c", "events__c"
    )
    exploded = parse_events(sessions, "session_id__c", "user_id__c", "events__c")

    output = exploded.filter(col("event_id__c").isNotNull())

    client.write_to_dlo("User_Events__dll", output, WriteMode.OVERWRITE)


if __name__ == "__main__":
    main()

The results written to User_Events__dll are as expected for the sample dataset:

You can find this entire example, including the sample data used, in the SDK’s docs/examples/script/json_explode directory.

Example 3: Score leads with a bundled scikit-learn model

The use case: The data scientist on your team trained a small scikit-learn classifier over categorical lead features (for example, industry, employee band, region, and source) and handed you the serialized artifact. You want a score on every lead as part of the nightly pipeline.

The solution: Similar to the py-files directory from the last example, you can ship other file types in the files directory. You can also ship external dependencies in Code Extensions by using the requirements.txt file, which in this example brings in scikit-learn, joblib, and pandas. Bundle the model as payload/files/lead_scorer.zip (a zip around lead_scorer.joblib — the joblib carries the sklearn pipeline plus feature schema and value domain). The training script is a plain scikit-learn Pipeline fit, run locally before deploying the Code Extension for any model adjustments.

The PySpark entrypoint can joblib.load the model, enumerate every combination of its categorical inputs, score that small grid with predict_proba, and left-join the grid against the leads DLO.

import itertools
import tempfile
import zipfile
from pathlib import Path

import joblib
import pandas as pd
from pyspark.sql import Row
from pyspark.sql.functions import coalesce, col, lit

from datacustomcode.client import Client
from datacustomcode.io.writer.base import WriteMode


UNKNOWN = "__unknown__"
MODEL_ARCHIVE = "lead_scorer.zip"
MODEL_MEMBER = "lead_scorer.joblib"

OUTPUT_COLUMNS = [
    "id__c", "first_name__c", "last_name__c", "industry__c",
    "employee_band__c", "region__c", "source__c", "score__c",
]


def load_bundled_model(client):
    archive_path = client.find_file_path(MODEL_ARCHIVE)
    extract_dir = Path(tempfile.mkdtemp(prefix="lead_scorer_"))
    with zipfile.ZipFile(archive_path) as zf:
        zf.extract(MODEL_MEMBER, path=extract_dir)
    return joblib.load(extract_dir / MODEL_MEMBER)


def build_score_grid(spark, bundle):
    pipeline = bundle["pipeline"]
    feature_cols = bundle["feature_cols"]
    domain = bundle["feature_domain"]

    combos = list(itertools.product(*(domain[c] for c in feature_cols)))
    grid_pd = pd.DataFrame(combos, columns=feature_cols)
    grid_pd["score__c"] = pipeline.predict_proba(grid_pd)[:, 1]

    rows = [
        Row(**{c: r[c] for c in feature_cols}, score__c=float(r["score__c"]))
        for r in grid_pd.to_dict(orient="records")
    ]
    return spark.createDataFrame(rows), feature_cols


def main():
    client = Client()

    leads = client.read_dlo("Lead__dll")
    spark = leads.sparkSession

    bundle = load_bundled_model(client)
    grid, feature_cols = build_score_grid(spark, bundle)

    normalized = leads
    for c in feature_cols:
        normalized = normalized.withColumn(c, coalesce(col(c), lit(UNKNOWN)))

    scored = (
        normalized.alias("l")
        .join(grid.alias("g"), feature_cols, "left")
        .withColumn("score__c", coalesce(col("score__c"), lit(0.0)))
    )

    client.write_to_dlo(
        "Lead_Scored__dll", scored.select(*OUTPUT_COLUMNS), WriteMode.OVERWRITE
    )


if __name__ == "__main__":
    main()

The grid is small, just a few thousand rows, so Spark’s planner auto-broadcasts it and every lead gets its score from a plain equi-join. This approach works well when features are naturally categorical or already banded (industry, region, tier, or segment). Same pattern for churn, propensity, and product-affinity: any model whose inputs are categorical or bucketable. coalesce to __unknown__ keeps the join total as new industries or sources appear.

The results written to Lead_Scored__dll are as expected for the sample dataset:

Because Lead_Scored__dll is a first-class Data 360 object, once mapped into a DMO, an Agentforce agent like Coworker can query it directly: “Who are my top 10 hottest leads this week?”

You can find this entire example, including the sample data used, in the SDK’s docs/examples/script/lead_scoring directory.

Limits and other considerations

Code Extension jobs run under managed Spark with fixed memory, timeout, and dependency-size limits documented in the Considerations When Writing Code Extensions guide. Because local runs sample only the first 1000 rows (by default) via the Connect API, data-scale problems, such as partition skew on a deep account tree or an out-of-memory issue on a large explode, only surface on the deployed run, so test at full scale after deploy. The documented limitations will evolve over time based on the roadmap, which you can influence by reaching out to your account executive and discussing feature requests.

Conclusion

Code Extension is the right tool for the job when Python is the right language: imperative control flow, an existing library you want to reuse, a serialized model, a helper module worth unit-testing on its own. Code Extension for batch data transform is GA. What use cases does this unblock for you and your team? 

More Resources

• Python SDK: forcedotcom/datacloud-customcode-python-sdk · PyPI
• Salesforce CLI plugin: salesforcecli/plugin-data-code-extension
• Developer guide: Data 360 Code Extension
• Help: Batch Data Transforms Overview

About the author

Mark DeLaVergne is a Principal Software Engineer at Salesforce working on Code Extension in Data 360.  With 19 years in software engineering and architecture, he currently leads Code Extension and partners on wider Data 360 design.  You can find him on LinkedIn.

The post Advanced Code Extension PySpark Examples for Batch Data Transforms appeared first on Salesforce Developers Blog.

This post covers the key updates for developers. We start with AIforce and the Headless Toolkit, including Salesforce Multi-Framework, MCP, Salesforce CLI, and API updates. Then we cover Lightning Web Components (LWC), Apex, Agentforce, Data 360, and platform developer tools.

AIforce and Headless Toolkit

AIforce brings the full power of Salesforce to any interface. You build the capability once, and it shows up directly inside your users’ agents, apps, and workflows.

Under the hood, this runs on a headless architecture. Every major Salesforce capability is available as an API, a Model Context Protocol (MCP) tool, or a CLI command. Any authenticated caller can use it, whether that’s an app, a human, or an AI agent. The Headless Toolkit is the biggest developer theme of the Winter ’27 release. It brings AI Skills, the Headless Experience Layer (HXL), Multi-Framework apps, MCP tools, and CLI and API enhancements. Let’s dive into the main developer features.

Salesforce Development plugin for Claude Code

The Salesforce Development plugin teaches Claude Code how to build Salesforce apps and agents. It detects your Salesforce DX project and gives Claude Code Salesforce-specific skills and org context through pre-configured Salesforce-hosted MCP servers. Install the plugin from the Claude Plugin Marketplace, or run this command in Claude Code.

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

Using Codex, Cursor, or another coding agent? The plugin’s skills come from the open-source Salesforce skills library, which works with any agent that supports AI Skills. Install it with one command.

npx skills add forcedotcom/sf-skills

Explore what’s inside the plugin

The core plugin ships skills that cover the everyday Salesforce development lifecycle. They generate Apex, custom objects and fields, permission sets, Flows, reports, and Lightning pages. They also write and run Apex tests, analyze debug logs, run SOQL queries, configure sharing, scan code with Code Analyzer, and validate and deploy metadata.

The plugin also connects Claude Code to MCP servers for Salesforce API and metadata guidance. A bundled Apex and SOQL language server gives the agent the same code intelligence your IDE uses.

Go beyond the core plugin with specialized plugins

New in Winter ’27, the plugin knows when a task needs more than its core skills. Describe your task, and it recommends a specialized plugin from the Salesforce catalog. The catalog includes specialized plugins such as:

• dx-org-lifecycle: Manage Dev Hubs, scratch orgs, sandbox refreshes, trial orgs, and managed package post-install setup.
• dx-devops: Run DevOps Center pipelines and work items, and configure their automated tests.
• agentforce-adlc: Author, test, and deploy Agentforce agents.
• experience-lwc and experience-react: Build Lightning web components and React apps.
• integration: Set up Named Credentials, callouts, OAuth apps, and Change Data Capture.

To search the catalog yourself, add the plugins keyword and a description of your task.

/salesforce-development:discover plugins <description of your task>

Prefer fewer suggestions? Run /salesforce-development:plugin-recommendations to set how readily the plugin recommends plugins, from off to high.

Salesforce Multi-Framework

Salesforce Multi-Framework lets you build web apps with frontend frameworks you already know, like Angular or React, and run them on the Salesforce Platform. Your app gets Salesforce data, security, and governance without a separate hosting stack. Winter ’27 adds Angular alongsideReact, a richer Data SDK, a way to embed your app in Lightning pages using microfrontends, and 2GP packaging. 

Additionally, we’ve updated the Multi-Framework Recipes sample repository with new Angular and microfrontend code samples to help you get started.

Build Multi-Framework apps with Angular

Angular joins React as a supported framework. Bring your existing Angular skills, libraries, and apps to the platform. Scaffold an app from the angularinternalapp template for employee-facing apps, or the angularexternalapp template for customer and partner apps or angularbasic for a barebones template. Angularinternalapp and angularexternalapp templates come pre-wired with platform integration.

sf template generate project --name account-pulse --template angularinternalapp

Your app is a UIBundle metadata type. You build it with the standard Angular CLI and deploy it with the same Salesforce DX commands you use for the rest of your project.

Reuse data logic with Data SDK extensions

The Data SDK works with any framework and enforces object-level security, field-level security, and sharing rules on every request. In Winter ’27, you can package your own data logic as an extension. Write the extension once with defineDataExtension, and call it through a typed sdk.ext.<name> namespace in every bundle that needs it.

Here’s an extension that returns the top accounts by annual revenue, using the GraphQL API in User Interface API (UI API).

import { defineDataExtension, gql } from '@salesforce/platform-sdk';
interface TopAccountsQuery {
    uiapi: {
        query: {
            Account: {
                edges: {
                    node: {
                        Id: string;
                        Name: { value: string | null } | null;
                        AnnualRevenue: { value: number | null } | null;
                    };
                }[];
            };
        };
    };
}

const TOP_ACCOUNTS = gql`
    query TopAccounts($first: Int) {
        uiapi {
            query {
                Account(first: $first, orderBy: { AnnualRevenue: { order: DESC, nulls: LAST } }) {
                    edges {
                        node {
                            Id
                            Name @optional { value }
                            AnnualRevenue @optional { value }
                        }
                    }
                }
            }
        }
    }
`;
export const pulseExtension = defineDataExtension({
    name: 'pulse',
    setup: (sdk) => ({
        async topAccounts(first = 5) {
            if (!sdk.graphql) {
                throw new Error('GraphQL is not available on this surface');
            }
            const result = await sdk.graphql.query<TopAccountsQuery, { first: number }>({
                query: TOP_ACCOUNTS,
                variables: { first }
            });
            return (result.data?.uiapi.query.Account.edges ?? []).map(({ node }) => ({
                id: node.Id,
                name: node.Name?.value,
                annualRevenue: node.AnnualRevenue?.value
            }));
        }
    })
});

Attach the extension when you create the SDK, then call it like any other SDK method.

import { createDataSDK } from '@salesforce/platform-sdk';
import { pulseExtension } from './pulse-extension';

const sdk = await createDataSDK({ extensions: [pulseExtension] });
const accounts = await sdk.ext.pulse.topAccounts(5);

The Data SDK also picks up these additions:

• Labels extension: Retrieve custom labels by namespace and locale.
• Minimum API version: Set a minimum Salesforce API version on an extension so that it attaches only where its data exists.
• Per-request headers: Pass a headers option on an individual GraphQL query or mutation. Headers are part of the cache key, so requests with different headers don’t share cached responses.

Localize your app and talk to the host page

Use the new @salesforce/platform-sdk/i18n module to match dates, numbers, and currency to each user’s Salesforce locale. Call getCurrentApp() to read the running app’s namespace, name, and qualified name.

import { createDataSDK, getCurrentApp, getViewSDK } from '@salesforce/platform-sdk';
import { createI18nFormatters, fetchI18nContext } from '@salesforce/platform-sdk/i18n';

const sdk = await createDataSDK();

// Format currency with the running user's locale and currency
const ctx = await fetchI18nContext(sdk);
const fmt = createI18nFormatters(ctx);
const total = fmt.formatCurrency(5080000, { maximumFractionDigits: 0 });

// Read the running app's identity, for example c__w27AccountPulse
const app = await getCurrentApp();
console.log(app.identity?.qualifiedName);

Embed your app in Lightning pages as a microfrontend (Beta)

You don’t have to rebuild your app in LWC to show it on a Lightning page. Write a thin Lightning web component that renders the lightning-ui-embedding base component and points it at your deployed app’s URL. Salesforce hosts your app in a secure, sandboxed iframe and gives it a two-way channel to the surrounding page.

That channel is what makes a microfrontend feel native. The host component can pass data down to your app, and your app can send events back up. In our example below, an industry filter in the LWC filters the Angular app’s account list, and clicking an account in the Angular app shows that record in native Salesforce components.

Pass data from the host LWC to your app

Set the props attribute on lightning-ui-embedding. When a value changes, Salesforce pushes the new props to your app.

<template>
    <lightning-radio-group
        label="Filter the embedded app"
        type="button"
        options={industryOptions}
        value={industry}
        onchange={handleIndustryChange}>
    </lightning-radio-group>
    <lightning-ui-embedding
        lwc:ref="embedding"
        src={appUrl}
        props={embedProps}
        width="100%"
        height="560">
    </lightning-ui-embedding>
</template>

In your app, read the props with getUiState() from the view SDK, and subscribe to get every change.

const view = await getViewSDK();
const ui = view?.getUiState?.<PulseUiState>();
if (ui) {
    this.industry.set(ui.state.props.industry ?? '');
    ui.subscribe((next) => this.industry.set(next.props.industry ?? ''));
}

Send events from your app to the host LWC

Dispatch a CustomEvent through the view SDK. Salesforce forwards it to the host page.

select(account: PulseAccount): void {
    this.view?.dispatchEvent?.(
        new CustomEvent('pulse.accountselected', {
            detail: { recordId: account.id, name: account.name }
        })
    );
}

The event arrives on the lightning-ui-embedding element with the same type and detail. Embedding event names contain a dot, so you can’t bind them in the template. Add the listener once in renderedCallback instead.

import { LightningElement, api } from 'lwc';
export default class MicrofrontendHost extends LightningElement {
    @api appUrl; // deployed app URL on the salesforce.app domain
    industry = '';
    selected;
    listening = false;

    get embedProps() {
        return { industry: this.industry };
    }
    renderedCallback() {
        const embedding = this.refs.embedding;
        if (embedding && !this.listening) {
            this.listening = true;
            embedding.addEventListener('pulse.accountselected', (event) => {
                this.selected = event.detail; // { recordId, name }
            });
        }
    }
    handleIndustryChange(event) {
        this.industry = event.detail.value;
    }
}

The host then renders selected.recordId with lightning-record-view-form, so the details panel is plain Salesforce UI. Here’s the same page after a user picks Retail in the LWC filter and selects an account in the Angular app.

Embedding supports internal, employee-facing apps built with React or Angular and served from the salesforce.app domain. You can add the host component to Lightning pages and Experience Cloud site pages.

Package, manage, and monitor your apps

• Package with 2GP: Distribute Multi-Framework apps with second-generation packaging (2GP). Use unlocked packages for apps you want to keep editable, or managed packages to distribute locked, namespaced internal apps through AppExchange.
• Manage apps in App Manager: From Setup, open App Manager and select New App | New Multi-Framework App. Choose Builder Central to build from a natural language description, or Agentforce Vibes to work directly with code.
• Analyze performance in Scale Center (Beta): From Setup, open Multi-Framework Insights (Beta) and click Generate Insight Report. The dashboard shows key metrics for up to ten apps with the most page views over the last seven days.

Headless Experience Layer (Beta)

The Headless Experience Layer (HXL) lets you define a rich UI once, as a widget, and render it natively in Agentforce, Claude, and Slackbot. To show how it works, I built a snow report widget for an Agentforce agent. Four pieces of metadata connect the agent’s Apex action to the UI, and each piece refers to the next by name.

First, the agent’s action calls the Apex invocable method and types its output with a custom Lightning type, c__w27SnowReport.

Get_Snow_Report:
   description: "Returns today's snow report for a resort"
   inputs:
      resort: string
         is_required: True
   outputs:
      report: object
         complex_data_type_name: "c__w27SnowReport"
         is_displayable: True
   target: "apex://W27_SnowReportService"

The Lightning type is a LightningTypeBundle with two files. Its schema.json binds the type to the Report Apex class that the action returns.

{
  "title": "Snow Report",
  "lightning:type": "@apexClassType/c__W27_SnowReportService$Report"
}

Its renderer.json points to the w27SnowReport widget and maps each field of the Apex class to a widget attribute.

{
  "renderer": {
    "componentOverrides": {
      "$": {
        "definition": "@widget/c/w27SnowReport",
        "attributes": {
          "resort": "{!$attrs.resort}",
          "conditions": "{!$attrs.conditions}",
          "newSnowCm": "{!$attrs.newSnowCm}",
          "baseDepthCm": "{!$attrs.baseDepthCm}",
          "liftsOpen": "{!$attrs.liftsOpen}",
          "liftsTotal": "{!$attrs.liftsTotal}"
        }
      }
    }
  }
}

The w27SnowReport widget itself is a UiWidgetBundle. Its composition file lays out HXL components and binds them to those attributes. Here’s an excerpt: the header, the lifts progress bar, and a button that sends a follow-up message to the agent.

{ "definition": "tile/text", "attributes": { "text": "{!$attrs.resort}", "variant": "h2" } },
{ "definition": "tile/badge", "attributes": { "label": "{!$attrs.conditions}", "variant": "success" } },
{ "definition": "tile/progress",
  "attributes": { "label": "Lifts open", "value": "{!$attrs.liftsOpen}", "max": "{!$attrs.liftsTotal}", "size": "md" } },
{ "definition": "tile/button",
  "attributes": {
    "label": "Show lift hours",
    "actions": { "click": [
      { "definition": "action/sendMessage", "attributes": { "content": "What are the lift hours today?" } }
    ] }
  } }

Here’s the result in the Agentforce Builder preview. The action returns structured data, and the agent shows it as an interactive card instead of plain text.

To try it, turn on Headless Experience Layer Settings in Setup, and deploy the widget and the Lightning type with sf project deploy start. To use the same widget in Claude or Slackbot, add the action as a tool on a custom MCP server. You can also explore components in the HXL Playground.

Salesforce MCP updates

Model Context Protocol (MCP) now works in both directions on Salesforce, through Salesforce Hosted MCP Servers and Agentforce. Your Agentforce agents can call MCP tools, and external AI clients can call your agents as MCP tools. Here’s what’s new.

Expose your Agentforce agents as MCP tools

Make an Agentforce agent available to any MCP client, such as Claude, ChatGPT, or Cursor, by adding it as a tool on a custom MCP server. The external client sends a request, and your agent handles it with its own instructions, actions, and knowledge sources. Every call runs as the authenticated user, so sharing rules, field-level security, and Einstein Trust Layer policies still apply.

To expose an agent:

1. In Setup, go to Integration > Salesforce MCP Servers and open your custom server.
2. Add a tool, and select Agentforce Agent as the backing type.
3. Choose the agent, then give the tool a name and a description.
4. Publish the server.

The agent’s required inputs become the tool’s parameter schema. Only agents built with the new Agent Script Builder can be exposed, so upgrade legacy agents first. 

Tip: External models choose tools based only on the name and description. Make each tool task-specific. For example, one sales agent can back a “Schedule Customer Meeting” tool and a “Forecast Deal” tool instead of a single generic “Sales Agent” tool. Update the description whenever the agent’s instructions change.

Add MCP server tools to your Agentforce agents

Going the other way, you can now add AgentExchange MCP server tools to an agent directly in Agentforce Builder. The Actions modal lists MCP server tools next to standard agent actions. Use the MCP Server Tools filter to find them quickly.

Two related updates make the right server easier to find and manage:

• Agentforce Registry: Each MCP server on AgentExchange has its own card that shows its tools and the solutions it belongs to. From Setup, open Agentforce Registry, select Registered MCP Servers, and click New+ to open AgentExchange and browse server cards.
• API Catalog: Activate Salesforce hosted MCP servers for Agentforce and supported external MCP clients, and register external MCP servers, including MuleSoft.

Automate Marketing Cloud Engagement with 40 new MCP tools

The Marketing Cloud Engagement MCP server adds 40 tools, so your AI agent can handle more day-to-day operations in natural language. New tools create and run Automation Studio activities, manage campaigns and Content Builder folders, upsert bulk data, query data extensions, erase contacts, and retrieve email tracking events.

Salesforce CLI updates

Salesforce CLI ships every week, so a lot has landed since Summer ’26. Here are five updates worth acting on now.

Move off the temporary secrets workaround

Commands such as org display and org list --json no longer print access tokens, SFDX auth URLs, or passwords. The SF_TEMP_SHOW_SECRETS=true workaround that restores the old output goes away on October 28, 2026. When a script needs a secret, ask for it explicitly.

sf org auth show-access-token --target-org my-org
sf org auth show-sfdx-auth-url --target-org my-org
sf org auth show-user-password --target-org my-org

Check your CI jobs now. A script that reads accessToken from org display --json gets [REDACTED] instead of a token, and the failure shows up later as a 401 error.

Scaffold async Apex with built-in best practices

New Batchable and Queueable values for the --template flag generate async Apex that follows platform best practices.

sf template generate apex class --name ProcessAccounts --template Batchable
sf template generate apex class --name SendEmail --template Queueable

The Batchable template uses a typed scope, an inline SOQL query, and Database.RaisesPlatformEvents. The Queueable template attaches a Finalizer, so your post-job logic runs even after an unhandled exception.

public with sharing class SendEmail implements Queueable, Finalizer {

    public void execute(QueueableContext context) {
        System.attachFinalizer(this);
        // TODO: implement job logic here
    }

    public void execute(FinalizerContext context) {
        if (context.getResult() == ParentJobResult.UNHANDLED_EXCEPTION) {
           // handle failure
        }
    }
}

Control Apex debug logs from the command line

Set the debug log level when you run anonymous Apex. Use --debug-level for a predefined level, or --category-level for per-category control.

sf apex run --file test.apex --debug-level DETAIL
sf apex run --file test.apex --category-level Apex_code=FINEST --category-level Db=FINE

New apex trace commands to create, list, and delete trace flags are coming next in the release candidate.

Set up scratch orgs for realistic testing

Assign a role to a new scratch org user with roleDeveloperName in the user definition file.

{
  "Username": "w27.presenter@winter27demos.example",
  "LastName": "Presenter",
  "Email": "w27.presenter@winter27demos.example",
  "profileName": "Standard User",
  "roleDeveloperName": "W27_Demo_Presenter"
}

To let Apex tests send email to unverified domains, enable enableSubstituteFromAddress in your scratch org definition file.

{
  "settings": {
    "emailAuthorizationSettings": {
      "enableSubstituteFromAddress": true
    }
  }
}

Skip the source-tracking scan on large projects

When your org is already in sync with your project, such as an org pre-seeded with your metadata, set SF_SOURCE_TRACKING_ASSUME_SYNCED to skip the local scan before deploys and retrieves. On very large projects, this can save some time.

export SF_SOURCE_TRACKING_ASSUME_SYNCED=true
sf project deploy start --target-org my-org

Tip: Use it with extra care. If the org isn’t really in sync, it drifts further out of sync.

Also new: the api request rest and api request graphql commands are generally available, and Salesforce CLI now requires Node.js 22 or later. See the Salesforce CLI release notes for every command and flag.

Salesforce Platform API updates

Winter ’27 ships API version 68.0. Two changes need action from integration owners now, and two make everyday API work easier.

Assign Use Any API Auth before December 1, 2026

Beginning December 1, 2026, every user who authenticates with SOAP API login() needs the Use Any API Auth user permission. This applies to all orgs. Users without it get an error. Test the change in advance with the release update in Setup.

This is a step toward the bigger change. SOAP login() in API versions 31.0 through 64.0 retires in Summer ’27. Move those integrations to OAuth with external client apps.

Plan for the retirement of API versions 31.0 through 40.0

SOAP API, REST API, and Bulk API versions 31.0 through 40.0 are being retired. For REST, this covers every URI under /services/data/vXX.X/.

• Summer ’27 (deprecation): These versions stop getting security updates and bug fixes.
• Summer ’28 (retirement): Calls to these versions fail.

Search your integrations, scripts, and middleware for hard-coded versions in this range, and move them to a current version.

Use latest instead of a numbered REST API version

Replace the version segment in a REST API URI with latest. Salesforce routes the request to the most recent version that your org supports. To see which version latest resolves to, call the List Available REST API Versions resource.

sf api request rest "/services/data/latest/sobjects/Account" --target-org my-org

In our Winter ’27 org, latest resolved to v68.0. Use it for scripts and internal tools. Keep a pinned version for production integrations that depend on a specific contract.

Monitor composite API requests with EventLogFile

Query the EventLogFile object for the new CompositeApi and CompositeApiSubrequest event types. You get details for each composite and composite graph request, and for each subrequest. That helps when a composite call succeeds overall but one subrequest fails.

SELECT EventType, LogDate, LogFileLength
FROM EventLogFile
WHERE EventType IN ('CompositeApi', 'CompositeApiSubrequest')
ORDER BY LogDate DESC

LWC updates

Winter ’27 brings two Lightning Web Components (LWC) features to general availability and fills a few gaps for state managers and console apps. Upgrade your components to LWC API version 68.0 to pick up the latest behavior. According to the release notes, version 68.0 has no version-specific changes, so it’s an easy upgrade.

Write logic in templates with complex template expressions (GA)

You no longer need a getter just to join strings, count items, or pick a CSS class. Write a subset of JavaScript directly in the template with template expressions. Template expressions require API version 66.0 or later.

<template>
    <p>{`Hello, ${firstName} ${lastName}!`}</p>
    <p>{isLoggedIn ? 'Welcome back!' : 'Please log in'}</p>
    <p>Theme: {user?.profile?.settings?.theme ?? 'default'}</p>
    <p>In-stock: {items.filter(item => item.qty > 0).length} of {items.length}</p>
    <ul>
        <template for:each={items} for:item="item">
            <li key={item.name} class="{item.qty > 0 ? 'slds-text-color_success' : 'slds-text-color_error'}">
                {item.name} ({item.qty})
            </li>
        </template>
    </ul>
</template>

Keep these rules in mind:

• Quote attribute expressions: The compiler requires double quotes around an expression in an attribute value, as in class="{...}".
• Keep expressions simple: You can’t use this, new, or function declarations in an expression.
• Iterate over expressions: for:each accepts a quoted expression that returns an array, such as for:each="{items.filter(item => item.qty > 0)}". Each item still needs a unique key.

Use third-party web components with lwc:external (GA)

Use an existing third-party web component library in LWC without rewriting it or wrapping it in an iframe. Load the library, then add lwc:external to the custom element so it renders as a native web component.

Our example uses w27-rating-stars, a plain, framework-free custom element packaged as an IIFE and uploaded as a static resource named w27RatingStars. It knows nothing about LWC. It reads value and max attributes and fires a standard rate event. In your LWC, load the static resource and render the element with lwc:external.

<template>
    <template lwc:if={libraryLoaded}>
        <w27-rating-stars lwc:external value={rating} max="5" lwc:spread={starProps} onrate={handleRate}>
        </w27-rating-stars>
    </template>
</template>

import { LightningElement } from 'lwc';
import { loadScript } from 'lightning/platformResourceLoader';
import RATING_STARS from '@salesforce/resourceUrl/w27RatingStars';

export default class ExternalComponent extends LightningElement {
    rating = 4;
    starProps = { 'data-qa': 'product-rating' };
    libraryLoaded = false;

    async connectedCallback() {
        await loadScript(this, RATING_STARS);
        this.libraryLoaded = true;
    }

    handleRate(event) {
        this.rating = event.detail.value;
    }
}

Note: Third-party web components require Lightning Web Security. Load libraries as IIFE or UMD bundles, because loadScript doesn’t support ES modules. On an lwc:external element, LWC passes values as attributes by default and sets properties only when the custom element defines them.

Here’s the w27-rating-stars component rendered inside a Lightning web component.

Refresh state manager data with refresh()

Some state managers serve data without a single record ID, such as related list records. You can now call refresh() on these managers to pull fresh data after an update. You don’t need to reload the page or create a new manager. Ensure the current status is loaded before calling it. The status remains loaded during execution, and the returned promise resolves once data populates with the latest results.

import { LightningElement, api } from 'lwc';
import relatedListRecords from 'lightning/stateManagerRelatedListRecords';

export default class OpportunityList extends LightningElement {
    @api recordId;
    related = relatedListRecords({
        parentRecordId: undefined,
        relatedListId: 'Opportunities',
        fields: ['Opportunity.Name']
    });

    connectedCallback() {
        this.related.value.setParentRecordId(this.recordId); // load the Account's Opportunities
    }

    async handleRefresh() {
        const sm = this.related.value;
        if (sm.status === 'loaded') {
            await sm.refresh(); // rejects if the status isn't loaded
        }
    }
}

Note: status, data, and refresh() live on related.value, not on related.

Apex updates

Winter ’27 gives Apex more room to work and better ways to test and inspect your code. Here are the highlights, with examples.

Handle larger payloads with higher heap limits

The Apex heap limit increases from 6 MB to 10 MB for synchronous transactions and from 12 MB to 25 MB for asynchronous transactions. The new limits are turned on automatically. Deploying from a Winter ’27 sandbox to a Summer ’26 production org? In the sandbox, open Apex Settings in Setup and select Enforce the Summer ’26 Apex heap limit until production upgrades.

Test real callouts with Apex integration tests (Developer Preview)

Unit tests can’t make real callouts, so a mock can hide a broken named credential or payload. Integration tests let you call the real service from a scratch org. They aren’t available in production orgs or sandboxes, and they don’t count toward code coverage. Turn on the ApexIntegrationTests feature in your scratch org definition file, then annotate the class and its test methods with @IntegrationTest.

@IntegrationTest
public with sharing class W27_ExternalServiceIntegrationTest {
    @BeforeClass
    static void setup() {
        insert as user new Account(Name = 'W27 PaymentTestAccount');
    }
    @IntegrationTest
    static void testExternalServiceCallout() {
        Account a = [SELECT Id FROM Account WHERE Name = 'W27 PaymentTestAccount' WITH USER_MODE LIMIT 1];
        HttpRequest req = new HttpRequest();
        req.setEndpoint('callout:W27_Echo/get?status=verified&account=' + a.Id);
        req.setMethod('GET');
        HttpResponse res = new Http().send(req);
        Assert.areEqual(200, res.getStatusCode());
        Assert.isTrue(res.getBody().contains('verified'));
    }
    @TearDown
    static void tearDown() {
        delete [SELECT Id FROM Account WHERE Name = 'W27 PaymentTestAccount'];
    }
}

Integration tests don’t roll back data, so clean up in @TearDown. It runs after each test method, so with several methods, delete only per-method data there. Only one integration test class can run per org at a time, and runs are asynchronous only. Run them with sf apex run test, without --synchronous. If you register Test.setMock(), the mock still wins.

Compare two fields in SOQL with FORMULA() (Beta)

Compare fields directly in a WHERE clause with FORMULA() instead of creating a formula field just for a query. FORMULA() requires API version 68.0 and isn’t available in production orgs.

List<Opportunity> openBalances = Database.query(
    'SELECT Name, Amount_To_Pay__c, Amount_Paid__c FROM Opportunity ' +
    'WHERE FORMULA(\'Amount_To_Pay__c - Amount_Paid__c\') > 0 ' +
    'WITH USER_MODE ORDER BY Name'
);

Prevent field name collisions in managed package queries

If a subscriber creates a field with the same API name as a field in your managed package, dynamic SOQL in your package can resolve the wrong field. Build a Database.QueryOptions object with withExplicitNamespace(true), and bind it with a SET OPTIONS clause. For details, see Prevent Field Name Collisions in Managed SOQL Queries.

Database.QueryOptions options = Database.QueryOptions.builder()
    .withExplicitNamespace(true)
    .build();
List<SObject> rows = Database.queryWithBinds(
    'SELECT Id, Name FROM Opportunity WHERE Name LIKE :prefix LIMIT 5 SET OPTIONS :options',
    new Map<String, Object>{ 'prefix' => 'W27%', 'options' => options },
    AccessLevel.USER_MODE
);

Note: Put SET OPTIONS after the other clauses, including WHERE, ORDER BY, LIMIT, and OFFSET. Only FOR UPDATE can follow it.

Look up Apex types with the Apex Symbol API (Beta)

The Apex Symbol API is a Tooling API resource that returns the same type information the Apex compiler uses, for built-in, custom, packaged, and dynamic types. Use it to power code completion or to ground a coding agent before it writes Apex. Set category to builtin, database, or dynamic, and narrow the results with namespace and name. The API handles one request per org at a time.

sf api request rest "/services/data/v68.0/tooling/symbols?category=builtin&namespace=Database&name=QueryOptionsBuilder" --target-org my-org

Page through Data 360 objects with Apex cursors (Beta)

Apex cursors now work with Data 360 Data Model Objects (DMOs). Fetch any slice of a large result set, forward or backward, without Batch Apex. In one of my orgs with Data 360, the same pattern pages through more than 1.4 million rows successfully.

Database.Cursor cursor = Database.getCursor(
    'SELECT device_id__c, event_ts__c, power_draw_w__c FROM Radiant_Reading__dlm ORDER BY event_ts__c DESC'
);
Integer total = cursor.getNumRecords();
List<SObject> lastPage = cursor.fetch(Math.max(total - 50, 0), 50); // jump straight to the end

DMO queries can consume Data Services credits from your Data 360 subscription. Track usage with Limits.getDataCloudCursors() and Limits.getDataCloudCursorRows(). Cursors expire 24 hours after you create them.

More Apex updates

• Test Discovery API: Filter results with the testLevel parameter, such as RunLocalTests. In API version 68.0, testLevel replaces showAllMethods.
• Recompile only invalid Apex: In Setup, use Compile only invalid classes or Compile only invalid triggers instead of recompiling the whole org. To get the errors programmatically, call the Tooling API apexCompileResults resource.
• Old API version warnings: The compiler now warns about classes and triggers saved at API versions 9.0 through 19.0, which will be retired. Move them to API version 20.0 or later.
• Elastic limits for Batch Apex (Beta): Elastic limits now cover Batch jobs, in addition to Queueable jobs and future methods. Jobs keep running above the rolling 24-hour async limit, and you can test this in non-production orgs.

Agentforce monthly updates

Agentforce ships updates every month, and the August and September updates arrive with Winter ’27. This round gives Agent Script a lot of new language features. It also makes multi-agent solutions generally available and simplifies how you move agents between orgs.

Write more expressive agents with new Agent Script language features

Agent Script now handles more logic without an extra action or a prompt workaround.

• New expression functions: lower(), upper(), to_json(), from_json(), and json_path(obj, path, default).
  
• else if chains: Branch on more than two conditions. Nested if statements and elif still aren’t supported.
• New system variables: @system_variables.current_connection and @system_variables.current_modality tell your agent where and how it’s talking to the user.
• Deterministic escalation: A top-level escalate statement hands the conversation to a human when a condition is met. The example below uses each of these features.

before_reasoning:
   set @variables.tier = upper(@variables.tier_input)
   set @variables.first_sku = json_path(from_json(@variables.order_json), "$.items[0].sku", "none")
   if @variables.score >= 90:
      set @variables.band = "high"
   else if @variables.score >= 70:
      set @variables.band = "medium"
   else:
      set @variables.band = "low"
reasoning:
   instructions: ->
      | Recent tags: {!@variables.recent_tags[0:2]}. You're on {!@system_variables.current_modality}.
after_reasoning:
   if @variables.needs_human:
      escalate

Format action output per connection

Tell your agent exactly how to format an action’s output on each connection. Add a when @connection.<name> block to the action, and pick a response format with render. The new built-in json format sends the action’s structured output directly to the client. Add show_and_return: True to send the response and end the turn.

connection messaging:
   label: "Messaging"
subagent menu:
   reasoning:
      actions:
         get_menu: @actions.Get_Menu_For_Restaurant
            with restaurant=...
            when @connection.messaging
               render: @response_formats.json
                  show_and_return: True

The compiler checks that each format belongs to its connection. After we published the agent, the rule appeared as a messaging render rule that returns JSON and ends the turn. To shape replies with natural language instead, add connection instructions to the Messaging, Service Email, or Marketing Email connection.

Accept file uploads in agent conversations

Service and Employee agents can now accept screenshots, receipts, and PDFs on Enhanced Chat v1, Enhanced Chat v2, and Lightning Experience. Your agent can read the file, attach it to a record, or use it as context. This feature is rolling out starting the week of September 21, 2026.

Turn it on in the agent’s config block. The mode can be auto (the default), managed, disabled, or error. In managed mode, uploaded files land in @system_variables.uploaded_files, so your script decides what to do with them.

config:
   developer_name: "W27_Channels_Lab"
   file_upload:
      mode: "managed"
   runtime:
      streaming: True

The new runtime block shown here also lets you set runtime behavior, such as streaming and citations, per agent.

Delegate to specialist agents with Multi-Agent Orchestration (GA)

Multi-Agent Orchestration is generally available. Connect an orchestrator agent to specialized agents in your org, and let each agent do what it does best. Declare the specialist as a connected_subagent, then hand off to it like any other subagent.

start_agent concierge:
   reasoning:
      instructions: ->
         | Answer resort questions yourself. Hand off menu questions to the menu specialist.
      actions:
         ask_menu_specialist: @utils.transition to @connected_subagent.Menu_Specialist
            description: "Hand off restaurant menu and food questions"

connected_subagent Menu_Specialist:
   target: "agent://W27_Menu_Specialist"
   description: "Answers questions about restaurant menus"
   delegate_escalation: True

In our test example, a menu question moved from the concierge to the specialist, which called its Apex action and answered. A question about ski lift hours stayed with the concierge.

Deploy agents between orgs with simplified metadata types

Starting in API version 68.0, an agent is described by two metadata types: AiAgentDefinition and AiAgentDefinitionVersion. You no longer list every planner, plugin, Apex class, flow, and prompt template by hand. Retrieve a version with its dependencies in one command.

sf project retrieve start --metadata "AiAgentDefinitionVersion:W27_Channels_Lab#1" --root-type-with-dependencies AiAgentDefinitionVersion

In our org, this returned the agent definition, the version, its Agent Script authoring bundle, and the Apex class behind its action. Both orgs must be on API version 68.0. Until production upgrades, keep using the previous metadata types to deploy from a Winter ’27 sandbox.

Also new: Compare and merge agent versions in Agentforce Builder, and the Agentforce platform is now turned on by default. Gemini 2.5 Pro, Flash, and Flash-Lite requests are rerouted to newer Gemini models on October 20, 2026, so test your prompts now.

To see the latest Agent Script grammar, linter, and compiler, explore the open-source Agent Script repository.

Data 360 monthly updates

Data 360 ships updates as often as monthly, and changes included in Winter ’27 are generally listed under October 2026 in the release notes. Here are two key updates for developers.

Measure RAG retriever quality with advanced retriever metrics

Retrievers find the content that grounds retrieval-augmented generation (RAG). To measure one, test it in the Retriever Playground in Advanced Mode with a question and a reference answer. Data 360 now returns a context precision score. Context precision measures how well the retriever ranks relevant chunks above irrelevant ones. A higher score means the relevant chunks are at the top. The metrics panel also shows the retrieval response time and the retrieved chunks.

To track retriever quality from code, query the AI Retriever Quality Metric DMO (ssot__AiRetrieverQualityMetric__dlm). Each row holds the context precision, answer relevancy, and faithfulness scores for a retriever request, along with the user utterance and the IDs of the retrieved context. This query averages the scores for each retriever over the last seven days.

List<AggregateResult> scores = [
    SELECT ssot__RetrieverApiName__c retriever,
           AVG(ssot__ContextPrecisionScoreNumber__c) contextPrecision,
           AVG(ssot__AnswerRelevancyScoreNumber__c) answerRelevancy,
           AVG(ssot__FaithfulnessRelevancyScoreNumber__c) faithfulness,
           COUNT(Id) samples
    FROM ssot__AiRetrieverQualityMetric__dlm
    WHERE ssot__MetricCreatedTimestamp__c = LAST_N_DAYS:7
    GROUP BY ssot__RetrieverApiName__c
];

Compare these averages before and after you change chunking, the search index, or the model, so you know which change moved the score. Testing retrievers consumes credits. For details, see Billing Considerations for Testing Retrievers.

Transform zero-copy data with Python code extensions

Code extension runs your custom Python batch transforms in Data 360. Winter ’27 extends them to zero-copy data: a data lake object (DLO) backed by a zero-copy connector, or a data model object (DMO) mapped from that DLO. The connector reads the data in place on the external platform, so you skip the ingestion step and the cost of storing a copy. Your script needs no special configuration. It runs the same way on federated data as on ingested data.

Write the script with the Code Extension plugin for Salesforce CLI (Beta). The SDK hands you a PySpark DataFrame. This script reads a DMO, averages signal strength for each device, and writes the result to another DMO.

from pyspark.sql.functions import avg, count, round

from datacustomcode.client import Client
from datacustomcode.io.writer.base import WriteMode


def main():
    client = Client()

    readings = client.read_dmo("Radiant_Reading__dlm")

    signal_by_device = readings.groupBy("device_id__c").agg(
        round(avg("signal_dbm__c"), 1).alias("avg_signal_dbm__c"),
        count("*").alias("reading_count__c"),
    )

    client.write_to_dmo(
        "Radiant_Device_Signal__dlm", signal_by_device, write_mode=WriteMode.OVERWRITE
    )


if __name__ == "__main__":
    main()

Create the package, run scan to fill in the read and write permissions in config.json, and then run the script locally against your org.

sf plugins install @salesforce/plugin-data-code-extension
sf data-code-extension script init --package-dir ./radiant-script
sf data-code-extension script scan --entrypoint ./radiant-script/payload/entrypoint.py
sf data-code-extension script run --entrypoint ./radiant-script/payload/entrypoint.py --target-org my-org

A local run reads a sample of rows through the Query API and prints the output DataFrame instead of writing it, so you can test against real data safely. When the output looks right, zip and deploy the package with sf data-code-extension script deploy, and then run it from a batch data transform.

Platform development tool updates

Winter ’27 brings a new in-browser IDE, Apex performance scans from your coding agent, and region-aware routing for Agentforce Vibes.Here’s what’s new.

Write and run code in the browser with Web Console (GA)

Web Console is a browser-based IDE built on VS Code for Web and built into Salesforce, so there’s nothing to install. Open it from the Setup menu by selecting Web Console, or click Edit on an Apex class or trigger in Setup.

In Web Console, you can:

• Edit code: Edit and save Apex, and view and edit Lightning web components with Org Browser.
• Run Apex and SOQL: Run anonymous Apex scripts, and build queries with SOQL Builder and see their query plans.
• Test and debug: Run Apex tests from the Testing panel, create a trace flag, and get debug logs.
• Work with metadata: Browse, retrieve, and deploy your org’s metadata.

Apex is read-only in production orgs, so make your edits in a sandbox or other non-production org. Running queries requires the Use Any API Client user permission. See supported editions for availability.

In Winter ’27, Developer Console doesn’t appear in the Setup menu by default. To bring it back, from Setup, enter Development in the Quick Find box, select Web Console, and set Enable Developer Console to Active. If you switch back, share your reasons in the Web Console feedback repository.

Scan Apex for performance antipatterns with ApexGuru

Ask your coding agent to check Apex for performance issues with the scan_apex_class_for_antipatterns tool from ApexGuru in the Salesforce DX MCP Server. The tool works in Agentforce Vibes, Claude Code, Cursor, and other MCP clients. Turn it on with the scale-products toolset.

{
  "servers": {
    "Salesforce DX": {
      "command": "npx",
      "args": ["-y", "@salesforce/mcp", "--orgs", "DEFAULT_TARGET_ORG", "--toolsets", "scale-products"]
    }
  }
}

ApexGuru also finds exact and near-duplicate Apex code, ranked by how many characters you can remove. From Setup, open Scale Center, go to Scale Insights, and click ApexGuru Insights to review the Code Duplicates recommendations. ApexGuru runs in production and Full Copy sandbox orgs, and it’s included at no extra cost for Unlimited Edition, Signature Success Plan, and Scale Test customers.

Keep Agentforce Vibes requests in your org’s region

Route Agentforce Vibes AI requests to the model endpoint closest to your Salesforce org, instead of to the United States by default. When geo-aware routing is on, the model picker shows only the models available in your org’s region. To turn it on, from Setup, enter Agentforce Vibes Extension in the Quick Find box, and turn on Enable Geo-Aware Routing for this Org. Data 360 must be turned on first.

Scratch orgs don’t inherit this setting, so add it to your scratch org definition file.

{
  "settings": {
    "agentforceForDevelopersSettings": {
      "agentforceForDevelopersGeoAwareOptIn": true
    }
  }
}

By default, a request falls back to the United States when no model is available in your region. To return an error instead, in Einstein Setup, turn on Enable In-Region Model Request Only. This setting doesn’t yet apply to Anthropic and Gemini models.

Conclusion

Winter ’27 is the release that makes Salesforce truly headless. Every major capability, including data, automation, grounding, and agents, is now reachable from a CLI, an API, your IDE, or an autonomous AI agent, with security enforced by default. With the Headless Experience Layer, the UI you build once rendered in Lightning Experience, ChatGPT, Claude, and Slackbot.

The best way to get ready is to spin up a sandbox, scratch org or a Developer edition org and try these features before they reach production. Have questions, or want to share what you’re building? Join the conversation in the Salesforce Developers Trailblazer Community, or connect with us on the Salesforce Developers channels.

More Winter ’27 learning resources

• Read the official release notes
• Join the Salesforce Developers Trailblazer Community group to connect with the global developer community
• Join the Release Readiness Trailblazers Community group to get early access to release information and discuss changes with other developers

About the author

Mohith Shrivastava is a Principal Developer Advocate at Salesforce with 15 years of experience building enterprise-scale products on the Salesforce 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 The Salesforce Developer’s Guide to the Winter ’27 Release appeared first on Salesforce Developers Blog.

A lot of people using Salesforce would rather talk than type. Agentforce Voice lets an Agentforce agent hold a spoken conversation, and it is available today. If you have already built a text agent, you can reach those people without starting over.

Voice does add a few new challenges. Once an agent takes spoken input, things can break. When a user says “async”, the agent can receive it as “a sink.” A reply that looks fine on screen can sound robotic out loud. These problems are easy to miss until a real conversation goes wrong.

This post covers key best practices for voice-enabling Agent Script agents, using one small Agent Script as an example. It walks through what it takes overall, what your org needs first, how to add the voice settings to your script, and how to write instructions for the ear.

What does it take to voice-enable an Agent Script agent?

It takes two steps, and not much else. The first step, configuring the agent for voice, is org setup plus a few settings: you turn on voice in your org, then add blocks that connect the agent to a voice channel and pick its voice. The second step, adjusting how it speaks, is instructions: a reply read out loud follows different rules than one read on a screen. Everything else stays the same. You keep the same personality, the same goal, and most of the same instructions.

Our example is a Rubber Duck Debugger agent. It is a debugging buddy that helps developers find bugs by asking one question at a time, instead of just giving the answer. It comes in two versions: a plain text version and a voice version tuned for speaking. This table shows what changes between them:

The screenshot below shows the instructions side by side: the text version on the left, and the spoken-style version on the right. Notice how the spoken version adds transcript repair and spells symbols out in words. 

What does my org need before I can use voice?

Before you write any voice code, there is one thing to check in your org that will save you from following this entire post and then hitting a wall at deploy. The voice version only works in a Salesforce org where Agentforce Voice is turned on. That is org setup, and a script cannot do it for you.

An admin configures Agentforce Voice in Setup. See the Agentforce Voice product page for what it can do. Agentforce Voice runs on Salesforce Voice with Telephony Providers (formerly Service Cloud Voice), so the voice connection can be a browser voice preview, or full phone support through Amazon Connect or a partner provider.

Want to check quickly whether your org is already set up? Open any agent in Agentforce Builder. In the Explorer on the left, click the plus button (+) next to Connections, choose Add Connections, and search for Telephony. If it does not show up, your org is not configured for voice yet.

Heads up: As of this writing, a free Developer Edition org does not include Agentforce Voice. It includes the licenses, but it does not show the full Agentforce Voice setup, so you cannot turn on a voice connection there.

How do I add voice settings to an Agent Script agent?

With voice turned on in your org, the next step is the code. Three blocks turn a text agent into a voice agent, and they also let you pick the voice model and persona right in the script. Keeping them in the script means the voice setup travels with the recipe, instead of living in a bunch of clicks in the UI.

Block 1: Set the language.

language:
   default_locale: "en_US"

The top-level language block sets the language the agent replies in. Voice mode only works with certain languages, so pick one you know is supported. It is also required once you add voice: without it, the agent uses your org’s default language, and if that language is not supported, Agentforce Builder warns you about it. To use more than one language, see the LanguageSettings recipe.

Block 2: Connect to a voice channel.

connection telephony:
   adaptive_response_allowed: True

The connection telephony block is what actually makes it a voice agent. Without it, you just have a text agent with short instructions. This block is the one that needs voice turned on in your org, since it points to the telephony connection you checked for earlier.

Block 3: Pick the voice model and persona.

modality voice:
   language:
      default_locale: "en_US"
   outbound:
      persona_id: "74752e92d40e"
      model:
         id: "eleven_flash_v2"
   inbound:
      filler_words_detection: True

The modality voice block picks the voice model and the persona that speaks your agent’s replies. It has three parts:

• outbound is how the agent speaks. persona_id is the voice, and model.id is the voice model. Here we use eleven_flash_v2, a lower-latency English model. Each language has a default model, so you can leave model out and get the default, but setting it lets you pick a faster model, with finer control over speed and stability (Flash), or a Japanese voice (Kotoba). At the time this post was written, Agentforce Voice supports ElevenLabs v3 Conversational (eleven_v3_conversational), ElevenLabs Flash v2.5 (eleven_flash_v2_5), ElevenLabs Flash v2 (eleven_flash_v2, English only), and Kotoba (kotoba, Japanese).
• inbound is how the agent listens. filler_words_detection helps it handle “um” and “uh” in what it hears.
• language sets the locale for the voice, and this one matters more than it looks. You do not need to memorize a persona_id. Each model has a voice catalog you copy one from.

You may have noticed language appears twice: once at the top level and once inside modality voice. That is not a mistake. You need both. The top-level block sets the language the agent replies in; the nested one sets the language for the voice. The nested block is also what makes the persona_id work: a persona belongs to a specific model and language, so without a language inside modality voice, the persona has nothing to resolve against and the voice quietly falls back to the default.

To find a persona_id in a model’s catalog, or to read more about voice models, see Voice Catalog for Agentforce Voice.

Set the voice model in the Script view. The Canvas view does not expose a voice-model selector.

A legacy format for modality voice uses a flat voice_id with outbound_speed, outbound_stability, and outbound_similarity. It still works, but it cannot pick a voice model, so to choose one, use the model structure above.

How do I write agent instructions for voice?

A listener cannot reread a sentence. That one fact shapes every voice instruction you write. The spoken debugging subagent keeps the same job as the text version, but its instructions field is written in three parts.

Part 1: Keep the same rubber-duck role.

| You are the developer's rubber duck, talking with them out loud.
  Help them discover the bug on their own instead of handing over the fix.

This is the same job as the text version. The agent guides developers to the bug instead of handing over the fix. Voice does not change the personality or the goal, so this part barely changes.

Part 2: Repair the speech-to-text transcript.

| Their words reach you as speech-to-text, so technical vocabulary is
  often garbled - "agent for script" means "Agent Script", "returns on
  the even" means "returns undefined", "a sink" means "async". Read every
  message charitably in a software-debugging context and quietly repair
  obvious mishears.

The agent never receives raw audio. Instead it receives a speech-to-text (STT) transcript, and that transcript is not always right. Technical words break first; “async” can arrive as “a sink.” This is the part most teams skip. It tells the agent to expect the noise and quietly fix obvious mishears from the context. Think of it as a safety net: most transcripts are fine, but when a word gets garbled, the agent recovers instead of getting confused.

Part 3: Speak for the ear.

| Keep replies short and easy to follow by ear: speak in full sentences,
  never read code or markdown aloud, and say symbols in words (for example
  "index plus plus" for "i++"). Guide with simple questions like "What did
  you expect to happen?" or "What did you change last?", and stay warm and
  playful.

Out loud, formatting is just noise. The agent should never read code or markdown aloud, and it should say symbols in words, so index++ becomes “index plus plus.” Full sentences help too, since a listener cannot piece together a fragment. These small changes are the difference between a reply that sounds natural and one that sounds like a screen reader.

Notice what did not change across all three parts. The personality and the goal are the same as the text version. You are only changing how the agent talks and how it reads what it hears, not rebuilding it.

Try it yourself

The best way to learn this is to deploy the recipe yourself. Clone the Agent Script Recipes repo and then deploy the voice agent:

sf project deploy start --source-dir force-app/main/02_actionConfiguration/voiceAgent

Then open Agentforce Studio, start a voice chat, and describe a bug out loud. Notice how the voice version keeps each reply short and recovers when a word gets misheard.

Conclusion

Adding voice to an Agent Script agent is not a rewrite. First, make sure your org has Agentforce Voice turned on, or the voice version will not deploy. Then add the language, connection telephony, and modality voice blocks so the voice setup lives in your script, and pick the voice model and persona right there in the code. Finally, write the instructions for a listener: short replies, no code read aloud, symbols said as words, and one line that fixes misheard terms. That is what keeps a spoken conversation on track. Put the text and voice versions side by side and the pattern is clear: it is the same agent, just tuned for the ear. Have questions? Ask on the Trailblazer Community or reach out to @SalesforceDevs.

Resources

• Agent Script Recipes (GitHub)
• Agentforce Voice
• Agent Script (Agentforce Developer Guide)
• Agentforce Developer Guide
• Salesforce Developers YouTube

About the author

Alex Martinez was part of the MuleSoft Community before joining Salesforce as a Developer Advocate. Today they help developers build with Agentforce and MuleSoft. You can find more of their content on ProstDev, a site that shares MuleSoft tutorials and walkthroughs. Follow Alex on LinkedIn or in the Trailblazer Community.

The post Agentforce Voice for Agent Script: Voice-Enabling Best Practices appeared first on Salesforce Developers Blog.

If a text snippet lacks proper context when retrieved from the vector database, your agent cannot generate an accurate response. This is the structural reality of retrieval-augmented generation (RAG): garbage in, garbage out.

This post shows how pro-code chunking for Data 360 search indexes using Data 360 Code Extension functions can be used to address three common chunking failures: fragmented data tables, multispeaker dialogue, and exposed personally identifiable information (PII). For each, it compares native chunking against custom pro-code chunking and shows the impact on agent responses.

Where native chunking falls short

Data 360 offers reliable native chunking for standard content. Mechanisms like Section-aware chunking and Semantic-based passage extraction cut documents along structural headings or thematic boundaries. They prevent sentences from splitting awkwardly and keep related paragraphs together.

However, enterprise data is rarely clean. It lives in complex multipage PDFs, regulatory records, dense tables, and multispeaker transcripts. When this data is fed into a character-count or token-length splitter, semantic continuity shatters.

How to write and deploy Code Extension functions

Note: The code examples in this post are intended to illustrate the concepts described in a simple way. They are designed for representative, happy-path examples, not for the full range of possible real-world inputs. Because the implementations rely on regular expressions (regex) and other pattern-based heuristics, they can produce both false positives and false negatives. For example, a heuristic might incorrectly classify an ordinary value as an account number or fail to recognize a valid table, speaker label, timestamp, or identifier in an unexpected format. Production-grade implementations of these functions are beyond the scope of this post.

Data 360 Code Extension functions let you deploy pro-code Python scripts natively within the Salesforce trust boundary for unstructured data pipelines where the built-in chunking behavior isn’t enough.

A function is a small, serverless-style unit that takes an input, performs a computation, and returns an output, running fully sandboxed and stateless. You author and debug it locally in your favorite IDE with the Data Custom Code SDK, deploy it through the Salesforce CLI or the UI, and wire it into your pipeline at the search index creation step. A code extension function can also call a generative or predictive model when your use case needs it. To go deeper, see the developer documentation.

How we tested

To test Code Extension custom chunking capabilities and compare them with native chunking capabilities, we evaluated three different documents. You can explore the structure of a chunking function and learn how to deploy it and run it during search index creation in the developer docs.

For each use case, we followed the same methodology:

1. Chunk the same source document via two separate paths:
   
   1. Path A (Native): The standard Agentforce Data Libraries (ADL) route with default chunking configuration
   2. Path B (Code Extension): Custom Python chunking function deployed via Code Extension
2. Query the resulting vector search indexes for Path A chunks using:
   

   SELECT Chunk__c FROM vector_search(TABLE("index_name__dlm"), 'query', 
     'SourceRecordId__c="<adl-id>/<filename>"', 100)
   

3. Query the chunks for Path B by querying the unstructured data model object (UDMO) directly:
   

   SELECT Chunk__c FROM vector_search(TABLE("index_name__dlm"), 'query', 
     'SourceRecordId__c="<adl-id>/<filename>"', 100)
   

4. Compare the chunks retrieved and evaluate what an agent would answer from each.

Use case 1: fragmented data tables

Imagine you are indexing a quarterly financial report (ABC_corp_q4_fy2025_financial_report.pdf): a 5-page PDF containing an executive summary, four dense multicolumn data tables, and forward-looking guidance.

Here are a few snapshots from the financial report document:

The Problem: Standard splitters often slice text strictly by character or token limits. Tables spanning multiple columns lose the relationship between headers and data rows. When your agent retrieves a chunk containing raw numbers, it has no column context to understand what those numbers mean.

You can solve this problem by implementing a structure-aware Python function that detects table boundaries (for example, markdown pipe tables, grid tables, and HTML tables), keeps each table as a unified block, and when a table exceeds the chunk size limit, splits it into sub-chunks with column headers repeated at the top of each sub-chunk.

Sample code

Native chunks: what you get without Code Extension

SELECT Chunk__c FROM vector_search(TABLE("ADL_ABC_Financial_index__dlm"), 
  'test something', 
  'SourceRecordId__c="1JDKd000000kADxOAM/ABC_corp_q4_fy2025_financial_report.pdf"', 100)

Here is what native chunking produced, a wall of numbers with no structural context:

Native Chunk Example 1 (Raw Data Dump):

DataCloud Pro 892 0.68 34.2 78.5 245.8 99.97 42 185 AgentForce 456 0.72 28.7 82.1 189.3 
99.95 38 162 Einstein Analytics 1,245 0.55 22.4 65.3 312.6 99.98 55 210 Flow Builder 678 
0.61 41.8 71.2 98.4 99.99 28 95 MuleSoft Connect 334 0.58 18.9 59.8 567.2 99.96 65 280 
Tableau Cloud 1,567 0.45 26.3 68.9 78.5 99.94 120 450 Commerce Cloud 289 0.71 45.2 74.6 
423.1 99.99 32 128 Marketing Cloud 1,102 0.52 31.5 72.8 198.4 99.96 48 195Service Cloud AI 
567 0.66 25.8 69.4 156.2 99.97 35 142Slack Platform 2,340 0.78 52.1 85.2 892.4 99.99 22 
78 5. Forward-Looking Guidance - Q1 FY2026 Page 4/5

Native Chunk Example 2 (Fragmented Table):

Enterprise Software 156.2 152.8 149.5 2.2 4.5 81.2 38.7 1,350 Professional Svcs 89.4 87.1 
82.6 2.6 8.2 42.1 15.3 980 Hardware & Infra 52.3 54.7 58.9 4.4 11.2 35.6 8.9 620 Emerging 
Mkts & IoT 24.8 21.2 15.4 17.0 61.0 55.4 5.2 340 Security & Compliance 13.4 11.9 9.8 12.6 
36.7 78.1 22.4 210 AI & Automation 42.1 35.8 22.4 17.6 87.9 82.5 28.1 410 Integration 
Platform 38.9 36.2 33.1 7.5 17.5 71.8 26.9 380Developer Tools 28.6 25.4 19.8 12.6 44.4 
76.3 18.2 290 Industry Solutions 52.8 48.9 41.2 8.0 28.2 69.4 24.5 450 Page 2/5

The Problem: As just one example, the numbers following “AI & Automation” (42.1 35.8 22.4 17.6 87.9 82.5 28.1 410) sit in a chunk with no column headers. What is 42.1? Revenue? A margin? A growth rate? Without the header row (Segment | Q4 FY25 Rev($M) | Q3 FY25 Rev($M) | ... | Headcount), these numbers are meaningless. Your agent cannot answer even basic questions about this data.

Code Extension chunks: structure preserved

The custom function detects table boundaries, preserves the header row, and produces structured chunks:

SELECT Chunk__c FROM ADL_ABC_Financial_MultiPage_chunk__dlm

Custom Chunk Example 1 (Executive Summary — Clean Prose):

ABC Corp - Q4 FY2025 Quarterly Financial Report (Confidential)

**Executive Summary**

Total revenue for Q4 FY2025 reached $847.3M, representing a 12% year-over-year increase 
driven primarily by growth in our Cloud Services and Data Platform segments. Operating margin 
improved to 28.4%, up from 25.1% in the prior quarter, reflecting improved cost discipline 
and scale efficiencies across all business units.

Key highlights include the successful launch of three new enterprise products, expansion into 
the APAC market with two new regional data centers, and a 15% reduction in customer churn 
attributed to our enhanced support model. The Data Platform segment showed particularly strong 
momentum with 18.1% YoY growth, driven by increased adoption of our AI-powered analytics features.

Free cash flow generation remained robust at $198.4M for the quarter, enabling continued 
investment in R&D while returning $85M to shareholders through buybacks. Our balance sheet 
remains strong with $2.1B in cash and short-term investments and a net-debt-to-EBITDA ratio of 0.8x.

Custom Chunk Example 2 (Table with Headers Preserved — Revenue by Segment):

**1. Revenue Breakdown by Business Segment**

The following table summarizes revenue performance across all business segments for Q4 FY2025, 
with year-over-year and quarter-over-quarter comparisons, gross margin, and headcount allocation:

* **Cloud Services**
* The Segment has Q4 FY25 Rev($M) of 312.5.
* The Segment has Q3 FY25 Rev($M) of 289.1.
* The Segment has Q4 FY24 Rev($M) of 261.8.
* The Segment has QoQ Growth% of 8.1.
* The Segment has YoY Growth% of 19.4.
* The Segment has Gross Margin% of 72.3.
* The Segment has Op Margin% of 34.2.
* The Segment has Headcount of 2,450.

* **Data Platform**
* The Segment has Q4 FY25 Rev($M) of 198.7.
* The Segment has Q3 FY25 Rev($M) of 185.3.
* The Segment has Q4 FY24 Rev($M) of 168.2.
* The Segment has QoQ Growth% of 7.2.
* The Segment has YoY Growth% of 18.1.
* The Segment has Gross Margin% of 68.9.
* The Segment has Op Margin% of 31.5.
* The Segment has Headcount of 1,820.

Custom Chunk Example 3 (Regional Performance — Each Region Self-Contained):

**2. Regional Performance Matrix**

Geographic revenue distribution across all operating regions, including customer metrics, 
deal economics, and satisfaction indicators:

* **APAC - ANZ**
* Revenue ($M): 52.8
* % of Total: 6.2%
* YoY Growth %: 18.4%
* Customers: 486
* Avg Deal ($K): 108.6
* NPS: 67
* Renewal %: 90.2%
* Expansion %: 114.6%

* **APAC - Japan**
* Revenue ($M): 34.2
* % of Total: 4.0%
* YoY Growth %: 21.5%
* Customers: 312
* Avg Deal ($K): 109.6
* NPS: 71
* Renewal %: 91.8%
* Expansion %: 116.2%

Impact on agent responses

User Query: “What is the YoY growth rate for the AI & Automation segment and how does its operating margin compare to Cloud Services?”

Use case 2: multispeaker dialogue

Now consider a use case in which you’re grounding your service agents on a recorded customer escalation call: a 45-minute platform migration planning session with five participants (Sarah Chen, VP of Engineering; Marcus Webb, Solutions Architect; Priya Desai, Database Lead; Tom Nakamura, DevOps Manager; Lisa Okafor, Customer Success Director).

Source document: Globex_Migration_Escalation_Call_2025_Q4.pdf

Here is a snapshot from the source document:

The Problem: Standard chunking produces massive walls of unstructured text. Speaker boundaries are lost, timestamps disappear, and topical shifts get merged into a single chunk. The result: chunks thousands of characters long where you cannot tell who said what or when.

You can solve this by using a windowed sliding dialogue mechanism with these parameters: WINDOW_SIZE = 6 turns, STRIDE = 3 turns, MAX_CHUNK_CHARS = 1500. This helps ensure that every question and its answer are almost always co-located in at least one chunk. Adjacent chunks overlap so context is virtually never orphaned.

Sample code

Native chunks: what you get without Code Extension

SELECT Chunk__c FROM vector_search(TABLE("ADL_MultiSpeakerCon_index__dlm"), 
  'test something', 
  'SourceRecordId__c="<library-id>/Globex_Migration_Escalation_Call_2025_Q4.pdf"', 100)

Native Chunk Example (Wall of Text — No Speaker Attribution):

Marcus Webb: I think yeah I th I think if you can just get a number whether it's through 
the benchmarks we ran last month or whether we have to do new load tests. If you can just 
get a number and saying if you had to migrate the legacy Oracle instances to the new 
Postgres cluster, how much data volume can we migrate within that within 72 hours or I 
guess even conservatively within 48 hours. Let's go with 48 hours because we probably 
need a buffer for rollback as well. Um do you know just just coming up with numbers of 
how much data we can migrate within a period of timewill give us some kind of uh 
measurement to know how many tenant databases we can cut over within that window or we 
can commit to Sarah Chen: Yeah,Marcus Webb: enough Sarah Chen: because the the challenge 
is like uh we'll be penalized right if we commit to uh certain migration windows if 
we're not able to meet that. 00:25:46 Sarah Chen: So this is a very crucial part of it 
wherein uh we have to kind of come up with these numbers based on uh the actual load 
testing uh given that we're not going the blue-green deployment route and we're doing it 
on a rolling basis. So I think we need that sort of analysis to be Marcus Webb: Priya,
Tom Nakamura: A Marcus Webb: is that something Kevin can can work with the DBA team 
Sarah Chen: done. Tom Nakamura: minute. Marcus Webb: on? Priya Desai: Yeah, I'll follow 
up with Kevin after this Marcus Webb: Okay, thanks.

The Problems:

1. No speaker separation: Turns from Marcus, Sarah, Tom, and Priya are mashed together in a single paragraph
2. Timestamps embedded randomly: 00:25:46 appears midsentence with no structural break
3. Questions divorced from answers: Marcus asks “can Kevin work with the DBA team?” and Priya’s answer is buried without clear attribution
4. Topic bleed: The Oracle-to-Postgres migration capacity discussion runs directly into the SLA penalty discussion with no boundary

Code Extension chunks: windowed dialogue

The custom function parses speaker turns, then creates overlapping windows:

Custom Chunk Example 1 (Clear Speaker Attribution and Overlap):

Sarah Chen: uh so I would uh so that's what my categorization of phases and milestones is. 
Phase one is more longer term more strategic where we want to land up eventually right we do 
want to uh achieve uh reach a point wherein for all the enterprise tier customers we want to 
uh have a zero-downtime migration kind of an approach uh but you know in terms of milestones 
now milestone is more like uh you know various different checkpoints that we have so our first 
milestone is towards end of Q4 when we want to

Sarah Chen: in Yeah. Yeah. So basically that was the next thing that I was going to talk 
about. If you see this these bottom uh you know tiers. So for all the enterprise tier 
customers what we offer them is guaranteed migration within the committed downtime windows 
you know uh they pay for a contractual guarantee. Whereas for all the customers who don't uh 
uh purchase the premium migration package, it'll be on a best effort basis without any 
committed timelines, no contractual SLAs, but they'll

Sarah Chen: anywhere uh we have like three layers. The first two layers talks about schema 
migration and data replication setup. We know the CDC streams are running every 5 minutes. 
The full table snapshots you know every 12 hours and we are also trying to you know make uh 
target uh to reduce the 12-hour sync window to 2 hours for Q4 and uh the development is 
complete and we are in the process of you know testing it and the third layer is where uh you 
know the the actual cutover needs to happen

Custom Chunk Example 2 (Decision and Response Together):

Tom Nakamura: correct as long as uh we are meeting their downtime window requirement they 
don't bother how we are providing Sarah Chen: might Tom Nakamura: them that migration how 
efficient

Sarah Chen: uh so I would uh so that's what my categorization of phases and milestones is. 
Phase one is more longer term more strategic where we want to land up eventually right we do 
want to uh achieve

Sarah Chen: in Yeah. Yeah. So basically that was the next thing that I was going to talk 
about. If you see this these bottom uh you know tiers. So for all the enterprise tier 
customers what we offer them is guaranteed migration within the committed downtime windows

Sarah Chen: anywhere uh we have like three layers. The first two layers talks about schema 
migration and data replication setup.

00:55:02

Sarah Chen: Yeah. Yeah. We Tom Nakamura: Hey. Uh, so our milestone it talks about in terms 
of per tenant for Q4,

Key Difference: Each chunk now contains multiple turns from the same topical exchange. The sliding window (stride of 3) helps ensure that a question asked in one chunk is always paired with its answer. Speaker names are preserved as structural anchors.

Impact on agent responses

User Query: “What is the committed downtime window for enterprise tier customers during the database migration?”

Use case 3: PII masking and regulatory cleansing

In this use case, you’re operating in a regulated sector (for example, healthcare, banking, or public sector) where internal identifiers must be sanitized before ingestion into a vector database that agents will query.

Source document: Sample_PII_Masking_Test_Document.pdf is a five-page document with simulated clinical intake records, banking credit memos, and public sector benefits cases. It contains both standard PII and proprietary identifiers.

Here is a snapshot from the source document:

The Problem: Standard pattern recognition is not applied during chunking via the ADL route. All identifiers, standard and proprietary, pass through into the vector index unmasked.

You can address this by implementing regex-based pattern matching over the raw text inside your custom function before chunking. This cleanses SSNs, credit card numbers, phone numbers, email addresses, employer identification numbers (EINs), ICD codes, and other industry-specific formats on-the-fly. The data is sanitized before it ever reaches the chunk data model object (DMO).

Sample code

Native chunks: all PII exposed

SELECT Chunk__c FROM vector_search(TABLE("ADL_PIIMasking_index__dlm"), 
  'test something', 
  'SourceRecordId__c="1JDKd000000kAE7OAM/Sample_PII_Masking_Test_Document.pdf"', 100)

Native Chunk Example 1 (Healthcare — Full PII Exposed):

Note: The X characters below are synthetic placeholders; they represent identifiers that are present and unmasked, not values that have already been redacted.

CONFIDENTIAL - INTERNAL USE ONLY Meridian Regional Health System Patient Intake & Clinical 
Summary - Q4 2025 Patient Demographics Standard Identifiers Patient Name: Margaret A. Thornton 
Date of Birth: 01/01/1970 Social Security Number: XXX-XX-XXXX Phone: (XXX) XXX-XXXX Email: 
m.thornton@example.com Address: 123 Main St, Anytown, IL 00000 Proprietary & 
Regional Identifiers MRN (Medical Record No.): MRH-XXXX-XXXXXX-X Internal Episode ID: 
EP.Q4.NAP.093871.TNT State HIE Patient Token: ILHIE-PKT-XXXXXXXX-XXXX Payer Member ID: 
BCBSIL-GRPXXXX-MXXXXXXX Referring Provider NPI+Loc: NPI1629384750-LOC.NAP.03 Bed Assignment 
Code: 4N-BED.217-ISO-RESP Regional Trauma Registry ID: ITRS-R5-2025-00847

Native Chunk Example 2 (Banking — All Identifiers Visible):

Credit Analysis Narrative Subject: Apex Manufacturing Solutions (CIF: CNB-CIF-2025-093871-COMM) 
requests $4.2M term loan expansion. Current exposure tracked under facility ID 
FAC-CNB-MW-2025-APEX-001. Borrower maintains primary operating account 
(DDA-CNB-MW-7741093871) with average collected balance of $847K. Guarantor Robert J. Whitfield 
(Internal KYC Profile: KYC-IND-XX-XXXX-XXXXXX, SSN:XXX-XX-XXXX) provides unlimited 
assessment net worth WA-CNB-2025-0291-WHTFLD. personalguarantee. Guarantor verified via 
internal wealth Collateral: IL. Appraisal ordered under engagement APR-CNB-2025-093871-IND 
(Appraiser Vendor ID: VND-APR-MW-0087-CERT). Environmental Phase I completed (Report ID: 
ENV-PH1-2025-APEX-093871).

Native Chunk Example 3 (Cross-System — Re-identification Risk):

Event 2: Employment Verification Timestamp: 2025-11-03T09:15:00Z Source: IL Dept of Revenue 
(System ID: SYS-ILDOR-EMPL-VERIFY) Destination: DHS Benefits (System ID: 
SYS-DHS-IL-ELIG-ENGINE) Subject: SSN XXX-XX-XXXX / DHS-IL-XXXX-XXXX-XXXXXX-XX Employer Match: 
ILDOR-EMP-2025-00-0000000-APEX Income Verified: 
3,847.00/month(PayPeriodID:PP-APEX-2025-B22) Verification Token: ILDOR-VT-2025-1103-093871-CONF

The Problem: Every sensitive identifier sits unmasked in the vector index:

• SSNs: XXX-XX-XXXX, XXX-XX-XXXX, XXX-XX-XXXX
• Credit card number: XXXX-XXXX-XXXX-XXXX
• Email address: m.thornton@example.com
• Phone number: (XXX) XXX-XXXX
• Medical record number: MRH-XXXX-XXXXXX-X
• Internal KYC profile: KYC-IND-XX-XXXX-XXXXXX
• Payer member ID: BCBSIL-GRPXXXX-MXXXXXXX
• DHS case number: DHS-IL-XXXX-XXXX-XXXXXX-XX

When your agent retrieves these chunks, it may echo PII directly back to end users, which constitutes a compliance violation under HIPAA, PCI-DSS, and many state privacy laws.

Code Extension chunks: PII masked before indexing

The custom function applies regex-based pattern matching to sanitize sensitive data before chunking:

Custom Chunk Example 1 (Healthcare — Standard PII Redacted):

CONFIDENTIAL - [SWIFT_REDACTED] USE ONLY Meridian Regional Health System Patient Intake & 
Clinical Summary - Q4 2025 Patient Demographics Standard Identifiers Patient Name: Margaret A. 
Thornton Date of Birth: 01/01/1970 Social Security Number: [SSN_REDACTED] Phone: 
([PHONE_REDACTED] Email: [EMAIL_REDACTED] Address: 123 Main St, Anytown, IL 00000 
Proprietary & Regional Identifiers MRN (Medical Record No.): MRH-XXXX-XXXXXX-X Internal 
Episode ID: EP.Q4.NAP.093871.TNT

Note the ‘[SWIFT_REDACTED]’ token replacing ‘INTERNAL’: an over-broad SWIFT-code pattern matched a plain word. Also note that certain PII,  such as names, addresses, dates of birth are not handled by the example function).

Custom Chunk Example 2 (Banking — Standard PII and Financial IDs Redacted):

Primary Contact SSN: [SSN_REDACTED] DUNS Number: 07-481-2937 Credit Card on File: 
[CREDIT_CARD_REDACTED] (Exp: 09/27) Internal & Proprietary Identifiers Relationship Manager 
ID: RM-COMM.MW.4471.SR Internal Credit Score: CNB-ICS-782-TIER2A Collateral Tracking ID: 
COLL-RE.IL.2025.093871.INDUST Loan Pipeline Position: PL-Q4.2025-MW-00291-PEND Risk Rating 
(Proprietary): RR-CNB-3B-WATCH-MOD BSA/AML Case Reference: AML-SAR.2025.MW.04471 Treasury 
Mgmt Client Code: TM-APEX-MW-4471-SWEEP

Custom Chunk Example 3 (Cross-System Events — SSN and EIN Masked):

Event 2: Employment Verification Timestamp: 2025-11-03T09:15:00Z Source: IL Dept of Revenue 
(System ID: SYS-ILDOR-EMPL-VERIFY) Destination: DHS Benefits (System ID: 
SYS-DHS-IL-ELIG-ENGINE) Subject: SSN [SSN_REDACTED] / DHS-IL-XXXX-XXXX-XXXXXX-XX Employer 
Match: ILDOR-EMP-2025-[EIN_REDACTED]-APEX Income Verified: $3,847.00/month (Pay Period ID: 
PP-APEX-2025-B22) Verification Token: ILDOR-VT-2025-1103-093871-CONF

Custom Chunk Example 4 (Public Sector — Government IDs Masked):

CONFIDENTIAL - [SWIFT_REDACTED] USE ONLY State of Illinois - Department of Human Services 
Benefits Determination & Case Management Summary Claimant Information Standard Identifiers 
Claimant Name: David R. Okonkwo Social Security Number: [SSN_REDACTED] Date of Birth: 
01/01/1980 Driver's License: O-000-0000-0000 (IL) Phone: ([PHONE_REDACTED] Agency-Specific 
& Regional Identifiers DHS Case Number: DHS-IL-XXXX-XXXX-XXXXXX-XX

What got caught and what needs custom patterns

In this test, the Code Extension function successfully redacted:

• SSNs: XXX-XX-XXXX → [SSN_REDACTED]
• Credit card numbers: XXXX-XXXX-XXXX-XXXX → [CREDIT_CARD_REDACTED]
• Email addresses: m.thornton@example.com → [EMAIL_REDACTED]
• Phone numbers: (XXX) XXX-XXXX → [PHONE_REDACTED]
• EINs: 00-0000000 → [EIN_REDACTED]
• ICD Codes: J96.01 → [ICD_CODE_REDACTED]

Proprietary identifiers that require organization-specific patterns (these passed through, demonstrating why you must extend the pattern registry for your formats):

• MRH-XXXX-XXXXXX-X — Medical record number
• BCBSIL-GRPXXXX-MXXXXXXX — Payer member ID
• DHS-IL-XXXX-XXXX-XXXXXX-XX — DHS case number
• ILHIE-PKT-XXXXXXXX-XXXX — HIE patient token

The key insight: Code Extension gives you the framework to add any pattern your organization needs. Standard numeric identifier patterns are handled by the existing sample code. Proprietary formats are added as one-line regex entries:

code here 22

Impact on agent responses

User Query: “What was the clinical pathway for the patient admitted on October 17th?”

Compliance implications

The bottom line: without Code Extension, everything goes into the vector store unmasked. With the Code Extension function, PII formats covered by the sample patterns are masked  during search index chunking, and the extensible pattern registry gives you a path to add proprietary formats as you discover them.

Conclusion

Code Extension functions are not a replacement for native chunking; they provide an escalation path when enterprise data complexity outpaces standard algorithms. Investing in pro-code chunking ensures your search indexes remain contextually rich and drive accurate Agentforce responses.

Get started with Code Extension

What are you waiting for? Start building Code Extensions today: Enable Code Extension in Data 360 setup feature manager, install the Data Custom Code SDK and the Salesforce CLI, and start building right away. To learn more:

• Check out the Code Extension function documentation.
• Watch the Extend Data 360 with Code Extension YouTube playlist.

About the authors

Jitin Mehndiratta is a Product Management Director at Salesforce working on Data 360. He focuses on enabling developers to build intelligent data pipelines that power Agentforce experiences.

Samaritha Patlori is a Product Manager for Code Extension at Salesforce Data 360. With 7+ years across engineering and product, she is currently focused on enabling developers to run custom code securely within Data 360.

The post Pro-Code Chunking of Data 360 Search Indexes for Agentforce appeared first on Salesforce Developers Blog.

Salesforce Multi-Framework (React) が GA になり、Salesforce 上で React アプリを動かせるようになりました。アプリケーションランチャーからフルページで起動するアプリとして使えるようになっていたのですが、やはり LWC のように Lightning Experience（LEX）のページに埋め込みたい ——と考える方も多いのではないでしょうか。

それを叶えてくれるのが Salesforce Microfrontend（UI Embedding） です。

• 公式ガイド（本記事の元にした情報）: Salesforce Microfrontend: Get Started

Microfrontend / UI Embedding は本記事執筆時点で Beta の機能です。今後仕様が変わる可能性があります。検証は Winter ’27 Preview のスクラッチ組織（API 68.0）で行っています。

Salesforce Multi-Framework の React などをはじめ、外部フレームワークで作った UI（UI Bundle）を、lightning-ui-embedding を介して LWC と同じようにレコードページなどへ埋め込めるようにする仕組みです。前回の記事では、React 製の UI Bundle をスクラッチ組織にデプロイして、単体で動かすところまでを試しました。

• 参考: Salesforce で React アプリをマルチフレームワークで動かす

今回はその続きとして、作った React アプリを Case（ケース）レコードページに埋め込む部分に絞って紹介します。埋め込みには lightning-ui-embedding を使い、LWC 側から React アプリへ「今開いているレコードの ID」を渡す、という連携がキモになります。

本記事の内容は、あくまで 2026年9月時点（Beta）で試した範囲の記録 です。ここで紹介する手順やコードは執筆時点で動作したものであり、正式リリース時には作法や API が変わっている可能性があります。その前提でお読みください。

今回作ったもの

題材として「Case Timeline」という読み取り専用のデモコンポーネントを用意しました。1 件のケースにひもづく複数の履歴 —— メール（EmailMessage）、ToDo（Task）、行動（Event）、ケースコメント、ケース履歴 —— を 1 本の時間軸にまとめて表示する React アプリです。

React アプリ自体の作り込み（React 19 + Vite + TypeScript + Tailwind + shadcn/ui）については前回記事の範囲なので、ここでは深追いしません。「こんな見た目のアプリを作った」という前提で読み進めてください。

全体像

埋め込みの登場人物は次の 4 つです。

Case レコードページ
  └─ caseTimelineEmbed （ラッパー LWC / 今回の主役）
       └─ <lightning-ui-embedding>  … iframe を生成
            └─ React UI Bundle（*.salesforce.app から配信）

• React UI Bundle は *.salesforce.app という専用ドメインから配信され、lightning-ui-embedding が iframe として画面に埋め込みます。
• レコードページに直接 UI Bundle を置くことはできないので、間に薄い ラッパー LWC（caseTimelineEmbed）を挟みます。
• このラッパー LWC が「どのアプリを」「どのレコードで」表示するかをアプリ側へ伝えます。

ということで本記事は、ほぼこのラッパー LWC の実装解説です。

ステップ1: 埋め込むアプリの URL を確認して信頼済み URL に登録する

iframe で外部 URL を読み込むため、信頼済み URL（CSP Trusted Site） として登録しておきます。これは公式ガイダンスに沿って [設定] の画面から登録するだけ です。

登録するには、まず埋め込むアプリの正確な URLを知る必要があります。そこで 一度、React アプリを単体でフルに開いてみます。アドレスバーに出る URL を控えます。

あとは [設定] → [セキュリティ] → [信頼済み URL] で、その URL を新規登録し、CSP コンテキストとして frame-src を有効にするだけです。

ステップ2: ラッパー LWC を作る

いよいよ本題のラッパー LWC です。まずはテンプレート（HTML）から。<lightning-ui-embedding> に src（アプリの URL）を渡すだけの、とてもシンプルな構成です。

lwc/caseTimelineEmbed/caseTimelineEmbed.html:

<template>
    <div class="ct-embed-container" style={containerStyle}>
        <!-- 読み込み失敗時のエラー表示 -->
        <template lwc:if={errorMessage}>
            <div class="slds-p-around_medium slds-text-color_error" role="alert">
                {errorMessage}
            </div>
        </template>

        <lightning-ui-embedding
            lwc:ref="embedding"
            src={embeddingUrl}
            sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-modals"
            shell-title="Case Timeline">
        </lightning-ui-embedding>
    </div>
</template>

次に JavaScript です。全体はこれだけです。

lwc/caseTimelineEmbed/caseTimelineEmbed.js:

import { LightningElement, api } from 'lwc';

// 埋め込むアプリの base URL。末尾は「変化しない」パスにする（後述）。
const BASE_URL = 'https://enterprise-fun-7452-dev-ed--c.scratch.my.salesforce.app/app/c__CaseTimeline';

// アプリ側と共有するカスタムイベント名。
// host→app: recordId を渡す / app→host: recordId の送信を要求する。
const RECORD_ID_EVENT = 'caseRecordId';
const REQUEST_RECORD_ID_EVENT = 'requestRecordId';

export default class CaseTimelineEmbed extends LightningElement {
    _recordId;
    // src はマウント後に変化させない（相対アセットを常にアプリのルート基準で解決させるため）。
    embeddingUrl = `${BASE_URL}/timeline`;
    errorMessage;

    // デザイン属性: 初期の高さ。420〜720px にクランプ。
    @api height = 520;

    @api
    get recordId() {
        return this._recordId;
    }
    set recordId(value) {
        if (value === this._recordId) return;
        this._recordId = value;
        // レコード遷移時に新しい id を送る（アプリ未接続なら無害に何もしない）。
        this.sendRecordId();
    }

    get containerStyle() {
        const h = Math.min(Math.max(Number(this.height) || 520, 420), 720);
        return `height:${h}px;`;
    }

    renderedCallback() {
        if (this._listenersAttached) return;
        const embedding = this.refs?.embedding;
        if (!embedding) return;
        this._listenersAttached = true;
        // アプリからの要求（確実）と ready（保険）、どちらでも recordId を送る。
        embedding.addEventListener(REQUEST_RECORD_ID_EVENT, this.sendRecordId);
        embedding.addEventListener('sf-embedding.component.ready', this.sendRecordId);
        embedding.addEventListener('sf-embedding.component.error', this.handleError);
    }

    disconnectedCallback() {
        this._listenersAttached = false;
    }

    // recordId を sf-embedding チャネル経由で app へ送信する。
    sendRecordId = () => {
        const embedding = this.refs?.embedding;
        if (!embedding || !this._recordId) return;
        embedding.dispatchEvent(
            new CustomEvent(RECORD_ID_EVENT, { detail: { recordId: this._recordId } })
        );
    };

    handleError = (event) => {
        this.errorMessage =
            event?.detail?.message ||
            'Case Timeline アプリの読み込みに失敗しました。時間をおいて再度お試しください。';
    };
}

そして、レコードページに配置できるようにするメタデータです。

lwc/caseTimelineEmbed/caseTimelineEmbed.js-meta.xml:

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>67.0</apiVersion>
    <isExposed>true</isExposed>
    <masterLabel>Case Timeline</masterLabel>
    <targets>
        <target>lightning__RecordPage</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightning__RecordPage">
            <objects>
                <object>Case</object>
            </objects>
            <property name="height" type="Integer" label="Height (px)"
                description="Component height in pixels (420–720)."
                default="520" min="420" max="720" />
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>

※ css ファイルは割愛

ステップ3: recordId をアプリへ渡す

埋め込みで一番のポイントが「LWC が持っているレコード ID を、iframe の中の React アプリへどう渡すか」です。

以降は 本記事執筆時点（Beta）で動いた方法 の記録です。UI Embedding はまだ Beta で、データ受け渡しの作法は今後変わる可能性があります。ここで紹介するのは「公式の仕組みの範囲内で、現時点で確実に動かせた一例」くらいに読んでください。正式リリースでは、もっと素直な方法が用意されるかもしれません。

公式の Exchange Data ガイド では、sf-embedding チャネルを通じてデータをやり取りします。用意されている口は主に 2 つです。

1. state.props … LWC が流し込む値（テーマ・ロケール・モードなど）。
2. カスタムイベント … sf-embedding チャネル越しにイベントをやり取りする口。

最初は「recordId は state.props に入ってくるのでは？」と思い、そこから取り出そうとしました。ところが実際にレコードページで中身をログに出してみると props は空（{}） で、recordId は入っていませんでした。そこでコーディングエージェントとも一緒に調べていった結果、現時点では「カスタムイベントで渡す」のが一番確実だった ——というのが、今回たどり着いた形です。

src に /timeline/{recordId} のようにレコード ID を載せる方式もあるかもしれませんが、今回は公式ガイドの手法（カスタムイベント）をベースとしました。

送るタイミングでハマった話（現時点の注意点）

もう 1 つ、送信タイミングでつまずきました。公式ガイドは「ロケールなどのデータは embedding component が ready を報告した後に送る」と案内していて、一見「LWC 側で ready を待って送れば十分」に見えます。ところが今回の構成では、うまくいきませんでした。

embedding.addEventListener('sf-embedding.component.ready', this.sendRecordId);

今回試した限りでは、LWC が ready を受け取って caseRecordId を送るタイミングと、アプリ側でそのイベントを受け取る準備が整うタイミングが、ちょうど前後してしまうことがあるようでした。アプリ側は createViewSDK() の解決を待ってからリスナーを登録するため、LWC からの通知の方が先に届くと、そのイベントを受け取れないことがあったようです。イベントは後から登録したリスナーには届かないため、そのまま取りこぼしてしまう、という状況でした。

※ このあたりは SDK 内部の挙動に関わる部分なので、あくまで今回の環境で観測した範囲からの推測としてお読みください。

そこで、送られてくる順序に左右されないよう、アプリ → LWC へ問い合わせる方式（ハンドシェイク） に切り替えました。アプリは自分のリスナーを登録し終えてから「recordId を送ってください」と LWC へ要求し、LWC がそれに応えて caseRecordId を返します。要求はリスナーの準備が整ってから送るため取りこぼしが起きにくく、今回はこの形で安定しました（ready を契機とした送信も、念のため残してあります）。

• LWC → アプリ: caseRecordId イベントで recordId を渡す
• アプリ → LWC: requestRecordId イベントで送信を要求する（dispatchEvent による app→host は公式にサポート）

LWC 側は、requestRecordId でも ready でも、どちらが来ても recordId を送り返します（前掲の renderedCallback を参照）。

アプリ（React）側の受け取り

受信ロジックはモジュール読み込み時に走る小さなストアにまとめ、app.tsx の先頭（ui-embedding の import 直後）で読み込みます。リスナーを登録したら、その場で requestRecordId を投げるのがポイントです。

src/features/timeline/hostRecordId.ts（抜粋）:

const RECORD_ID_EVENT = 'caseRecordId';
const REQUEST_RECORD_ID_EVENT = 'requestRecordId';

// モジュール読み込み時（＝アプリ起動時）にリスナーを登録する。
void (async () => {
  const { createViewSDK } = await import('@salesforce/platform-sdk/view');
  const viewSdk = await createViewSDK();

  // (1) LWCが push するカスタムイベントを待ち受ける
  viewSdk?.addEventListener?.(RECORD_ID_EVENT, (event) => {
    publish(event.detail?.recordId);
  });

  // (2) リスナーが立ったので「今 recordId を送って」とLWCへ要求する
  viewSdk?.dispatchEvent?.(new CustomEvent(REQUEST_RECORD_ID_EVENT));
})();

getUiState().state.props から取れたら良かったのですが、実際に中身をログに出して確かめたところ、レコードページでは props は空（{}）で recordId は入っていませんでした（props はテーマ・ロケール等の host-configurable inputs 用とされています）。なので recordId を運べるのは上記のカスタムイベントだけ、という結論になりました。(2026年9月時点)

app.tsx の先頭で読み込むことで、要求をできるだけ早く出せます。

import '@salesforce/platform-sdk/ui-embedding';
import '@/features/timeline/hostRecordId'; // ここで受信リスナー + requestRecordId が走る

あとは React 側のフックでこのストアを購読するだけです。埋め込みでない環境（ローカル開発）ではルートパラメータにフォールバックします。

export function useEmbeddedRecordId(): string | undefined {
  const { recordId: routeRecordId } = useParams();
  const [hostRecordId, setHostRecordId] = useState(getHostRecordId);
  useEffect(() => subscribeHostRecordId(setHostRecordId), []);
  return hostRecordId ?? routeRecordId;
}

recordId が届くまでは GraphQL クエリを投げない、というガードも入れておくと安心です。

// recordId が来るまではクエリしない（caseId が null で uiapi に弾かれるのを防ぐ）
const { data, loading, error } = useAsyncData(
  () => (recordId ? fetchTimeline(recordId) : Promise.resolve(undefined)),
  [recordId, reloadKey],
);

if (!recordId) return <NoRecordState />;

ステップ4: iframe の高さ（無限に伸びる問題）

lightning-ui-embedding には iframe の高さをコンテンツに合わせるオートリサイザーが入っています。ここで、iframe の中のアプリが 100vh や min-h-screen（ビューポート基準の高さ）を使っていると、

「オートリサイザーが iframe を広げる → 中身の 100vh も一緒に広がる → さらにリサイザーが広げる…」

というループになり、縦にどこまでも伸び続けます。

対策はシンプルで、iframe 内でビューポート基準の高さを使わないことにしました。

/* 修正前: ビューポート高さがリサイザーにフィードバックして無限に伸びる */
html, body, #root { @apply min-h-screen; }

/* 修正後: コンテンツ基準の高さにする */
html, body, #root { height: auto; min-height: 0; }

LWC 側の初期高さは LWC のデザイン属性（height、420〜720px にクランプ）で調整できるようにしてあります。

ステップ5: レコードページに配置して動作確認

デプロイしたら、Case レコードページを Lightning アプリケーションビルダーで開き、コンポーネント一覧から 「Case Timeline」 をドラッグして配置します。必要なら右側のプロパティで高さ（Height）を調整します。

保存してレコードページを開くと、そのケースの履歴が 1 本の時間軸に並んで表示されます。

おわりに

Microfrontend / UI Embedding を使うと、React で作った UI を、レコードページの文脈（recordId）を受け取りながら埋め込めます。今回試してみて分かったことを振り返ると、

• 埋め込みは lightning-ui-embedding に src を渡すだけの薄いラッパー LWC で実現できる
• アプリのオリジンは、一度アプリを単体で開いて確認し、[信頼済み URL] に画面から登録しておく
• recordId は、現時点（Beta）では sf-embedding チャネルのカスタムイベントで渡すのが素直そう。ready 待ちだけだと取りこぼすことがあり、アプリ → LWC の要求（requestRecordId）を挟むと安定した
• 細かいハマりどころは「src は固定 base URL にする」「iframe 内で 100vh を使わない」あたり

あくまで Beta 時点での一例なので、正式リリースでは作法が変わっているかもしれません。とはいえ、LWC と React アプリを橋渡しする感触はつかめました。今後の進化が楽しみです。

参考資料

• Salesforce Microfrontend: Get Started（本記事の元にした公式ガイド）
• Salesforce Microfrontend: Exchange Data ガイド
• 前回記事: Salesforce で React アプリをマルチフレームワークで動かす

The post Salesforce Microfrontend (UI Embedding) で React アプリの埋め込みを試す appeared first on Salesforce Developers Blog.

※本記事は2026年6月16日に米国で公開された Build a Decision-Scoring Skill for Any Agentの抄訳です。本記事の正式言語は英語であり、その内容および解釈については英語が優先されます。

プロジェクトには技術的な判断がつきものですが、その時点で文書化されることはほとんどありません。後になって誰かが「なぜこの実装を選んだのか」を知りたくても、その根拠はSlackのスレッドや会議中の記憶、あるいはすでにチームを離れているかもしれない人の頭の中にしか残っていないのです。

AIを使えば、プロジェクトに重要なコンテキストの喪失を防ぎ、アーキテクチャーの原則を厳密に適用できます。意思決定スコアリングスキルを実装することで、プロジェクトチームは、コーディングエージェントをエンジニアリング設計のガードレールとして活用できます。この記事では、幅広い要件の聞き取りから始めて検証可能な形で意思決定を記録する、構造化されたフレームワーク「/decideパイプライン」を構築する方法を紹介します。

技術的な意思決定を支援するスキル

Salesforce Ada Agent Skills（英語）は、コードの記述にとどまらない、さまざまなエージェントスキルを集めたオープンソースのレポジトリです。/decideは、AIを使って技術的な意思決定を進める、構造化されたパイプラインです。たとえば、「/decide managed package vs. unlocked package vs. unpackaged metadata for distributing utilities across 3 orgs」（3つのSalesforce組織に共通のユーティリティを配布する場合、管理パッケージ、ロック解除済みパッケージ、パッケージ化しないメタデータのどれを選べばよいか）と入力してみましょう。すると、コーディングエージェントが、ユーザーから情報を収集して、公式ドキュメントにもとづく選択肢を提示します。さらにユーザーが実際の運用をもとにリスクを評価できるように表を出力し、スコア付きの推奨プランを提案して、その推奨案を意思決定の記録としてディスクに書き込みます。

出力はファイルとして残るため、バージョン管理やレビューが可能で、経緯を知りたい人がいつでも参照できます。

要件の聞き取り、評価基準の検討、スコアリングという基本パターンは、システム管理者（Admin）、開発者（Developer）、アーキテクト（Architect）を問わず、あらゆる技術的な意思決定に応用できます。これが「ADA」の由来です。以下の例ではClaude Codeを使っていますが、このスキルはどのAIエージェントでも使えるように設計されており、GitHubにはGeminiやCodex CLI向けのひな形も用意されています。

パイプラインの流れ

パイプラインでは、ステップを進めながら意思決定の範囲とコンテキストを絞り込んでいきます。各ステップの出力によって、次のステップの入力の範囲が決まります。幅広い情報収集と調査から始まり、最終的に1つの検証可能な意思決定スコアを決定します。

主な設計パターン

前述のパイプラインは、このスキルが実行する処理を示したものです。以下に、このスキルの実装方法と、信頼性と適応性を備え、技術的な意思決定を安心して任せられるスキルにするための設計パターンを紹介します。これらのパターンを組み合わせることで、内容を検証して共有し、その後の作業にも活用できる出力が得られます。

フォルダー構造

このスキルは、複数のMarkdownファイルからなるディレクトリとして構成されています。

salesforce-ada-agent-skills/
 ├── CLAUDE.md # グローバルルール
 ├── .mcp.json # MCPサーバーの構成
 ├── .claude/
 │ 　　└── skills/
 │ 　　　　　├── learn/
 │ 　　　　　│　　 └── SKILL.md # 学習ワークフロー
 │　　　　　 └── decide/
 │ 　　　　　　　　└── SKILL.md # パイプラインのステップと制約
 ├── knowledge/
 │ 　　├── formats/ # 共通の出力テンプレート
 │　　 │ 　　├── options-format.md # ソリューションの選択肢一覧用テンプレート
 │ 　　│　　 ├── criteria-format.md # 評価基準用テンプレート
 │　　 │　　 ├── risk-matrix-format.md
 │　 　│　 　└── decision-format-*.md # 意思決定記録の出力テンプレート
 │　　 ├── scoring/ # 意思決定スコアの算出方法
 │ 　　└── modifiers/ # 組み合わせ可能な観点
 └── output/
 　　　└── decisions/ # 生成された意思決定の記録

CLAUDE.md （レポジトリのルート）では、スコアリングに使う各評価軸の重み、MCPのソース選択ルール、さらに、意思決定スキル全体に適用される厳格な制約を定義しています。スキルファイル（SKILL.md）はパイプラインの処理順序を管理し、CLAUDE.mdは各ステップを規定するルールを管理します。

「/decide」と入力するとSKILL.mdが読み込まれ、パイプラインの順序を制御します。フォーマットファイルは、 AIエージェントが解釈することなく、コピーして使用するテンプレートです。そのため、会話の長さにかかわらず一貫した出力を生成できます。スコアの算出方法は、最後のステップでのみ読み込まれます。スコアの算出方法には、約350行にわたって詳細な評価基準が記されているため、早い段階で組み込むと、情報収集の段階でAIエージェントの注意を分散させてしまうことになります。

このようにファイルを分けておくと、パイプラインのロジックに手を加えずにフォーマットを改善したり、ステップを変更せずにスコアリングの評価軸を入れ替えたりすることが可能になり、各段階でAIが参照する情報量を必要最小限に抑えられます。

最終的には人が判断

各ステップの最後で、AIエージェントはいったん作業を停止し、次のステップに進んでよいかを確認します。どの確認ポイントでも分析内容を調整して、選択肢の追加や評価基準の削除、評価の見直しが可能です。この仕組みによって、最初のステップで生じた誤った前提が、途中で検証されないまま推奨案まで持ち越されることを防げます。これにより、開発者の実務経験を最大限に活かし、より質の高い出力を得ることができます。

早い段階で幅広く情報を収集し、その後で事実関係を検証

解決策の選択肢を探るステップで最初に行う調査では、広範なクエリーを使用し、個々のアプローチを都合よく選ぶのではなく、複数のアプローチを一度に提示します。それぞれの選択肢は、提示する前にドキュメントをもとに妥当性が検証されます。さらに、リスクマトリックスに記載される事実関係についても、評価を付ける前に的を絞った検索で確認します。このように複数の段階で検証することで、幅広くすべての選択肢を公平に洗い出しながら、掘り下げた調査で根拠のない記述が最終スコアに入り込むことを防ぎます。

このスキルは、ドキュメント検索に対応したMCP（Model Context Protocol）サーバーがなくても機能します。MCPサーバーを利用できない場合は、Web検索やAIエージェントの学習済み知識を代わりに使用し、どの方法で情報を裏付けているかを明確に示します。とはいえ、質の高い意思決定には質の高いドキュメントが欠かせません。そこで、管理者、開発者、アーキテクト向けの最新の公式ドキュメントを対象に、キーワード検索とベクトル検索を実行できるカスタムMCPサーバー、salesforce-content（英語）を構築しました。MCPで利用できるドキュメントであればどれでも機能します（このレポジトリには、設定不要で使える代替手段としてContext7の設定も含まれています）。ただし、Web検索ではソースが解析しにくい場合に重要な情報を取りこぼすことがよくあるため、信頼できるSalesforceの情報源が直接インデックス化されたsalesforce-contentの利用が推奨されます。

各ステップの出力に個別のフォーマットファイルを用意

各ステップには、出力に使われる表の構造を厳密に定めたテンプレートファイルが用意されています。AIエージェントは、文章で書かれた指示よりも、具体的なテンプレートのほうに確実に従います。フォーマットファイルをパイプラインのロジックから分離することで、ステップに手を加えずにフォーマットを繰り返し改善できます。

AIエージェントが自ら検証できるルールベースのスコア

リスク評価には、信頼度を表す数値が割り当てられます（低リスク = 85、中リスク = 55、高リスク = 25）。この数値に評価軸ごとの重み付け（信頼性20%、安定性20%、オペレーショナルエクセレンス20%、リソースの最適化15%、コストの最適化15%、公平性10%）を掛けて合計した値が、各選択肢の意思決定スコアになります。常に最もスコアが高い選択肢が推奨案になります。AIエージェントは数値を比較して結果を検証します。また、プロンプトでも、判断や推論を加えないよう指示されます。値を固定することで、曖昧さがなくなります。各リスクレベルに1つの固定値が割り当てられているため、リスクマトリックスからスコアが機械的に算出されます。

この例では、新しいWell-Architectedフレームワーク（英語）の方向性を踏まえて最適化したスコア帯を使用していますが、必要に応じて変更できます。

共有可能な出力

重要な意思決定は文書化しておく必要があります。新しく加わったチームメンバーにも、技術的な選択の理由を理解してもらわなければなりません。そのため、出力を永続的に保存できるように設計することが重要でした。このスキルには、簡潔な出力か詳細な出力かの選択肢を備えた、Markdown形式のArchitectural Decision Record (ADR)（英語）を採用しました。

独自の意思決定スコアリングスキルを構築

このスキルは、他にも応用できる設計パターンです。希望するステップやスコアの算出方法、AIエージェントに応じて調整できます。

さっそく始める

レポジトリ（英語）をクローンし、READMEの手順に従って、/decideとタイプした後に質問を入力してみましょう。

このスキルは、人からのフィードバックを繰り返し取り入れることを重視して作成しています。そのため、推論を長い文章として提示するのではなく、具体的で引用可能な記述に分解し、表形式で確認できるようにしています。こうしたスキルがあれば、意思決定の質が向上し、誤りに早く気づいて、次の担当者が活かせる形で意思決定を記録として残せます。

関連情報

• ドキュメント – Anthropicのスキル公式ドキュメント（英語）
• ドキュメント – Anthropicのスキル活用に関するベストプラクティス（英語）
• ドキュメント – Salesforce Well-Architected（英語）
• 動画 – The Next Chapter of the Well-Architected Framework（英語）

執筆者について

Dave Norrisは、Salesforceのデベロッパーアドボケイトです。技術的なテーマを、多様な読者に広くわかりやすく説明することに情熱を注いでいます。Salesforceで10年以上勤務し、現在、SalesforceとMuleSoftの認定資格を40以上保有。2013年に、Salesforce認定テクニカルアーキテクトの資格を取得しています。

The post AIエージェント用の意思決定スコアリングスキルを作成する appeared first on Salesforce Developers Blog.

※本記事は2026年7月15日に米国で公開された Connect Slack to Salesforce with Hosted MCP Serversの抄訳です。本記事の正式言語は英語であり、その内容および解釈については英語が優先されます。

営業担当者は、定期的にパイプラインを更新し、Tableauで指標を確認し、商談に向けてアカウントチームの準備を整えなければなりません。これまで、開発者がこうしたワークフローを支援するには、カスタムアプリの構築が必要でした。しかしHeadless 360を利用すれば、Slack上の会話からSalesforce Platformのデータやプロセスにアクセスできます。もうSalesforceのタブを開く必要はありません。

これを可能にするのが、Slackに組み込まれたAIのチームメイトであるSlackbotに接続された、Salesforce Hosted MCP Server（英語）です。Slackは、チームやAIエージェント、Salesforceエコシステム上に構築されたすべてのツールを1か所でつなげるエンゲージメントレイヤーです。

この記事では、なぜSlackがSalesforceに最適な会話型インターフェースなのか、Salesforce Hosted MCP ServerがSlack内でどのように機能するのか、Slackbotとどのように接続するのか、そしてSalesforce Platformと、業務を支えるオペレーティングシステムであるSlackが組み合わさることで何が可能になるのかを見ていきます。

Slack – エージェンティック・エンタープライズのためのエンゲージメントレイヤー

Slackは人、AIエージェント、データをつなげ、仕事を進めるためのオペレーティングシステムです。Slackには、Salesforce Platformの機能がネイティブに組み込まれ、MCPサーバーも接続されています。チームが一緒に作業を進めている場所で、自然な会話を通じて、Agentforce 360、Data 360、TableauなどのSalesforceエコシステム全体を利用できます。

下のスクリーンショットには、Slackデスクトップアプリに表示されたSalesforceレコードとTableauインサイト、Slackモバイルアプリで交わされたユーザーとSlackbotの会話が表示されています。

この体験の中心にあるのがSlackbotです。Slackbotは、企業内のあらゆる会話、ファイル、チャンネル、アプリに1か所からアクセスできるAIインターフェースです。Slackbotが提示した情報は、チーム全体で共有し、話し合い、アクションにつなげることができます。さらに、Slackbotはデータを会話や接続済みのツールと統合することができます。チームがSlackで仕事を進めるなかで蓄積されるコンテキストは、Slackbotに取り込まれ、日々の業務の自然な流れの中でレコードに反映されます。

これが、Slackの強みです。そして、ビジネスのコンテキストがすべてMCPを通じてSlackbot MCPクライアント（英語）から利用可能になったことで、これまで別々に動いていたツールを、1つの会話の中で連携させて使えるようになりました。

Salesforce Hosted MCP Serverとは – 簡単なおさらい

Model Context Protocol（MCP）は、さまざまなベンダーの外部ツールやデータソースとAIエージェントがやり取りするためのオープン標準（英語）です。 Salesforceは、この標準をSalesforce Hosted MCP Serverとして実装し、提供しています。MCPに対応しているクライアントであれば、Salesforce組織に安全で適切に管理された形でアクセスし、クエリーの実行、レコードの変更、アクションの実行といった操作を直接行うことができます。個別のログインや、連携のためのカスタムコードは必要ありません。

Salesforceでは、Salesforceオブジェクト（英語）、Tableau（英語）、Data 360（英語）向けに、標準のHosted MCP Server一式をすぐに利用できる状態で提供しています。さらに、標準サーバーだけでなく、Apexアクション、フロービルダー、Apex RESTエンドポイント、APIカタログのAPI、プロンプトビルダーのテンプレート、AgentforceのAIエージェントといったツールを組み込んでカスタムMCPサーバー（英語）を構築し、連携用のコードを記述することなく、Salesforce組織の機能を公開できます。

Salesforce Hosted MCP Serverの詳細については、こちらのドキュメント（英語）をご覧ください。

SlackとSalesforce Hosted MCP Serverとの連携を設定する

SlackbotとSalesforce Hosted MCP Serverとの連携は簡単に設定できます。URLのコピーや手作業でのOAuthの構成、カスタムコードの記述は必要ありません。Slack管理者向けのUIを使って、すべての設定を数ステップで完了できます。

事前準備

設定を始める前に、以下を用意してください。

• SlackbotとSalesforceを利用できるSlackの有料プラン（ビジネスプラス、Enterprise Select、Enterprise Grid、Enterprise+）
• Slackに接続された1つ以上のSalesforce組織
• ワークスペースのオーナー/管理者権限、またはオーガナイゼーションのオーナー/管理者権限
• 接続されているSalesforce組織に対するSalesforce管理者権限
• 1つ以上の有効なSalesforce Hosted MCP server（英語）

SalesforceをまだSlackに接続していない場合は、まずヘルプ記事「SalesforceとSlackを連携させる」 の手順を実行してください。接続が確立されると、ユーザー認証は自動的に行われます。SlackbotはSlackとSalesforceの既存のアカウントマッピングを使用するため、メンバーが別途ログインする必要はありません。

Note: Slackワークスペースをまだ作成していない場合は、こちらの手順で簡単に作成できます。

ステップ1 – MCPサーバーの設定を開く

MCPサーバーの設定にアクセスする手順は、プランによって異なります。

ビジネスプラスとEnterprise Select:
管理者 → ワークスペースの設定 → Salesforce → Salesforce MCPサーバー

Enterprise GridとEnterprise+:
オーガナイゼーション名 → ツールと設定 → オーガナイゼーションの設定 → Salesforce → MCPサーバー

ステップ2 – Salesforce Hosted MCP Serverを追加する

1. ［MCPサーバーを追加］をクリックします。
2. 有効なSalesforce Hosted MCP Serverのリストから追加したいサーバー（SObject All、Data 360、カスタムサーバーなど）を選択します。
3. ［追加］をクリックし、サーバーが公開するツールを確認します。
4. ［次へ］をクリックします。

Enterprise GridまたはEnterprise+を利用している場合は、次のステップに進む前に、そのサーバーを利用可能にするワークスペースも選択します。

ステップ3 – アクセス権を設定する

1. SlackbotからこのMCPサーバーを利用できるユーザーを選択します。
   • 全員：Slackbotを利用できるすべてのメンバー
   • 特定のグループとメンバー：チームまたは個人単位で細かく制御
   • すべて許可しない：先にインストールだけして、アクセスは後で有効化
2. ［接続］をクリックして完了します。

これでMCPサーバーが有効になり、アクセス権を持つユーザーに代わってSlackbotがこのサーバーを利用できるようになります。

SlackbotのMCP呼び出しに適用されるSalesforceの権限

Slackbotで利用するSalesforceのMCPサーバーは、権限を考慮して動作するように設計されています。Slackbotが実行するすべてのアクションは、標準のSalesforceセキュリティモデル（英語）に従い、項目レベルのセキュリティ、オブジェクト権限、共有ルールがユーザーごと、リクエストごとに適用されます。ユーザーは、Salesforceで許可されている情報のみを表示し、許可されている操作のみを実行できます。Slack管理者は、Slackオーガナイゼーションの管理者向けUIから、いつでもアクセス権の調整、権限の更新、サーバーの完全削除を実行できます。

Slackのユーザーレベルでもセキュリティ対策が講じられており、MCPツールを誤って使用しないよう、確認を促すプロンプトが表示されます。以下のスクリーンショットでは、SlackbotがCreateAccountSyncMeetingTaskカスタムMCPツールを使用してよいかどうかを、ユーザーに確認しています。

SlackbotとSalesforce Hosted MCP Serverの活用例

MCPサーバーの設定が完了すると、SlackとSalesforceの両方で認証されているチームのメンバーは、それぞれの権限にもとづいて、Slackで自然言語を使ってSalesforce組織にアクセスできるようになります。では、実際にSlackbotをどのように活用できるのでしょうか。架空のアウトドアグッズメーカー「Northern Trail Outfitters」を例として見てみましょう。

カスタムビジネスプロセスの開始

Northern Trail Outfittersの営業担当者が、1時間後に顧客であるAlpine Trekkersへの訪問を予定しています。Salesforceを開いて取引先ページに移動し、訪問に備えて商談やケースを確認する必要はありません。代わりに、Slackbotに次のように指示します。

「Alpine Trekkersとの取引の健全性を調べてください」

Slackbotは、標準のSObject All MCP server（英語）のツールを使用し、企業名にもとづいて取引先を特定します。続いて、取引先の健全性をチェックするカスタムフローツールを呼び出します。このフローによって、関連するケース、商談、活動から追加データが取得され、厳密なビジネスルールに従って健全性スコアが算出されます。

健全性チェックの結果、重大なサポートケースが未解決で、この取引先が要注意の状態にあることがわかりました。

商談の準備

Alpine Trekkersの健全性を確認した営業担当者は、顧客訪問に向けた準備をSlackbotに依頼します。Slackbotは別のカスタムツールを使って、Salesforceで取引先に関連付けられた取引先責任者をもとに相手の関係者を特定し、商談に必要な情報を記録します。以下のスクリーンショットでは、SlackbotがカスタムMCPツールを呼び出し、取引先についての情報を共有するためのミーティングを設定するタスクを作成しています。

Tableauのリアルタイムデータを使ったパイプライン分析

Slackbotに準備を手伝ってもらったことで、商談は順調に進み、懸念にも対処できました。Alpine Trekkersのリスクは解消されました。

Northern Trail Outfittersの営業マネージャーは、第2四半期のパイプラインの健全性について最新の状況を把握したいと考えています。Tableauダッシュボードを開く必要はなく、Slackbotに次のように尋ねます。

「Tableauでは、第2四半期の地域別のパイプラインのコンバージョン率はどうなっていますか」

Tableau MCPサーバー（英語）に接続されているため、Slackbotは行レベルのセキュリティを維持しながらセマンティックレイヤーにクエリーを実行し、実際のビジネス指標にもとづく、信頼性とガバナンスが確保された回答を、視覚化したデータとともに返します。営業担当者はこうして得たインサイトをチームと共有して、すぐに行動に移せます。また、データを見ながら、その場で次の一手について話し合うことができます。

まとめ

SlackbotをSalesforce Hosted MCP Serverに接続する方法を紹介しました。Slackがエージェンティック・エンタープライズのエンゲージメントレイヤーである理由、そしてHeadless 360を活用し、Salesforce Hosted MCP Serverを通じてAIエージェントと一緒に仕事を進める仕組みを見てきました。また、SlackbotをSalesforce Hosted MCP Serverと連携させる設定と、連携のメリットを示す実践的な例も確認しました。

さっそく、皆さんのSalesforce組織にSlackbotを接続してみましょう。設定の詳しい手順は、「MCPサーバーでSlackbotをSalesforceに接続する」を参考にしてください。

関連情報

• ドキュメント – SalesforceとSlackを連携させる
• ドキュメント – MCPサーバーでSlackbotをSalesforceに接続する
• ドキュメント – Salesforce Hosted MCP Servers（英語）

執筆者について

Ashley Maoは、Salesforceでシニアプロダクトマーケティングマネージャーを務め、SalesforceとSlackの製品リリースを主導しています。AIエージェントをチームメイトとしてともに働くことの意義や、データと会話が融合することで生まれる可能性を探求しています。

Philippe Ozilは、Salesforce Platformの開発に取り組むプリンシパルデベロッパーアドボケイトです。技術的なコンテンツを執筆し、カンファレンスにもよく登壇します。フルスタック開発者で、API、DevOps、ロボティクス、VRプロジェクトに注力しています。X、LinkedIn、Blueskyでのフォロー歓迎。GitHubのプロジェクトもチェックしてください。

The post Hosted MCP Serverを使ってSalesforceにSlackを接続する appeared first on Salesforce Developers Blog.

※本記事は2026年6月30日に米国で公開された How to Secure Salesforce Hosted MCP Serversの抄訳です。本記事の正式言語は英語であり、その内容および解釈については英語が優先されます。

Salesforce Hosted MCP（Model Context Protocol）Server（英語）は、Headless 360を構成する主なコンポーネントの1つで、標準機能（英語）やカスタム機能（英語）をサーバー経由で利用可能にし、AIエージェントの能力を拡張できます。ツール、プロンプト、リソースをユーザーに公開する際には、データや操作を保護するために、MCPサーバーへのアクセスを安全に保つことがきわめて重要です。

MCPサーバーを構築する開発者やそのサーバーの管理者は、セキュリティモデルを理解しておくことで、誰が、何に、いつ、どのような方法でアクセスできるかを制御できます。この記事では、Salesforce Hosted MCP Serverの認証、認可、権限の制御、ログの記録のベストプラクティスについて説明します。

Salesforce Hosted MCP Serverのセキュリティモデルを理解する

Salesforce MCPのセキュリティモデルは、3つのレイヤーで構成されています。

1. 認証 – 誰がリクエストを行っているかを確認します。
2. 認可 – そのユーザーが何を実行できるかを決定します。
3. 権限の制御 – サーバーが公開する基本要素（ツール、プロンプト、リソース）を利用する際に、オブジェクトや項目のレベルで細かなアクセス制御を適用します。

これらのセキュリティレイヤーに加え、監査やコンプライアンスに対応できるよう、すべての操作がログに記録されます。

最初の2つのレイヤーはMCP標準に直接関連しており、3つ目のレイヤー（権限の制御）はSalesforce Platform固有のものです。それぞれのセキュリティレイヤーは、1つ前のレイヤーの上に成り立っています。ユーザーが誰なのかを確認するまでは、そのユーザーに何を許可するかを決めることはできません。そして、認可ルールがなければ、権限を適用することはできません。

これらのレイヤーとログがどう連携しているかを理解すれば、多層防御戦略を構築しやすくなります。各レイヤーを詳しく見ていきましょう。

認証 – 本人確認

認証は、最初の防御線となります。ユーザーの身元を確認します。

MCPの仕様（英語）では、認証と認可は実装に必須の技術的要件としては定義されていません。しかし、適切なセキュリティ対策がなければ、権限のないユーザーが機密データにアクセスしたり、望ましくない操作を実行したりするおそれがあります。そのため、この記事では、エンタープライズ環境に必須の要件として扱います。

MCPでは、認証と認可の仕組みとしてOAuth 2.0（英語）を規定しています。MCPでサポートされているのはOAuth 2.0の一部のみで、すべての認可フローやグラントタイプを利用できるわけではありません。また、ClaudeやChatGPTなどの広く使われているクライアントがサポートするフローは、Salesforceよりも少数です。

MCPは比較的新しいものですが、OAuth 2.0は10年以上使われており、Salesforce Platformには、クライアントとして、あるいはサーバーとして動作する場合でも、OAuthと連携するためのさまざまな仕組みが用意されています。そのため、Salesforce開発者は、OAuthのセキュリティを自分で実装する必要がなく、外部クライアントアプリ（ECA）を通じて宣言的に制御できます。

Salesforceは、1つのECAを複数のMCPクライアントで共有するのではなく、MCPクライアントごとに専用のECA（Claude用、ChatGPT用、Cursor用など）を作成することを強く推奨します。こうすることで、アクセス制御とクライアントのアクティビティの監査が容易になります。
Salesforce Hosted MCP Serverでは、ECAを介した認可コードフローのみをサポートしています。そのため、ユーザーがMCPサーバーに接続する際には、Salesforceでの認証が必要になります。各ユーザーのSalesforceユーザーアカウントが、MCPセッションに関連付けられます。

Notes:

• インテグレーションユーザーなど、プリンシパル（実行主体）となるユーザーを設定したサービスアカウントを、すべてのセッションで共通して使用するように指定することはできません。これは避けるべきアンチパターンです。
• 現時点では、マシン間のフローをサポートする予定はありません。組織への接続とMCPツールに対するアクセスの許可には、引き続き人間が関与します。

デフォルトでは、組織内のすべてのユーザーがECAに接続し、MCPサーバーにアクセスできるようになっています。ただし、認可ルールを指定すれば、アクセスを制御できます。

認可 – アクセス制御

認可により、ユーザーが実行できる操作を決定します。ユーザーの認証が完了すると、Salesforceはそのユーザーの権限を評価し、どのリソースにアクセスできるかを判断します。
認可を制御する仕組みはいくつかあります。

OAuth範囲でアクセスを認可する

認可の第一段階として、ECAの設定時に指定するOAuth範囲により、特定のリソースへのアクセスが制御されます。

新たに追加された「SalesforceでホストされているMCPサーバーにアクセス（mcp_api）」範囲によって、Salesforce Hosted MCP Serverへのアクセスが許可されます。この範囲は、Platform API（REST、Tooling、Metadataなど）へのフルアクセスを許可する「APIを使用してユーザーデータを管理（api）」範囲の使用を避けるために導入されました。

原則として、AIエージェントにAPIへのフルアクセスを許可のではなく、MCPを介して限られた「安全な」操作だけを公開することが推奨されます。

承認済みユーザーのみにアクセスを許可する

デフォルトのECA設定では、組織内のすべてのユーザーが認証を行い、MCPサーバーにアクセスできます。アプリケーションポリシーを設定すると、事前に承認した特定のユーザーにのみアクセスを限定できます。この設定では、特定のプロファイルや権限セットが割り当てられたユーザーを選択できます。

たとえば、次の設定では、「MCP Client User」権限セットを持つユーザーだけがECAに接続できます。

IP制限を適用する

ECAを利用できるユーザーを限定するだけではなく、接続可能なIP範囲を指定してIPアドレスによる制限を適用することもできます。これらの制限は、デフォルトのECA設定の［アプリケーション認証］で有効になっています。

［ネットワークアクセス］設定メニューで、信頼済みIP範囲をすべてのユーザー、または特定のユーザープロファイルに対して指定できます。

更新トークンの有効期間を短縮する

ユーザーがECAでログインするとアクセストークンが取得され、その後のすべてのMCP操作にそのトークンが渡されます。トークンは、有効期間が終了したら更新する必要があります。

デフォルトのトークン有効期間は1年ですが、調整が可能で、本番環境で短く設定することもできます。これにより、トークンが盗まれ、悪意のある目的で再利用されるリスクを軽減することができます。トークンの有効期間を制御するには、ECAの設定を開き、［アプリケーション認証］にある［更新トークンポリシー］を探します。更新トークンのセキュリティを強化する推奨設定については、こちらのドキュメント（英語）で紹介しています。

アクセス権を取り消す

有効期限が切れる前にECAのトークンを取り消す必要がある場合は、［設定］に移動して［OAuthの利用状況］を検索し、ECAを選択して個々のトークンを取り消すか、一括で取り消します。

MCPサーバーを有効化する

デフォルトでは、すべてのMCPサーバーが無効になっています。AIエージェントに公開するMCPサーバーだけを有効にしてください。

たとえば、以下の図では1つのカスタムサーバーと2つの標準サーバーのみを有効にしています。

MCPツールにアノテーションを追加する

厳密な意味でのセキュリティ対策ではありませんが、公開するMCPツールには、その動作を示すアノテーションを付けることが推奨されます。これにより、AIエージェントにツールをどのように使用すべきかを伝えられます。たとえば、AIエージェントに対して、レコードの削除など破壊的な可能性のある操作を実行する際にユーザーに確認を求めるべきか、あるいはツールを複数回実行しても安全かどうか、といった情報を提供できます。

Note: MCPツールのアノテーション（英語）をクライアント側でサポートするかどうかは任意であるため、すべてのAIエージェントがその内容に従うとは限りません。

権限の制御 – きめ細かなアクセス管理

ECAの設定によって特定のMCPサーバー自体へのアクセスを制限することはできませんが、サーバーを構成する各ツールへのアクセスは制御できます。

MCPツールは、ECAを使用して認証したユーザーと同じ権限で実行されます。つまり、Salesforceの中核的なセキュリティモデルが、次のすべてのレベルで適用されます。

• オブジェクトレベルのアクセス制御（CRUD権限）
• 項目レベルのセキュリティ（FLS）による制限
• レコード共有ルール

個別のセキュリティ要件に対応する（英語）ために、Agentforce、Apex、Flowを使ってカスタムツールを実装する（英語）こともできます。この方法を採用する場合は、必ずセキュリティのベストプラクティスに従ってください。

機密性の高い操作を保護し、最小権限の原則に従うために、権限セットを使ってください。ユーザーには、業務に必要な権限だけを付与します。権限は定期的に見直し、不要になったアクセス権は取り消してください。

また、本番環境にデプロイする前に、権限をテストしてください。たとえば、runAsメソッドを使ってMCPツールに対してApexテストやFlowテストを実行し、さまざまなアクセスレベルでユーザーの動作をシミュレーションします。

ログの記録 – アクセスのトラッキング

ログを記録することにより、誰が、何に、いつアクセスしたかを示す監査履歴が作成されます。こうした記録は、セキュリティの監視、コンプライアンス、トラブルシューティングに不可欠です。

MCPツールによって実行されたすべてのアクションは、監査履歴の中でECAに接続したユーザーに紐付けられます。Salesforceは、イベントモニタリングを使用してMCPサーバーのアクティビティを自動的に記録します。

ログにアクセスするには、［設定］に移動し、「イベントログファイルブラウザー」を検索します。[イベントの種別］で［API合計使用量］を選択して絞り込みます。イベントログのCSVファイルで、API_CLIENT_CATEGORY列の値がSALESFORCE_HOSTED_MCPである行をフィルタリングして、MCPトラフィックを特定できます。MCPツールを呼び出したユーザーや、影響を受けたオブジェクト（エンティティ）などの詳細を確認できます。

ログは定期的に確認してください。STATUS_CODEでエラーを探し、USER_NAMEやCLIENT_IPを見て予期しないアクセスパターンがないかを確認しましょう。何か見つかった場合、セキュリティ上の問題や権限設定の誤りがあるかもしれません。

まとめ

Salesforce Hosted MCP Serverのセキュリティを確保する方法を確認し、多層的セキュリティアーキテクチャーを構成するすべてのコンポーネントを見てきました。

• 認証で、ユーザーの本人確認を行う
• 認可で、ユーザーがアクセスできるツールを制御する
• 権限の制御で、きめ細かなデータアクセス制御を適用する
• ログの記録で、コンプライアンスとセキュリティ監視のための監査履歴を作成する

この記事で紹介したセキュリティのベストプラクティスを実践して、便利なMCPツールをAIエージェントに提供しながら、データを確実に保護してください。

関連情報

• ドキュメント – Salesforce Hosted MCP Servers（英語）
• ドキュメント – APIカタログでのMCPサーバーの管理
• ドキュメント – 外部クライアントアプリケーション
• ドキュメント – 権限セット
• GitHub – Community Wiki（英語）

執筆者について

Philippe Ozilは、Salesforce Platformの開発に取り組むプリンシパルデベロッパーアドボケイトです。技術的なコンテンツを執筆し、カンファレンスにもよく登壇します。フルスタック開発者で、API、DevOps、ロボティクス、VRプロジェクトに注力しています。X、LinkedIn、Blueskyでのフォロー歓迎。GitHubのプロジェクトもチェックしてください。

The post Salesforce Hosted MCP Serverをセキュアにする方法 appeared first on Salesforce Developers Blog.

※本記事は2026年5月8日に米国で公開された Intent-Driven Tool Selection Using Abilities in Agentforce Vibesの抄訳です。本記事の正式言語は英語であり、その内容および解釈については英語が優先されます。

AIのコーディングエージェントが真価を発揮するには、適切なタイミングで適切なツールを利用する必要があります。しかし、利用できるSalesforce DX MCP Server（英語）ツールはとても多く、さらに増え続けているため、AIエージェントに必要なツールを開発者が手作業で選び、設定するのは簡単ではありません。ここで、Agentforce Vibes（英語）の新しい機能「アビリティ」（英語）が役に立ちます。アビリティは、Salesforce開発環境の自動化を支援する、インテリジェントなコンテキスト有効化システムです。

アビリティはRAGベースのセマンティック検索を活用し、リクエストごとに最も関連性の高いSalesforce DX MCP Serverツールを特定して、ツール選択の問題に対処します。このアプローチにより、実行環境のツールを絞り込みながら、出力品質を向上させ、トークン使用量も削減できます。

この記事では、ツールの増加によって生じる課題を検討し、アビリティの仕組みを説明したうえで、セマンティック検索と、依存関係にもとづいて関連ツールを追加する仕組みを詳しく掘り下げます。

課題 – 増え続けるツールと手動による構成

Agentforce Vibesでは、コンテキストがすべてです。Agentforce 360 Platformが拡大するにつれ、MCP（Model Context Protocol）サーバーの数も増えています。現在、Agentforce Vibes内で利用できるSalesforce DX MCP Serverツールは80を超え、CLIコマンド、テスト、コード分析、アクセシビリティチェック、DevOpsオペレーション、モバイル開発など、個別のタスクに対応するツールが揃っています。

すべてのツールを一度に有効にすると、プロンプトが大きくなり、モデルの選択肢が多くなりすぎ、出力品質が低下し、トークンコストも増加します。一方で、ツールが少なすぎるのも問題です。Agentforce Vibesが、メタデータの生成、Apexコードの作成、LWCのリファクタリング、コードに含まれるセキュリティ違反の分析といった処理に必要な機能を利用できなくなるかもしれません。

Salesforce DX MCP Serverツールの増加に伴い、次のような課題が新たに生じています。

• デフォルト設定の制限 – 利用可能なツールが膨大な数に上るため、Salesforceはその一部だけをデフォルトで有効にしています。多数のツールを有効にすると、ユーザーエクスペリエンスが低下したり、モデルに過度な負荷をかけたりする可能性があるためです。
• ユーザーエクスペリエンスへの影響 – その結果、最適とはいえないコードが生成され、コンパイルやデプロイに失敗したり、Salesforceの開発規約が無視されたりすることがあります。
• 手動での設定の難しさ – 利用できるツールはカスタマイズできますが、そのためにはローカルのmcp_config.jsonファイルを手作業で編集し、MCPサーバーツールの内部名を把握しておく必要があります。その結果、ツールを追加すれば出力が改善される場合でも、ほとんどの開発者は変更を行わず、デフォルトのツールセットだけに依存してしまっています。

こうした課題を背景に、Salesforceでは、Agentforce Vibesが必要とするツールを、必要なタイミングで過不足なく提供する仕組みを必要としていました。

ソリューション – アビリティで、インテリジェントなコンテキストを有効化

アビリティは、特定の開発シナリオにおいてAgentforce Vibesが何を実行できるかを定める、ドメイン固有の機能です。手動で設定したり、開発モードを切り替えたりする必要はありません。システムが、開発者の意図を直接判断して対応します。これにより、Agentforce Vibesが開発タスクの完了に必要な機能を確保しながら、実行環境をスリムに保つことができます。

たとえば、次のような機能に対応するアビリティがあります。

• ApexおよびLWCの開発
• DevOps運用
• モバイル開発
• コアプラットフォームの管理

各アビリティには、その機能に関連するDX MCP Serverツールがまとめられています。

リクエストを受け取ると、Agentforce Vibesは開発者のプロンプトを評価し、そのタスクで有効にする機能を判断して、それらの機能に関連するツールだけを利用可能にします。このプロセスは、アビリティコーディネーターと呼ばれる内部オーケストレーションレイヤーによって管理されます。アビリティコーディネーターはリクエストを解釈し、モデルが呼び出される前に実行環境を準備します。この処理はすべてのタスクで自動的に実行されるため、開発者が設定を行う必要はありません。

アビリティは組み合わせ可能で、リクエストによっては複数の機能が有効化されます。「現時点でAgentforce Vibesに対してどのツールを利用可能にすべきか？」という問いに答えるのが、アビリティの役割です。

スキルとアビリティが連携する仕組み

アビリティとスキルは、それぞれが異なる役割を担いながら、相互に補完し合う関係にあります。アビリティはコンテキストを有効化します。開発者の意図を検知し、そのタスクに適したSalesforce DX MCPツールを自動的に選択します。これにより、モデルの焦点が明確になり、Salesforceのベストプラクティスに沿った出力を維持できます。

スキルは、再利用可能なタスク単位の作業手順書です。スキルには、トリガーのリファクタリングやテストの生成、デプロイの実行といった具体的な作業の進め方が定義されているため、その都度同じ指示を出し直す必要はありません。

アビリティはどのツールを利用可能にするかを決定し、スキルは作業の進め方を定義します。この2つが連携することで、開発者が主導権を保ちながら、Agentforce Vibesがタスクに適した実行環境をインテリジェントに構成します。

アビリティの仕組み

アビリティは、検索拡張生成（RAG）を使用してツールを選択します。モデルに利用可能なツールの全カタログを送るのではなく、セマンティック検索を活用して最も関連性の高いツールを取得します。そのため、プロンプトのサイズを抑えながら、増え続けるカタログに対応できます。

セマンティック検索の流れ

モデルに過度な負荷をかけることなく、Agentforce Vibesが適切なツールを選択できるように、RAGベースの検索プロセスが採用されています。このプロセスは、ツールのインデックス化、プロンプトとの照合、モデルの実行コンテキストへのツールの追加という、3つのフェーズで行われます。

フェーズ1 – ツールのベクトル埋め込みとインデックス化

ユーザーとのやり取りに先立ち、ツールカタログをあらかじめ検索可能な状態にしておきます。MCPツールカタログが更新されるたびに、次の処理が実行されます。

• ベクトル変換 – 名前、説明、パラメーター、想定される利用コンテキストを含む各ツールの定義を正規化し、ベクトル埋め込みに変換します。
• データベースへの保存 – これらのベクトル埋め込みは、ベクトルデータベースに保存されます。これにより、システムは単にキーワードを照合するのではなく、ツールの「意味」と機能にもとづいてツールを特定します。

フェーズ2 – プロンプトとツールの照合（検索）

プロンプトを送信すると、Agentforce Vibesは次の手順でリアルタイムの類似度検索を実行します。

• プロンプトの埋め込み – ツール定義のベクトル変換に使用したものと同じモデルで、プロンプトをベクトル埋め込みに変換します。
• 類似度検索 – システムはコサイン類似度検索を実行し、プロンプトのベクトルとツールのベクトルインデックスを比較して、意味的に最も近い候補を特定します。
• 上位候補の選択 – パフォーマンスと精度のバランスを取るため、システムは結果を順位付けし、通常は適合度の高い10個前後のツールを候補として選択します。

フェーズ3 – 実行時コンテキスト

選択されたツールは、一時的な「関数カタログ」として、モデルの実行コンテキストに組み込まれます。これにより、速度とコストの面でプロンプトサイズを最適化しながら、リクエストの処理に必要な機能をLLMにすべて提供できます。

ツールの依存関係への対応

一部のMCPツールは、ワークフロー全体を制御・調整するオーケストレーターの役割を担い、タスクを完了するために追加のツールを必要とします。検索で取得されたツールのセットにオーケストレーターツールしか含まれていない場合、必要なツールがないために実行に失敗する可能性があります。

アビリティは、ツールの選択後に必要なツールを追加することで、この問題を解決します。

これにより、ツールセット全体を小さく保ちながら、タスクの完了に必要なツールをAIエージェントに提供できます。

まとめ

開発者の意図を把握し、タスクを実行できるようにするまで、アビリティは、Agentforce Vibesがその都度必要とするツールを過不足なく利用できるようにします。RAGベースのセマンティック検索を利用し、依存関係にもとづいて必要なツールを自動的に追加することで、増え続けるSalesforce DX MCPツールを効果的に管理し、手動で構成することなく、質の高い開発環境を実現します。

Agentforce Vibesの進化に合わせて、アビリティのインテリジェントなコンテキスト有効化システムも、次のような機能強化が見込まれます。

• Salesforce製およびサードパーティー製MCPサーバーへの対応の拡大
• 適切なツールが有効化された後に、スキルと連携してタスクの進め方をガイド
• 検索に使用するツールメタデータの拡充
• ツールの依存関係を検出する仕組みの強化

関連情報

• Agentforce Vibes開発者ガイド：アビリティ（英語）
• Trailhead：クイックスタート：Agentforce Vibesを使用してコードをトラブルシューティングする
• Trailhead：Get Started with Agentforce Vibes（英語）
• 動画：Agentforce Vibes Decoded（英語）

執筆者について

Jeff DouglasはSalesforceのプロダクトマネジメントディレクターで、Agentforce VibesとAIを活用した開発者向けツールを担当しています。2007年からSalesforce開発者として活動し、最初期のSalesforce MVPの1人でもあるJeffは、Trailheadの立ち上げを支援し、中核となる学習・評価システムをいくつも構築しました。陸軍の退役軍人で、ビール醸造所を経営していたことがあり、里親として子どもを育て、養子も迎えています。木工にも取り組み、小型のハイランド牛を飼育しています。LinkedInのプロフィールはこちら。

Ken Lewisは、Salesforceのテクニカルサービスのリードメンバーで、カリフォルニア州オークランドを拠点に活動しています。以前は非営利組織向けのSalesforce製品に携わっていました。現在はさまざまなお客様に向けて、Salesforce製品が使いやすく、役立つものになるよう取り組んでいます。プライベートでは、ラケットボールを楽しみ、自宅のDJセットで腕を磨き、ベイエリアの新しいレストランやアクティビティを開拓しています。LinkedInのプロフィールはこちら。

The post 開発の意図に応じてツールを自動で選択 – Agentforce Vibesの新機能「アビリティ」 appeared first on Salesforce Developers Blog.