Read the Language Behind the Canvas

Learning Objectives

After completing this unit, you’ll be able to:

• Explain why Agent Script pairs deterministic logic with LLM reasoning.
  
• Identify the top-level blocks in an Agent Script file.
  
• Describe how the reasoning loop builds a prompt from logic instructions and prompt instructions.
  
• Declare regular, linked, and default-initialized variables in the variables block.
  

What Is Agent Script?

Agent Script is a purpose-built Salesforce language for defining how an agent behaves, thinks, routes, and responds. Its defining trait is that it blends two things that usually live in separate tools—the flexibility of natural-language prompts and the reliability of deterministic, programmatic logic. You decide which parts of your agent's behavior are fixed rules and which parts the LLM figures out. That blend is called hybrid reasoning, and it's the heart of Agent Script.

Review Your Experience with Agent Script

In Programmatic Instructions in Agentforce, you gave the service agent for Coral Cloud Resorts some serious new powers. You taught it to recognize Platinum and Gold loyalty tiers, thank customers accordingly, and issue resort credits—but only to eligible members, and only once per session. You did most of that work by working in the Canvas—moving an If/Else block here, adding an action filter there.

But twice, you switched to Script view. Those moments—the ones where you typed commands instead of navigating the Salesforce UI—were Agent Script. This badge is about everything that language can do.

Here's the key idea—the Canvas doesn't build a different kind of agent than Script view. It builds the exact same agent. Every block you drag, every filter you add, every conditional you configure—Agentforce stores all of it as Agent Script in a single text file. The Canvas is one way to edit that file. Script view is another. Once you can read the language, you know precisely what your agent will do, review what a teammate (or an AI tool) wrote, and reach features the Canvas doesn't surface.

Three Ways to Work with Agent Script

Check out the different ways you can work with Agent Script. You already have experience using the first way.

In Agentforce Builder (Script view): Open an agent and select Canvas in the upper right, and then select Script. Script view gives you the raw editor with syntax highlighting, autocompletion, and inline validation. You can switch between Canvas and Script freely—they each edit the same agent.

With Agentforce DX and VS Code: Use the Agentforce DX extension to retrieve your agent from the org into a local Salesforce DX project. Your agent lives in an .agent file inside a metadata container called an AiAuthoringBundle. You edit it in VS Code with full language support, then deploy it back. This is the pro-code path—version control, code review, the works.

With an AI coding agent: Tools such as Agentforce Vibes or Claude Code generate and edit Agent Script for you and use skills that call Agentforce DX under the hood. You describe what you want in natural language. The AI writes the script. You review, refine, and deploy. Knowing the language yourself is what makes that review meaningful—you can catch a mistake before it ships.

The File and Its Blocks

Agent Script files are made up of blocks, or top-level sections that serve one purpose. Blocks are sequenced in a set order, and the language is whitespace-sensitive—like in Python or YAML—so indentation is part of the syntax.

At minimum, an agent needs system, config, and start_agent. Everything else you add as the agent grows. The CC Service Agent has all of these—you just met them through the Canvas instead of as code.

The Reasoning Loop Is How Prompts Get Built

An essential thing to understand about Agent Script is how it assembles a prompt. When a customer sends a message, Agentforce starts at start_agent (which you can think of as the entry point subagent) and reads the reasoning instructions top to bottom, building up the prompt as it goes. This same process occurs with every subagent that is run.

There are two kinds of instructions, and they’re constructed differently on purpose.

• Hybrid instructions: These live under -> and contain a mix of deterministic instructions and natural-language prompts. In the deterministic instructions, you tell Agentforce to evaluate conditions, run actions, set variables, and transition between subagents.
  
• Prompt instructions: These start with | and add natural-language text to the prompt. LLMs receive this text and use it to decide how to respond. This is the part you wrote when you entered "Thank the customer for being a Platinum member."
  

Here's the Experience Management subagent expressed in Script view—the same logic you built.

subagent Experience_Management:
    description: "Helps verified customers explore experiences and rewards loyalty tiers."
    reasoning:
        instructions: ->
            if @variables.LifetimeValue >= 50000:
                | Thank the customer for being a Platinum member!
            if @variables.LifetimeValue < 50000 and @variables.LifetimeValue >= 25000:
                | Thank the customer for being a Gold member!

Read it top to bottom. The logic instructions check LifetimeValue first. Only the matching branch's prompt instruction gets added to the prompt. This way, a Platinum member's prompt never contains the Gold message. Agentforce resolves all the logic, then sends just the resulting prompt to the LLM. That sequence—logic first, then prompt—is the reasoning loop.

This is why the "different prompt per context" trick you used in the previous badge works. Agent Script uses deterministic logic to decide before the LLM is ever involved, so the LLM isn’t choosing which thank you to use.

Variables Are Your Agent's Memory

You created two variables—LifetimeValue (a number, default 0) and isCreditIssued (a boolean, default False). In Script view, those declarations live in the variables block.

variables:
    LifetimeValue: mutable number = 0
        description: "The value of Lifetime_Value__c from the Contact record."
    isCreditIssued: mutable boolean = False
        description: "Whether the customer has already been issued a resort credit this session."

A few things to notice, because they explain choices you made.

• Mutable means the agent can change the value: Both of yours are mutable. The agent sets LifetimeValue from the contact record and flips isCreditIssued to True after issuing a credit. Leave off mutable and the value can never change.
  
• The = 0 and = False are default values: Remember being told to set isCreditIssued to False even though Agentforce defaults booleans to False anyway? In Script, the reason is simple—your conditional checks isCreditIssued == False. Having a sensible default guarantees that comparison behaves correctly from the first turn. Initialize variables that feed conditionals.
  
• The description documents the variable for your teammate: And when you want the LLM to fill a variable from the conversation, it tells the LLM what to put there.
  

Linked Variables—Data from the Session

Open the Variables tab on the CC Service Agent and you'll find more than the two you made. Variables such as EndUserId, ContactId, and EndUserLanguage are listed with a source of Messaging Session. Those are linked variables—read-only values bound to the session context at runtime.

In Script view, the Messaging Session source in Canvas becomes an explicit source on the declaration.

variables:
    session_id: linked string
        source: @MessagingSession.Id
        description: "The ID of the current messaging session."
    contact_id: linked string
        source: @MessagingEndUser.ContactId
        description: "The contact ID of the end user."

You reference a linked variable the same way as any other—@variables.contact_id—but you can never set it, and it can't have a default value. It injects when the session starts and stays put. Linked variables are how your agents know who it's talking to without asking, which is handy for routing, logging, and personalization.

Now you can read the file, the blocks, the reasoning loop, and the variables that power it. You're ready to write the parts of the language that control where a conversation goes, and it all starts with routing.

Resources

• Agentforce Developer Guide: Agent Script Reference
• Agentforce Developer Guide: Agent Script Common Patterns
• Trailhead: Programmatic Instructions in Agentforce