Forem: Conor

Agent Script: Salesforce's Open Language for Deterministic Agent Orchestration

Conor — Sun, 26 Apr 2026 20:39:35 +0000

Salesforce open-sourced Agent Script at TDX 2026, and it solves one of the most frustrating problems in production Agentforce deployments: you can't tell an LLM "always do step A before step B, and only proceed to step C if the customer is verified." Prompt instructions don't enforce control flow. Agent Script does.

This post walks through what Agent Script is, how the language works, mnd how to build a realistic support triage agent with hard routing logic.

The Problem Agent Script Solves

Agentforce topics let you describe what an agent should do — but that description goes through an LLM at runtime.¹ The LLM interprets your instructions and decides how to act. Most of the time, it works. Sometimes it doesn't: it skips a verification step, invokes the wrong action, or transitions prematurely.

The workaround most teams use is defensive prompt engineering — stacking ALWAYS, NEVER, and IMPORTANT clauses into system instructions. This is fragile, untestable, and hard to audit.

Agent Script approaches the problem differently: it gives you a structured specification language where control flow is deterministic by design. The LLM still handles reasoning, but your code controls when reasoning happens and what happens after.

From the spec: "execution is decoupled from specification. Agent Script describes what the agent is — its state, its available actions, its instructions — not how the runtime executes it."²

Language Fundamentals

Agent Script is block-based and indentation-sensitive (like Python or YAML). Every agent is composed of blocks. Blocks fall into two categories:

Configuration blocks (config, system) — set the agent's identity and static behavior
Execution blocks (topic, start_agent) — define runtime behavior, state, and transitions

Here's a minimal valid Agent Script file:

config:
    agent_name: "Support Bot"
    default_locale: "en_US"

system:
    instructions: |
        You are a Salesforce support agent.
        Your job is to triage cases and route them to the right team.
        Never share internal case notes with the customer.

topic default:
    description: "General support entry point"

The pipe character (|) denotes multiline strings — keep your system instructions here rather than inline so they're readable and diffable.

Variables: Typed State in Your Agent

One of the more useful features is first-class variable support with explicit types:

variables:
    case_id: mutable string = ""
        description: "The support case ID collected from the user"
    customer_verified: mutable boolean = False
        description: "True once identity check has passed"
    priority: mutable string = "standard"
        description: "Case priority: standard, high, or critical"

Variables use @variables.name syntax throughout the rest of the script. Declaring them at the top of a topic forces you to think about what state the agent actually needs — and makes it visible during reviews and in the audit trail.

Before and After Reasoning Hooks

This is where Agent Script gets powerful. The before_reasoning and after_reasoning blocks let you inject deterministic logic around the LLM call:

topic billing_support:
    description: "Handle billing disputes and payment questions"

    variables:
        customer_verified: mutable boolean = False
        account_id: mutable string = ""

    before_reasoning:
        run @actions.verify_customer_identity
            with email=@variables.user_email
            set @variables.customer_verified = @outputs.verified
            set @variables.account_id = @outputs.account_id

        if not @variables.customer_verified:
            transition to @subagent.identity_verification

    reasoning:
        instructions: |
            The customer is verified. Account ID is @variables.account_id.
            Help them with their billing question. If the dispute exceeds $500,
            collect the details and escalate — do not resolve it yourself.

    after_reasoning:
        if @outputs.escalation_required:
            run @actions.create_escalation_case
                with account_id=@variables.account_id
                with details=@outputs.dispute_details
            transition to @topic.escalation_confirmation

Key mechanics:

run @actions.action_name — invokes a named Agentforce action (Apex, Flow, MuleSoft, external API)
with param=value — passes inputs to the action
set @variables.name = @outputs.field — captures outputs back into state
transition to @topic.name or @subagent.name — deterministic routing, no LLM involved

A Full Support Triage Example

Here's a more complete agent that routes inbound support requests by product category and customer tier:

config:
    agent_name: "Case Triage Agent"
    default_locale: "en_US"

system:
    instructions: |
        You are a Salesforce case triage agent.
        Identify the product area and collect a clear description of the issue.
        Do not attempt to solve technical problems directly — triage and route only.
        If the customer is on a Premier Success Plan, acknowledge the SLA.

