Send Agent Variables with the Agent API
When starting a session or sending messages to the agent, you can pass in context variables and custom variables. The agent can use these variables during subsequent turns in the conversation. In addition to pre-defined context variables, you can pass additional information to the agent using custom variables. For example, you can pass an email as a variable and then ask the agent to fetch the call records for that email.
You can control whether variables are accessible to the API through Agentforce Builder or the Metadata API.
To learn more about variables, see Agent Variables in Salesforce Help.
The following example contains variable data that can be used in an Agent API request. This example includes a context variable ($Context.EndUserLanguage) and a custom variable ($inUserEmail).
Many variables are read-only and can only be set during the start session call. By default, context variables (which have the $Context prefix) aren't editable after the session has started, except for the $Context.EndUserLanguage variable. You can only modify editable variables during a send message call. When specifying variables that are derived from custom fields, omit the __c suffix. For instance, Conversation_Key__c becomes $Context.Conversation_Key.
When creating agent variables in Agentforce Builder, verify that Allow value to be set by API is checked.
Variables can be configured using the Metadata API through ConversationVariable (in BotVersion and BotTemplate) and ConversationContextVariable (in Bot and BotTemplate). These metadata types can be useful if you want to affect how variables are accessed and used.
The following tables contains the key fields associated with agent variables in ConversationVariable and ConversationContextVariable.
| Field Name | Description |
|---|---|
dataType | The data type of the variable (Text, Number, Boolean, Object, Date, DateTime, Currency, Id). |
description | A description of this variable. This value is used by the Agentforce planner service. |
developerName | The unique name of the variable. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. |
includeInPrompt | Indicates whether the variable is included in the prompt sent to the Agentforce model. |
label | A human-readable label that identifies the variable throughout the Salesforce user interface. |
visibility | Determines which components can set this variable. If the visibility is internal, the variable can only be set by an action output in Salesforce. If the visibility is external, the variable can be set by an action output as well as an API, such as Agent API. (This field is only applicable to ConversationVariable.) |
To review all the fields associated with these Metadata types, see ConversationVariable and ConversationContextVariable in the Metadata API Developer Guide.
- Salesforce Help: Agent Variables
- Agent API Developer Guide: Get Started with Agent API
- Agent API Developer Guide: Agent API Examples
- Agent API Reference Guide: Variables Object
- Metadata API Reference Guide: ConversationVariable and ConversationContextVariable