Mastering Salesforce Agentforce Variables: Explicit Memory for AI Agents

💬 In plain words: A variable securely stores a specific fact for the rest of an AI conversation. Without variables, you are blindly trusting the AI model to remember things accurately. By using variables, you lock that fact in place so it never drifts, hallucinates, or disappears.

Key Points

• Never rely on an LLM's implicit memory; use explicit state management via variables to store persistent facts across turns.
• Salesforce Agentforce supports multiple data types, including string, number, boolean, object, date, id, and list.
• Initialize default variable values at the beginning of the agent session (e.g., inside start_agent).
• Use distinct syntax to reference variables in backend logic versus frontend prompt instructions.

The Core Concepts

Variables allow your agents to manage state reliably. When designing conversational logic in Salesforce Agentforce, understanding how to classify and reference data is crucial.

• Standard Types: Your primary building blocks include string, number, boolean, object, date, id, and list.
• Mutable vs. Immutable: Always mark a variable as mutable if you expect its value to change or update during the course of the session.
• Linked Variables: A linked variable automatically binds its value directly to the output of an underlying action, such as an Apex class or a Salesforce Flow.
• Initialization: Best practice dictates setting initial default values inside start_agent. Because every new user request begins there, it ensures your data environment is clean from the start.

📌 Real-Life Example: Imagine an energy utility company named Meridian. When a user reports a power outage, the agent immediately captures and stores meter_id, is_outage_confirmed, and estimated_restore. Because these are safely stored as explicit variables at the beginning of the chat, any subsequent sub-agent or troubleshooting topic can seamlessly read those values without ever forcing the customer to repeat their information.

⚠️ Developer Traps to Avoid:

• The Linked List Limitation: Currently, a linked variable cannot be formatted as a list type.
• The Default Value Syntax: Never use three dots (...) to signify an empty default value. In Agentforce, three dots invoke slot-filling syntax, prompting the AI to ask the user for missing data. To define a blank default, use standard empty quotes ("").

Syntax in Action

When working with variables, the syntax you use depends entirely on where you are trying to access the data.

variables:
  meter_id:            mutable string  = ""
  is_outage_confirmed: mutable boolean = False
  estimated_restore:   mutable string  = ""
  refund_amount:       mutable number  = 0

# 1. Referencing inside system script or logic conditions:
@variables.meter_id

# 2. Referencing inside prompt text instructions (Merge Syntax):
{!@variables.meter_id}
  

Notice that inside prompt text, you must wrap the reference in merge syntax brackets. This guarantees the actual stored value is injected into the plain English instructions before the LLM processes them.

🧠 Store, don't trust. Never ask the AI model to remember a core fact across conversation turns. Lock it in a variable.

🧭 360 Card — Variables

Rule: Any factual detail used more than once in a session must be stored in a variable, set once, and read indefinitely thereafter.

Gain: Values locked in variables cannot hallucinate or drift over time. Furthermore, variables provide concrete values that you can run automated assertions against during testing.

Price: Implementing explicit variables requires more upfront state design and naming convention overhead than simply letting the AI wing it.

Limits: Linked variables currently do not support list data types.

Mirror: Relying on the LLM's conversation history often works just well enough to hide the critical edge cases where it completely fails. Don't fall for the trap of implicit memory.

Later: These same explicit variables are the foundation for your post-generation guardrails and "after-reasoning" evaluations.

Core Q&A

Q: How does an agent remember something across a long conversation?

🎯 Say this first: In explicitly defined variables. You should never rely on the AI model to accurately recall a fact on its own.

A: Explicit state beats implicit recall. When you declare a variable, you create a rigid memory slot for the agent. Once a value is fetched—like an account number or eligibility status—it is immediately stored. Every subsequent sub-agent reads that hard-coded value instead of executing redundant queries or annoyingly asking the user again. This is also how you build testable agents; a stored variable can be verified in a test script, whereas an AI's abstract "memory" cannot.

Q: Where is the best place to set initial variable values?

A: Generally, you should initialize them within the start_agent configuration. Because every user interaction initiates from this core entry point, you can guarantee your foundational variables are properly scoped and populated before complex logic begins.

Q: What is the functional difference between mutable and linked variables?

A: A mutable variable is a dynamic container that the agent can actively update or overwrite based on the user's conversational inputs. A linked variable, however, behaves more like a direct pipeline—it is explicitly bound to the output of a predefined backend action (like a Salesforce Flow or Data Cloud query) and populates automatically upon execution.