Variables

Variables are an important part of the Gendial intelligent agent platform. Variables can pass information between nodes in the agent or be passed to the agent via API calls from the client.

It is worth mentioning that Gendial platform variables are not strongly typed; the values of variables are treated as strings. This can be likened to how people communicate with each other using natural language (strings), where the specific meaning and format of the string are analyzed and processed by the recipient. Similarly, if we compare the agent to a wise creature or person, the information exchanged between them is also in the form of natural language strings, with the receiving node determining the format or content of the string.

For example, when you call an API that returns a strongly-typed JSON object, you can serialize the object into a string using JSON.stringify and pass it to downstream nodes through variables. The downstream nodes can use the large language model to extract the necessary information or use a code node with JSON.parse to deserialize the string back into a strongly-typed object.

The platform has two types of variables: system variables and process output variables.

System Variables

System variables provide information from the Gendial platform, including the following types:

{{sys.userMessage}}

Represents the last message sent by the user. Use the format {{sys.userMessage}} to reference it in prompts.

{{sys.context}}

Represents the context from the knowledge base queried during the agent's processing. Use the format {{sys.context}} to reference it in prompts.

{{sys.history}}

Represents the complete conversation history between the user and the agent. Use the format {{sys.history}} to reference it in prompts.

{{sys.rephrasedHistory}}

When the agent’s settings enable multi-turn conversation and question reorganization, this variable retrieves the dialog history where the question has been reorganized by the large language model.

{{sys.agentDesc}}

Represents the agent’s description setting. Use the format {{sys.agentDesc}} to reference it in prompts.

{{sys.agentStylePrompt}}

Represents the agent’s conversation style setting. Use the format {{sys.agentStylePrompt}} to reference it in prompts.

{{sys.imageUrl}}

The image URL from the last message sent by the user that contains an image.

{{sys.fileUrl}}

The document URL from the last message sent by the user that contains a document.

{{sys.fileName}}

The original document name from the last message sent by the user that contains a document.

{{sys.files}}

New When interacting with agents, you can now upload multiple files at once (up to 100 files, each not exceeding 40MB), particularly suitable for file automation processing agents. Uploaded files can be accessed via the {{sys.files}} variable in nodes. This variable's value is a JSON array formatted as:

[
  {
      "fileName": "<original_filename>",
      "fileUrl": "<uploaded_file_url>",
  },
  {
      "fileName": "<original_filename>",
      "fileUrl": "<uploaded_file_url>",
  },
]

{{sys.now}}

The current system’s UTC time, which usually needs to be converted to local time for use.

{{sys.userInfo}}

The user information of the currently logged-in user (when the user logs in using the Gendial platform or native client), as a string of the following JSON object:

{
    "userId": "<unique user ID>",
    "displayName": "<user's display name>",
    "casUid": "<CAS account ID, only present when using CAS unified identity authentication>",
    "aadOpenId": "<Azure AAD ID, only present when using AAD unified identity authentication>"
}

Preset Variables

Preset variables refer to the pre-defined variables on the native Gendial client UI, used to control the behavior of the agent. The preset variables include the following two:

{{__search}}

This variable is controlled by the Online Search toggle on the Gendial client. When the toggle is turned on, its value is true; when turned off, its value is false.

{{__think}}

This variable is controlled by the Thinking toggle on the Gendial client. When the toggle is turned on, its value is true; when turned off, its value is false.

Process Output Variables

Process output variables are variables that the AI agent outputs according to its settings during execution. They can be set with output variable names in Input Nodes, Output Nodes, API Call Nodes, Blank Prompt Nodes, and Code Nodes to save the agent’s output into corresponding variables. These variables can then be referenced in subsequent process steps or prompts.

The same output variable name can be set multiple times across different nodes, with later nodes overwriting the values of earlier ones, similar to how a variable is reassigned multiple times in a program.

Output variables can be referenced directly as input parameters in API call nodes or referenced in prompts using the format {{variableName}}

Note：After referencing a variable, its value will be replaced in the corresponding location in the original text. If the variable’s value is a large block of text, this could make the prompt difficult to read and reduce its effectiveness.

For example, with the following prompt:

Find the corresponding information from {{content}} based on the user's request.

If content is a 10,000-word article, it will directly replace {{content}} with the entire text, making what was once a clear prompt difficult to read.

In this case, you should modify the original prompt format like this:

Find the corresponding information from the article content based on the user's request.

Article Content
======
{{content}}

With the new prompt, after variable replacement, it will still be readable and recognizable, and the large language model will process it more effectively.

Client-Side Variable Passing via API Calls

The intelligent agents provide API call formats compatible with the OpenAI API. In the API call, in addition to the fields required by OpenAI, you can also pass a "variables" object, which is a string dictionary or JavaScript object. These passed variables will be written into the agent’s runtime variables and used as regular process output variables.

Here is an example of a curl command that passes variables through the OpenAI API:

curl https://gendial.cn/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_SECRET" \
  -d '{
    "model": "$AGENT_GUID",
    "messages": [
      {"role": "user", "content": "Which is larger, 9.11 or 9.9?"}
    ],
    "variables": {
      "myvar": "My custom variable"
    }
  }'

Where AGENT_SECRET is the API key set in the agent’s configuration, and AGENT_GUID is the agent’s unique identifier, which can be obtained from the browser’s address bar.