Salesforce Agent Script: A Practical Guide

Salesforce Agent Script is here, and it's changing how we think about building AI agents on the platform. If you've been following Agentforce updates, you probably know the old approach: configure topics, add instructions in plain text, cross your fingers, and hope the LLM interprets everything correctly. Agent Script flips that model on its head by giving you actual programmatic control over agent behavior - while still letting the AI handle the conversational stuff it's good at.

I've spent the last few weeks getting my hands dirty with it, and honestly? It's the most interesting thing Salesforce has shipped for builders in a long time.

What Exactly Is Agent Script?

Agent Script is a new scripting language purpose-built for defining AI agent behavior inside Agentforce Builder. It went GA in February 2026 and was open-sourced at TDX 2026 (you can find the full spec on GitHub at github.com/salesforce/agentscript).

The core idea is simple but powerful: you get to decide which parts of your agent's workflow should run deterministically (meaning the same way every single time) and which parts should use LLM reasoning (where the AI gets to think and respond naturally).

Think of it this way. Before Agent Script, telling your agent to "verify the customer's identity before looking up their order" was a prompt instruction. The LLM usually got it right, but sometimes it would skip steps or get creative in ways you didn't want. Now, you can write that as actual logic that executes predictably, every time.

If you're brushing up on Salesforce terminology while learning Agent Script, salesforcedictionary.com is a solid reference for keeping all the new Agentforce terms straight.

The Two Types of Instructions

This is the part that clicked for me once I understood it. Agent Script has two distinct instruction types, and knowing when to use each one is basically the whole skill of writing good scripts.

Logic Instructions use the arrow syntax (->). These run deterministically - no AI interpretation, no variation. You use them for business rules, running actions, setting variables, and controlling flow. For example:

-> if @variables.order_total > 100:
->   set @variables.shipping = "free"
-> else:
->   set @variables.shipping = "standard"

Prompt Instructions use the pipe syntax (|). These are natural language lines sent to the LLM for interpretation. The AI reads them and decides how to respond to the customer:

| Greet the customer warmly and ask how you can help today
| If the customer seems frustrated, acknowledge their frustration before proceeding

The beauty is mixing them together. You can have deterministic business logic running alongside flexible, natural conversation. Your agent verifies identity the same way every time (logic), but handles the small talk and empathy naturally (prompts).

Subagents, Actions, and Variables

If you've worked with the older topic-based approach, here's a terminology update: what used to be called "topics" are now called subagents (as of April 2026). Each subagent handles a specific responsibility - billing questions, order tracking, returns, whatever your use case needs.

Actions are the tasks your subagents can perform. They can call Flows, prompt templates, Apex classes, or even external APIs. Here's what a simple action call looks like in practice:

-> run @actions.lookup_order with order_id=@variables.order_id
-> set @variables.order_status = @outputs.status

You can also let the LLM slot-fill action parameters from the conversation using the ... syntax. So if your customer mentions their order number in chat, the AI extracts it automatically:

-> run @actions.lookup_order with order_id=...

Variables work like you'd expect - they store data throughout the conversation. You reference them with the @variables namespace, and they persist across the subagent's lifecycle.

One pattern I've found really useful: run a before_reasoning block to pull in context before the AI starts thinking. Verify the customer, load their account info, check business hours - all before the LLM even fires up. It makes your agents faster and more accurate because the AI starts with the right context instead of having to figure it out.

Practical Tips From Actually Using It

After building a few agents with Agent Script, here are the things I wish someone had told me on day one.

Start small and separate. Don't try to write one massive script. Break your agent into focused subagents - one for identity verification, one for order lookup, one for escalation. Small scripts are easier to test, debug, and maintain. The transition to @subagent.billing syntax makes it clean to hand off between them.

Use comments liberally. The # syntax works just like Python comments. Future you (or the admin who inherits your work) will thank you. I've started adding comments that explain the why behind business rules, not just the what.

The Canvas view is your friend. Agentforce Builder gives you two views: Canvas (visual blocks) and Script (raw code). I usually start in Canvas to sketch out the flow, then switch to Script view for fine-tuning. The / shortcut in Canvas lets you quickly add common patterns like if/else blocks, and @ lets you reference resources.

Test with edge cases early. The deterministic parts of your script are predictable by definition, but the handoff points between logic and prompt instructions are where things get interesting. What happens when the LLM can't slot-fill a required parameter? What if a customer gives ambiguous input? Build those scenarios into your testing from the start.

For more Salesforce terminology and concepts explained in plain language, check out salesforcedictionary.com - it's been really helpful as a quick reference while working through new features like this.

Why This Matters for Your Career

Here's the thing that not enough people are talking about: Agent Script is open source. Salesforce published the full language specification, grammar, parser, and compiler on GitHub. That's a pretty big deal.

It means this isn't just a Salesforce-specific skill you're learning. Understanding how to blend deterministic logic with AI reasoning is becoming a core competency across the entire tech industry. The patterns you learn writing Agent Script - context engineering, hybrid workflows, guardrail design - transfer directly to other agentic AI platforms.

If you're an admin, you don't need to become a developer to use this. The Canvas view in Agentforce Builder and the built-in AI assistant handle the heavy lifting. You describe what you want in plain English, and the builder generates the Agent Script for you. But understanding the underlying concepts will make you significantly better at building reliable agents.

And if you're a developer? The Script view with syntax highlighting and real-time validation feels like working in a proper IDE. You can even use Agentforce DX to work with scripts in your local dev environment and push them through your CI/CD pipeline.

Salesforce also published a recipe repository at github.com/trailheadapps/agent-script-recipes with practical examples covering common patterns. It's a great starting point.

Getting Started Today

The fastest path to learning Agent Script:

1. Open the Trailhead module "Explore the New Agentforce Builder for AI Agents" - it walks you through the basics with hands-on exercises
2. Clone the agent-script-recipes repo and read through the examples
3. Build a simple service agent in a Developer Edition org - start with identity verification and one action
4. Gradually add complexity - conditional logic, multiple subagents, transitions between them

Agent Script represents a real shift in how Salesforce thinks about AI agent development. It's no longer "write a prompt and hope for the best." You get actual control, actual reliability, and actual developer tooling. That combination is rare in the AI space right now.

I'd love to hear what you're building with Agent Script. Drop a comment below with your use case or any questions - I'm happy to dig into specific patterns. And if you're still wrapping your head around all the new Agentforce terminology, salesforcedictionary.com has you covered.