Agent Script: The Critical Difference Between Actions vs. Reasoning Actions in Agentforce

In plain words: There are two action lists inside a subagent in Agentforce, and they serve completely different purposes. One list runs strictly because your logic explicitly called it. The other acts as a menu of tools that the AI model can choose to use if it thinks they are needed. Confusing these two is the most common mistake developers make when writing Agent Script.

📌 Example: Imagine a utility company's agent (like Meridian). It runs an "outage lookup" deterministically every single time by placing it in the actions block. However, it offers a "book a crew visit" tool inside reasoning.actions, so the model only offers to schedule a crew when the context of the conversation actually requires it.

Key Points: Understanding the Concept

• subagent.actions are available directly to your logic-based reasoning instructions. You explicitly command when these are called.
• subagent.reasoning.actions are available to the AI model to call autonomously as needed. These are referred to as tools.
• Tools must wrap a standard action or a utility function.
• Use the with keyword to bind input parameters to the tool, and use set to assign the tool's outputs back to variables.
• Use the available when keyword to deterministically control whether a tool is even offered to the model in the first place.
• Crucial insight: available when is a filter, not a prompt instruction. It dynamically changes what tools the model can see, rather than politely asking the model not to use a tool.
• Tools can also reference other subagents entirely, which is the underlying mechanism for agent delegation.

subagent
├─ actions:            <-- YOU call these explicitly
│    └─ deterministic, runs every time, in the exact order specified
└─ reasoning:
     actions:          <-- THE MODEL picks these (tools) based on context
       ├─ with         → binds input parameters
       ├─ set          → assigns outputs to variables
       └─ available when → filter: dynamically hides the tool entirely

🧠 You call, the model picks.
`actions` = You decide.
`reasoning.actions` = The model decides.

🧭 360 Card — actions vs. reasoning.actions

Rule: Anything that absolutely must happen goes in actions. Anything the conversation may or may not need goes in reasoning.actions.
Gain: You control exactly which steps are guaranteed and which are left to the AI's discretion.
Price: You must keep two distinct mental models straight, and the syntax differs slightly between them.
Limits: Salesforce enforces a limit of 15 actions per subagent across both lists combined.
Mirror (Everything as a tool): Putting everything in reasoning.actions gives maximum flexibility but minimum guarantee. The model may simply decide not to call a critical tool.
Later: The available when clause is one of the primary determinism mechanisms for controlling agent behavior.
At volume: Exposing fewer tools means better model selection accuracy, exactly like having fewer subagents means better topic routing.

⚠ INTERVIEW TRAP:
Do not say, "We give the agent the actions and it uses them." Which specific list you place an action in is a deliberate control decision. Interviewers ask this question specifically to see if you know there are two distinct lists and how they differ in behavior.

Core Q&A

Q: What is the primary difference between actions and reasoning.actions in Agentforce?

🎯 Say this first: You call the first one. The model picks from the second one. That choice decides who controls the execution of the step.

A: They represent the same underlying capability (executing an action), but they are exposed in two fundamentally different ways.

• Anything placed in the plain actions list runs strictly because a logic line called it—it is deterministic, runs every time, and executes in the exact order you wrote.
• Anything placed in reasoning.actions becomes a tool. The AI model reads its description and decides autonomously whether the conversation requires it.
• Therefore, the same Apex method can be used in either list. The choice is a strategic control decision, not a technical limitation.
• For tools, you bind parameters using with, assign outputs to variables using set, and gate availability using available when.
• That last one is genuinely a hard filter—the model cannot select a tool it cannot see. This is far more effective than just instructing the model not to use it in a prompt.
• My rule is simple: Anything that must happen goes in actions. Anything optional goes in reasoning.actions.

Q: Can I use the same Apex action in both lists simultaneously?

A: Technically yes, but architecturally it rarely makes sense. If an action is required deterministically for a process, call it directly. If it is optional, provide it as a tool. Having it in both lists usually indicates a flaw in your agent's design logic.

Q: What happens if I put too many tools in reasoning.actions?

A: The model has to evaluate the description of every single tool to decide which one to use. Giving it too many options dilutes its focus, increases latency, and significantly raises the chance of hallucinations or selecting the wrong tool. Keep the toolset lean and targeted to the subagent's specific topic.

📝 2-Minute Self-Check

Q1: Name the five action types available in Agentforce.
A1: Flow, Apex, Prompt Template, External Service, and MCP (Model Context Protocol).

Q2: How does the model actually pick an action from the tools list?
A2: By reading its description. Therefore, you must write action descriptions as clear selection criteria, not just technical summaries.

Q3: Your Apex action returns an Asset record, but the agent struggles to understand it. What is wrong?
A3: The model is being forced to infer the verdict from raw data. Instead, design your Apex to return a clear text decision alongside a reason string so the model doesn't have to guess.