How to Write Agentforce Variables Correctly in Instructions

In Agentforce, variables inside instructions help the agent behave consistently, avoid guessing, and follow strict rules instead of relying on probabilistic LLM behavior. The most important thing is to use the correct syntax, because even a small formatting mistake can prevent the platform from resolving the variable value.

A context variable must use this exact format: {!$Context.VariableAPIName}. The key idea is that context variables are identified by the $Context prefix. They typically come from system context, channel context, or messaging session field mappings, and they are often read-only. This means the agent can reference them, but should not be expected to change them during the conversation.

A conversation variable or custom variable must use this exact format: {!VariableAPIName}. Notice that there is no $Context prefix here. Conversation or custom variables are used to store information during the interaction, so the agent can reuse it later in the same session and stay consistent without repeatedly asking the user the same questions.

Here are the two required examples. The first one uses a context variable: “Always use the {!$Context.EndUserLanguage} language in responses.” This forces the agent to respond in the language provided by the session context. The second one uses a conversation variable: “Use the following process... {!TroubleshootingSteps}” This inserts a stored list of troubleshooting steps into the agent’s response, so the agent can keep following the same resolution process across the conversation.

There are three common mistakes that cause problems. The first is incorrect syntax, such as missing the exclamation mark, missing curly braces, or writing the variable name in the wrong format. When the syntax is wrong, the system cannot resolve the variable and the instruction becomes unreliable. The second mistake is confusing a context variable with a conversation or custom variable. If the variable is a context variable, it must include $Context. If it is a conversation or custom variable, it must not include $Context. Mixing them up typically breaks the instruction or causes unexpected behavior. The third mistake is expecting a read-only context variable to be changeable. Context variables often cannot be updated by the agent during the conversation. If you need a value that can be updated as the conversation progresses, you should store it in a conversation variable or a custom variable designed for that purpose.

Next, it is important to understand conversation variables in more depth, because they are the mechanism that allows the agent to “remember” information during a single session and reuse it reliably across topics and actions.