Variables
Last updated:2026-01-28 10:21:11
The Agent Development Platform provides rich variable types for users to meet the needs of different business scenarios.
Type
From the perspective of usage scope, variables in the Agent Development Platform are divided into "application-level variables" and "workflow-level variables".
Application Level Variables
Application-level variables are visible and usable across the entire application. They include:
Type | Variable Description | Variable Name and Description |
System Variable | Variables provided by the platform by default. They can be read in all modules of the application but cannot be edited by users. Named as SYS.XXX . | SYS.UserQuery: The content of the current user query. SYS.RewriteQuery: The rewritten query in multi-turn dialogue. SYS.ChatHistory: Conversation history (in workflows, the number of history rounds can be configured). SYS.CurrentTime: Current system time (format: YYYY-MM-DD HH:MM:SS, e.g. 2025-08-10 11:01:18). SYS.RequestId: Request ID of the dialogue (the request_id parameter in API calls). SYS.Memory: Long-term memory content (available only after enabling “Long-Term Memory”). |
Environment Variable | Used to store sensitive data such as API keys and database passwords. A special secret data type is provided for encrypted storage and transmission. In the UI, values are displayed as *****. Readable by all application modules, but editable only in "Variables & Memory". Named as ENV.XXX. | Usage example: ENV.LLMSecretKey, which stores the secretKey used to call a large language model. Can be used in workflows or as an Agent tool. |
API parameter | Represent variables passed into the system when calling the Agent Development Platform API via the customer_variable field. Readable by all application modules, but editable only in "Variables & Memory". Named as API.XXX . For call details, see: Dialog API Documentation (HTTP SSE), Dialog API Documentation (WebSocket). | Usage example: API.UserName, where the user name is passed in as an API parameter so the dialogue can address the user more personally. |
Application Variable | Variables that can be passed across modules within the application. For example, Workflow A assigns a value to an application variable, and Workflow B reads it. Readable and writable by all application modules, but editable only in "Variables & Memory". Named as APP.XXX . | Usage example: APP.Notes, where Workflow A collects user notes and assigns them to APP.Notes, and Workflow B retrieves the notes and generates a summary. |
Workflow Level Variables
Workflow-level variables are visible and usable only within a single workflow. They include:
Type | Variable Description | Variable Name and Description |
workflow variable | Variables passed within a workflow. For example, a variable is assigned in branch A and read in branch B. Defined in the workflow’s start node, can be read in all nodes of the workflow, and assigned only in "variable assignment nodes". Named as WF.XXX . | Usage example: WF.OrderList, where branch A organizes the user’s order data and assigns it to WF.OrderList, and branch B retrieves it to place an order. |
Node input variable | Variables representing the input of the current workflow node. Editable and usable only inside the node. | - |
Node output variable | Variables representing the output of the current workflow node. Written inside the node and can be read by subsequent nodes. | - |
Applicable Scope
Since usage scenarios vary, the access scope of each variable differs as follows:
Variable Name | User Isolation Required or Not | Session Isolation Required or Not | |
Application Level Variables | System Variable (except SYS.Memory) | Yes | Yes |
| SYS.Memory | Yes | No |
| Environment Variable | No | No |
| API parameter | Yes | No |
| Application Variable | Yes | No |
Workflow Level Variables | workflow variable | Yes | Yes |
| Node input variable | Yes | Yes |
| Node output variable | Yes | Yes |
Note:
Since these variables exist in application and are conceptual under application, they are naturally "application isolated". No redundancy here.
"User isolation" means the same variable has different values for different terminal users. Terminal users are distinguished by the visitor_biz_id field passed in during API call (for details, see Dialogue End API Documentation (HTTP SSE), Dialogue End API Documentation (WebSocket)).
For example: API parameter userID (refers to user ID), Zhang San's userID is 001, Li Si's userID is 002, this is "user isolation". Environment variable APIKey (represents the key of a plug-in) has the same value for both Zhang San and Li Si, so it is not "user isolation".
"Session isolation" means the same variable has different values in different sessions.
For example: Zhang San's long-term Memory (SYS.Memory) can be used across sessions, so it is not "Session isolation". The input variables of workflow nodes are replaced with new values when switching sessions, which is "Session isolation".
In terms of isolation scope, application isolation > user isolation > Session isolation. Flexible use of various variables provided by ADP can meet the requirements of complex business scenarios.
Lifecycle
Since usage scenarios vary for each variable, their lifecycles differ as follows:
Variable Name | Lifecycle | |
Application Level Variables | System Variable (except SYS.Memory) | Session scope |
| SYS.Memory | Permanent (retention depends on configured memory duration) |
| Environment Variable | Permanent |
| API parameter | Permanent |
| Application Variable | Session scope |
Workflow Level Variables | workflow variable | Session scope |
| Node input variable | Session scope |
| Node output variable | Session scope |
Note:
“Session scope” means that the variable is valid only within the same session. For example: The default value of APP.UserName is “Adam.” In Session 1, Workflow A changes it to “Jason.” From then on, Workflow B in Session 1 reads APP.UserName as “Jason.” When a new Session 2 starts, Workflow A reads APP.UserName again, but the value reverts to the default “Adam,” not the “Jason” value set in Session 1.
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No
Feedback