Agentforce utilizes data from your CRM and apps to provide insights and take action on your behalf. Developers guide the Agentforce reasoning engine in orchestrating actions through topic instructions. Sometimes, these instructions need to include important business rules, written in plain, simple language. These rules often use data or responses from private actions.

However, writing business-critical rules using private data as instructions presents two main challenges. First, the logic must be deterministic to ensure consistent outcomes. Second, you must protect private data within these instructions from alteration by the large language model (LLM).

For example, imagine there’s an action to check whether or not a user is verified. It gives a simple Boolean true or false response. But other actions also depend on that response. We must ensure that the LLM cannot change that Boolean value and should never hallucinate when instructions are given using this data.

So, how do we keep private structured data safe and ensure that instructions using this data are deterministic? By using variables and filters within Agentforce, developers can ensure deterministic logic, protect private data, and streamline agent orchestration. 

This post will guide you through practical examples showing how to effectively implement these features to enhance the security and efficiency of your agents.

What are variables in Agentforce?

Variables in Agentforce act as secure data containers, enabling developers to control agent logic and ensure deterministic outcomes. There are primarily two types of variables: context variables and conversation variables.

Context variables

If your agent connects to customer messaging channels, it automatically includes context variables that come from Messaging Session object fields, including custom fields. Context variables are prefixed with $Context and are read-only. They can be added to topic instructions using the syntax {!$Context.VariableAPIName}.

The screenshot below shows context variables that come out of the box with the Messaging Session object.

Example use case

Let’s assume that you want your agent to always respond in the end user’s language. You can write instructions as shown below using context variables.

“Always respond in {!$Context.EndUserLanguage} language”

The above instructions assume that when a new Messaging Session record is created (upon a new agent session initiation), the EndUserLanguage field is populated with the language of the user. This EndUserLanguage is mapped from a pre-chat or hidden channel variable using an Omni-Channel flow.

Conversation variables

Conversation variables are unique to the agent, and these variables hold a value only during a conversation session. There are conversation variables provided out of the box, but you can also create a custom conversation variable. Currently the variable can be of type text, boolean, or number. To learn how to create a new conversation variable, see the documentation. To use conversation variables in instructions, use the format {!VariableAPIName}.

The screenshot below shows conversation variables.

Note: The creation of conversation variables is only possible via the action output in Agent Builder. 

Example use case

Often, when building an agent, you need to save information from one action to use in another action. For example, imagine you have an action to verify a user. After verifying, this action gives you the user’s customer ID. Later actions might need this same customer ID.

Instead of writing extra topic instructions for each action to pass along the customer ID, you can use a custom variable. When you save the customer ID in a custom variable, other actions can easily reuse it.

For instance, in the Coral Cloud sample app, there’s an action that verifies a user and returns the customer ID. Later, there’s another action that lets the user book a session for a customer, and this action also requires the customer ID. By using a custom variable in Agentforce, you can automatically pass the customer ID from the verification action to the session booking action. This makes the agent instructions simpler and easier to manage.

Below is a simple diagram that helps visualize how the outputs from one action can be mapped back to custom variables, and then the same customer variables can be mapped back to the inputs of other actions.

The screenshot below from the Coral Cloud sample app shows the mapping of a variable to an action output in the Agent Builder.

And below is a screenshot from Agent Builder showing how to map the conversation variables to the inputs of an action. In this case, we map the Verified Customer ID variable to the inputs of the Create Booking action.

What are filters in Agentforce?

Filters in Agentforce use variables to create conditions that determine if topics or actions execute, enabling granular control over agent behavior. For example, a filter might check whether or not a custom conversation variable meets a certain condition (e.g., a Boolean flag is true) before proceeding with an action.

You can create filters that use variables in Agent Builder by writing simple expressions. An example is shown in the screenshot below. To learn more about creating a filter, check out the documentation.

Example use case

In the Coral Cloud app, we only allow actions like Create Booking, Get Experience Details, Get Personalized Schedule, or Get Sessions if the customer is verified. To track whether or not the customer is verified, we create a Boolean variable called IsCustomerVerified. This variable is set by an action called Verify Customer. Next, we make a filter named Is_Customer_Verified and use it for all the actions that require verification.

The diagram below visualizes this use case.

We also need a simple topic instruction (as shown below) that uses the variable to define the scope of user verification for Agentforce to reason correctly.

“Always check if the customer is verified before doing anything else. A customer is verified only if {!IsCustomerVerified} is true; if it’s false, the customer is not verified.”

The screenshot below shows how to add this filter to the Create Booking action.

Conclusion

We recently implemented Agent variables and filters for the Coral Cloud Sample app, and we have since seen a significant reduction in Agent instructions along with improved security. Check out the project and this pull request on GitHub to learn more about variables and filters, including its metadata. 

In conclusion, Agentforce offers powerful features for building secure, controlled, and efficient agent systems. By leveraging variables and filters, you can ensure deterministic business logic and control how your agent uses topics and actions — all while streamlining your agent’s decision-making process. This post provides a comprehensive overview of how context and conversation variables work together with filters to safeguard your private data and simplify agent orchestration.

More learning resources

• Documentation: Agent Variables
• Documentation: Filters for topics and actions
• GitHub: Coral Cloud sample app project

About the author

Mohith Shrivastava is a Principal Developer Advocate at Salesforce with a decade of experience building enterprise-scale products on the Salesforce Platform. Mohith is currently among the lead contributors and moderators on Salesforce Stack Exchange, a developer forum where Salesforce Developers can ask questions and share knowledge. You can follow him on LinkedIn.