topic case_intake:
    description: "Initial contact — collect case details and route"

    variables:
        product_area: mutable string = ""
            description: "Detected product: Sales Cloud, Service Cloud, Data Cloud, MuleSoft"
        customer_tier: mutable string = ""
            description: "Success plan tier: standard, premier, signature"
        case_description: mutable string = ""

    before_reasoning:
        run @actions.lookup_account_tier
            with contact_id=@variables.contact_id
            set @variables.customer_tier = @outputs.tier

    reasoning:
        instructions: |
            Greet the customer. Ask which Salesforce product they need help with
            and collect a clear description of the issue.
            Customer tier: @variables.customer_tier

    after_reasoning:
        set @variables.product_area = @outputs.detected_product
        set @variables.case_description = @outputs.issue_summary

        if @variables.product_area == "MuleSoft":
            transition to @subagent.mulesoft_triage

        if @variables.product_area == "Data Cloud":
            transition to @subagent.data_cloud_triage

        if @variables.customer_tier == "signature":
            run @actions.notify_tam
                with case_summary=@variables.case_description
            transition to @topic.premium_intake

        transition to @topic.standard_routing

Notice that the LLM does the qualitative work — understanding what product the customer is describing, extracting a clean issue summary — but the routing decisions are code. You can unit-test that transition logic. You can audit it. You can change it without touching a prompt.

Salesforce Actions as First-Class Citizens

Agent Script's @actions namespace maps directly to your Agentforce action library: Apex classes, Flows, MuleSoft API calls, external services. This means all the action tooling you already have — invocable Apex, autolaunched Flows — plugs in without changes.³

Example invocable Apex action that Agent Script can call:

public class LookupAccountTier {
    @InvocableMethod(label='Lookup Account Tier' description='Returns the Success Plan tier for a contact')
    public static List<Result> execute(List<Request> requests) {
        List<Result> results = new List<Result>();
        for (Request req : requests) {
            Contact c = [
                SELECT Account.Success_Plan__c
                FROM Contact
                WHERE Id = :req.contactId
                LIMIT 1
            ];
            Result r = new Result();
            r.tier = c.Account.Success_Plan__c != null
                ? c.Account.Success_Plan__c.toLowerCase()
                : 'standard';
            results.add(r);
        }
        return results;
    }

    public class Request {
        @InvocableVariable(required=true) public Id contactId;
    }
    public class Result {
        @InvocableVariable public String tier;
    }
}

The action name in Agent Script (@actions.lookup_account_tier) maps to the invocable method's API name in your org.⁴

Tooling: Parser, LSP, VS Code Extension

The full Agent Script toolchain is available at github.com/salesforce/agentscript:²

Parser — validates syntax, resolves namespaces
Linter — catches common mistakes (undefined variables, unreachable transitions)
LSP — Language Server Protocol implementation for editor support⁵
VS Code extension — syntax highlighting, autocomplete, inline validation
Monaco playground — browser-based editor for prototyping without an org

The VS Code extension is the practical starting point. Install it, open a .ascript file, and you get full IntelliSense for block types, namespace references, and action parameters.

Where to Start

Install the VS Code extension from the Agent Script GitHub repo.[2] It takes 2 minutes and gives you a working local environment.
Open the playground at the repo's web UI. The preloaded examples cover the most common patterns: verification gates, multi-topic routing, subagent delegation.
Audit your existing Agentforce topics:¹ identify the transitions and verification steps you're currently enforcing through prompt instructions. Those are your first candidates for Agent Script refactoring.
Map your invocable Apex to actions:³ any @InvocableMethod in your org can be wired as an @actions reference. Start with the actions your most critical agents already call.

Agent Script is in active development — the spec is open, the tooling is moving fast, and the TDX 2026 announcement included it as a pillar of the Headless 360 initiative. Now is the time to get ahead of it before it becomes the expected pattern for any production Agentforce deployment.

Agentforce Agent Topics — Salesforce Developer docs. Covers topic definition, instructions, and action assignment within Agentforce. ↩
Agent Script GitHub repository — Salesforce open-source repo. Contains the language specification, parser, linter, LSP implementation, VS Code extension, and Monaco playground. ↩
Invocable Actions in Agentforce — Salesforce Developer docs. Covers how Apex, Flow, and external actions are registered and invoked within Agentforce agents. ↩
@InvocableMethod annotation reference — Salesforce Apex Developer Guide. Full reference for declaring Apex methods as invocable actions, including input/output variable typing. ↩
Language Server Protocol specification — Microsoft. The open protocol that Agent Script's LSP implements for editor tooling integration. ↩

