AI Agents
Agent Script and the New Agentforce Builder
@media (min-width: 900px){.cmlms-ig–wide{display:block !important}.cmlms-ig–tall{display:none !important}}
Agent Script and the New Agentforce Builder
Learn how agents are defined in the new Agentforce Builder: one script that mixes plain-language instructions with logic that runs the same way every time.
Why Agent Script exists
Early agents were driven almost entirely by the LLM. You described subagents (then called topics) and actions, and the reasoning engine decided what to do. That works for open conversation, but businesses also have rules that must never be skipped: verify identity first, only refund under a limit, always log the case.
Agent Script is the language the new Agentforce Builder uses to define an agent. It lets you keep the LLM for what it is good at (understanding requests and writing replies) and write the must-happen steps as logic. Salesforce calls this mix hybrid reasoning.
Canvas view and script view
Every agent in the new builder is stored as Agent Script. The builder shows it two ways, and both edit the same agent:
- Canvas view: blocks and plain-language fields. Good for admins who build by describing behaviour.
- Script view: the script itself. Good for precise edits, reviewing logic, and working in VS Code or the Salesforce CLI with source control.
Agent creation moved to the new builder in July 2026. Agents built in the legacy builder keep working and can still be edited. Converting one creates a new version, and the old version stays active until you activate the new one.
The building blocks of a script
A script is made of named blocks. The ones to know for the exam:
| Block | What it holds |
|---|---|
| system | Agent-wide instructions and standard messages such as the welcome and error messages. |
| config | Settings for the agent, such as its name and type. |
| variables | Typed values the agent keeps during a session, for example a Boolean that says the customer is verified. |
| start_agent | The entry point. It runs first for each message and usually routes to the right subagent. |
| subagent | A job to be done (formerly a topic): its description, its reasoning instructions and its actions. |
Inside a subagent, the reasoning section has two parts: instructions (what to do this turn) and actions (the tools the LLM may choose from).
Prompt lines and logic lines
Instructions can contain two kinds of line. A line starting with a pipe (|) is text for the LLM. An arrow (->) starts logic that the platform runs itself before the LLM is asked anything.
reasoning:
instructions: ->
if @variables.loyalty_tier == "":
run @actions.get_loyalty_tier
with email=@variables.customer_email
set @variables.loyalty_tier=@outputs.tier
| Thank the customer and explain the rewards for the
| {!@variables.loyalty_tier} tier in two sentences.In this example the lookup always runs when the tier is unknown, the result is stored in a variable, and the LLM only writes the reply. The {!@variables.name} syntax is a template expression: it places a variable’s value into the text the LLM sees.
Actions, inputs and outputs
Actions are declared on the subagent with a description, typed inputs and outputs, and a target such as a flow, Apex class or prompt template. You then use them in two ways:
- Run them in logic with
run @actions.namewhen the step must happen. - Offer them to the LLM in the reasoning actions list, when the LLM should decide whether the step is needed.
When binding inputs, with order_id=@variables.order_id passes a known value, and with order_id=... tells the LLM to fill it from the conversation. set @variables.x=@outputs.y saves a result for later steps.
Any tool offered to the LLM can carry an available when condition. Until the condition is true, the LLM can’t see or pick the tool. This replaces the filters you attached to topics and actions in the legacy builder.
Moving between subagents
Use @utils.transition to @subagent.Name to move the conversation to another subagent. Transitions are one-way: the current subagent stops, and the target starts from its beginning. It does not come back on its own.
- As a tool in reasoning actions, the LLM decides when to transition, guided by its description.
- As logic (inside an
if), the transition happens whenever the condition is met. - Referencing another subagent directly runs it and returns, which is different from a transition.
Other utilities you should recognise: @utils.setVariables (let the LLM store values it heard, such as a preferred date), @utils.escalate (hand off to a human through the messaging connection’s route) and @utils.end_session.
Testing what you built
The builder’s preview shows a step-by-step trace of each test message: which subagent ran, which logic executed, which actions were called and what they returned. Use it while you build, then cover the agent with Testing Center before activation.
Quick checklist
- Canvas view and Script view edit the same Agent Script.
- Pipe lines go to the LLM; arrow lines are deterministic logic.
- Variables keep state reliably; template expressions put values into prompts.
- available when hides a tool until its condition is true.
- Transitions are one-way and start the target subagent from the top.
- Hybrid reasoning = LLM for conversation, logic for rules.