Salesforce Headless! All agents, all access.

Conor — Tue, 21 Apr 2026 22:30:34 +0000

Salesforce just flipped a switch at TDX 2026 that matters more than most announcements in recent memory: your Salesforce org is now an MCP server. Every Developer Edition org ships with Salesforce Hosted MCP Servers at no cost, and any MCP-compatible AI agent — Claude, Claude Code, Cursor, Codex, Windsurf — can now read data, trigger flows, run SOQL, and invoke Apex directly, with no browser involved.

This post walks through exactly how to wire that up: OAuth config, MCP connection, and what you can actually do once you're in.

What Headless 360 Actually Changes

Before Headless 360, connecting an external agent to Salesforce meant either writing your own connected app + REST adapter or cobbling together a third-party library. The platform wasn't designed to be consumed by agents; it was designed for humans clicking through tabs.

Headless 360 reframes the whole stack. Salesforce now exposes 60+ MCP tools covering:

Data operations: query records, create, update, upsert, delete (any standard or custom object)
Automation: invoke named Flows, trigger Process Builder actions, run Apex methods via REST
Reporting: execute saved reports and return structured data
Agentforce: start and resume Agentforce sessions, pass context, read session traces
Metadata: describe objects, list picklist values, read field metadata

The underlying transport is Model Context Protocol — JSON-RPC 2.0 over SSE or HTTP.¹ Your agent calls a tool (salesforce_query, salesforce_run_flow, etc.) and Salesforce executes it under the user's OAuth token.

Step 1: Create an External Client App in Salesforce Setup

Navigate to Setup → External Client Apps → New.² You're creating an OAuth 2.0 client that your AI agent will use (claude for example).

Key settings:

Field	Value
App Name	`MCP Agent` (or whatever labels your use case)
API Name	`MCP_Agent`
OAuth Flow	Authorization Code and Credentials
Callback URL	`https://claude.ai/oauth/callback` (for Claude Desktop) or `http://localhost:7878/callback` (for Claude Code / local agents)
Selected OAuth Scopes	`api`, `refresh_token`, `sfap_api`, `einstein_gpt_api`

The sfap_api scope unlocks Salesforce API Platform — required for Agentforce features.³ Without it, the hosted MCP server returns 403s on agent-related tools. The einstein_gpt_api scope is needed if you're routing through Einstein or hitting Prompt Builder endpoints.

Save and copy the Consumer Key. You'll need it in the next step.

Step 2: Locate Your Org's MCP Server URL

Every org's hosted MCP server endpoint follows this pattern:

https://<my-domain>.my.salesforce.com/mcp/v1

Where <my-domain> is your org's My Domain name.⁴ You can confirm it under Setup → My Domain.

For a scratch org or Developer Edition org, it looks like:

https://myorgname-dev-ed.develop.my.salesforce.com/mcp/v1

Step 3: Configure Your AI Client

Claude Desktop

Add this block to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "salesforce": {
      "type": "oauth",
      "url": "https://myorgname-dev-ed.develop.my.salesforce.com/mcp/v1",
      "oauth": {
        "clientId": "YOUR_CONSUMER_KEY_HERE",
        "authorizationUrl": "https://login.salesforce.com/services/oauth2/authorize",
        "tokenUrl": "https://login.salesforce.com/services/oauth2/token",
        "scopes": ["api", "refresh_token", "sfap_api", "einstein_gpt_api"]
      }
    }
  }
}

Restart Claude Desktop, click the plug icon, and you'll be prompted to authorize against your org. After that, the salesforce server appears in the tools panel.

Claude Code (CLI)

In your project root, create or update .mcp.json:

{
  "mcpServers": {
    "salesforce": {
      "type": "oauth",
      "url": "https://myorgname-dev-ed.develop.my.salesforce.com/mcp/v1",
      "oauth": {
        "clientId": "YOUR_CONSUMER_KEY_HERE",
        "authorizationUrl": "https://login.salesforce.com/services/oauth2/authorize",
        "tokenUrl": "https://login.salesforce.com/services/oauth2/token",
        "scopes": ["api", "refresh_token", "sfap_api"]
      }
    }
  }
}

Then run:

claude mcp auth salesforce

Claude Code opens a browser tab, you authenticate, and the token is stored locally. Subsequent runs reuse the refresh token.

Cursor / Windsurf / Other MCP Clients

These clients follow the same JSON format — they read a config file (usually mcp.json or similar) and handle the OAuth flow on first connect. Consult your client's docs for the exact config file location.

Step 4: What You Can Do With It

Once connected, here's a taste of what's now available to your agent without writing any integration code:

SOQL Query

The agent can call salesforce_query with a SOQL string:

SELECT Id, Name, StageName, Amount, CloseDate
FROM Opportunity
WHERE StageName = 'Negotiation/Review'
  AND CloseDate = THIS_QUARTER
ORDER BY Amount DESC
LIMIT 20

Results come back as structured JSON. Your agent can reason over them, generate follow-up queries, or feed them into another tool.

Trigger a Flow

{
  "tool": "salesforce_run_flow",
  "parameters": {
    "flowApiName": "Case_Escalation_Auto_Assign",
    "inputs": {
      "caseId": "5001R00000EXAMPLE",
      "escalationReason": "SLA breach detected by monitoring agent"
    }
  }
}

The MCP server runs the Flow in the context of the authenticated user and returns output variables.⁵

Invoke Apex via REST

If you've exposed an Apex class as a REST resource, the agent can call it directly:⁶

@RestResource(urlMapping='/agent/summarize-account/*')
global class AccountSummaryResource {
    @HttpGet
    global static Map<String, Object> summarize() {
        String accountId = RestContext.request.requestURI.substringAfterLast('/');
        Account acct = [SELECT Id, Name, Industry, AnnualRevenue,
                                (SELECT Id, Name, Status FROM Cases ORDER BY CreatedDate DESC LIMIT 5)
                        FROM Account WHERE Id = :accountId LIMIT 1];
        return new Map<String, Object>{
            'accountName' => acct.Name,
            'industry' => acct.Industry,
            'annualRevenue' => acct.AnnualRevenue,
            'recentCases' => acct.Cases
        };
    }
}

The agent calls this via salesforce_apexRest with the endpoint path and method. Your Apex runs server-side with full platform access.

Scope Gotchas and Common Issues

sfap_api scope isn't showing in your External Client App? It's only available if Agentforce is provisioned in your org.³ Developer Edition orgs now include this by default post-TDX; sandbox orgs tied to Enterprise Edition may need Agentforce licensing enabled first.

Token expiry: Salesforce access tokens expire after the session timeout configured in your org (default 2 hours).⁷ The refresh_token scope handles silent renewal, but if you've set a stricter session policy, agents will hit 401s mid-session. Check Setup → Session Settings → Force relogin after and set it to None for agent-facing External Client Apps.

IP restrictions: If your org uses Login IP Ranges on the profile, agent requests coming from cloud-hosted AI services will fail. Either relax IP restrictions on the profile assigned to the External Client App, or use a dedicated Integration profile with no IP range restrictions.

Read-only vs. read-write: You control what the MCP server can do by scoping the connected user's profile and permission sets. Run agents as a dedicated integration user with only the object-level permissions they need.

Where to Start

Spin up a Developer Edition org — post-TDX, every new DE org comes with Hosted MCP Servers pre-enabled at no cost.
Create your External Client App with the scopes above and wire it to Claude Desktop or Claude Code using the config shown here.[2]
Start with read-only queries — verify the connection works by asking your agent to pull 10 open Opportunities.
Layer in Flow invocation — pick a simple, well-tested Flow and let the agent trigger it from a natural language request.⁵
Add custom Apex REST endpoints for anything the 60+ built-in MCP tools don't cover — your business logic, your custom objects, your integration patterns.⁶

Headless 360 is the most architecturally significant thing Salesforce has shipped for developers in years. The platform is finally designed to be consumed by code — and agents — and not just browsers.

Model Context Protocol specification — Official MCP spec. ↩
External Client Apps overview — Salesforce Help. ↩
OAuth scopes reference — Salesforce Help. ↩
My Domain overview — Salesforce Help. ↩
Invoke a Flow via REST — Salesforce REST API Dev Guide. ↩
Apex REST web services — Salesforce Apex Dev Guide. ↩
Session security settings - Salesforce Help. ↩