> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 会话变量

**会话变量** 是 XpertAI 智能体平台一项核心功能，旨在为智能体对话系统提供动态、可扩展的上下文管理能力。会话变量分为 **系统变量**，**自定义全局变量** 和 **节点变量** 三种类别。

## 功能定位

**会话变量** 是 XpertAI 智能体平台中用于存储和管理对话上下文的核心数据结构。它允许开发者在多轮对话中：

* **持久化关键信息**：例如用户意图、历史对话记录、中间推理结果等。
* **支持动态更新**：通过节点（Nodes）和边（Edges）的协作，实现对话状态的实时演进。
* **隔离与共享控制**：灵活管理公共变量（如用户输入）和私有变量（如内部中间状态）。

## 技术实现

### 系统变量

系统变量是由平台提供的预定义变量，如用户语言、时区、邮箱等，这些用户信息可以在用户设置里进行修改。

常用系统变量：

| 系统变量名称               | 描述                           |
| -------------------- | ---------------------------- |
| `sys.language`       | 系统使用的语言                      |
| `sys.user_email`     | 用户的电子邮件地址                    |
| `sys.timezone`       | 用户所在的时区                      |
| `sys.date`           | 当前日期                         |
| `sys.datetime`       | 当前本地时间                       |
| `sys.workspace_path` | 当前共享 workspace 目录路径          |
| `sys.workspace_url`  | 当前共享 workspace 目录 URL        |
| `sys.thread_id`      | 当前会话线程 ID，可在提示词中用于自定义路径或隔离策略 |

### Workspace Directory 规则

`sys.workspace_path` 和 `sys.workspace_url` 始终指向 Xpert runtime 与 sandbox 实际使用的共享 workspace 根目录：

* project 场景使用共享目录 `/project/<projectId>/`
* 非 project 场景使用共享目录 `/user/<userId>/`
* 默认不再额外拼接 conversation 级子目录

如果你的提示词或工作流需要按线程进一步做隔离，可以显式使用 `sys.thread_id` 自己决定路径规则。

### 会话变量

**会话变量** 作为数字专家内所有智能体共享的状态变量，实现了信息在各智能体之间的传递和演进。用户可以在数字专家工作室的菜单按钮中找到“变量”按钮打开会话变量面板进行添加。

<img src="https://mintcdn.com/xpertai/CUk-Ab9Rv7YWeJmd/public/img/ai/variables/conversation-variables.png?fit=max&auto=format&n=CUk-Ab9Rv7YWeJmd&q=85&s=9048af419dc9d1af0537b3f50a730dd3" alt="Conversation variables" width="1218" height="807" data-path="public/img/ai/variables/conversation-variables.png" />

在提示词中插入会话变量，请使用 `{{` 来插入变量名：

<img src="https://mintcdn.com/xpertai/CUk-Ab9Rv7YWeJmd/public/img/ai/variables/prompt-use-variables.png?fit=max&auto=format&n=CUk-Ab9Rv7YWeJmd&q=85&s=180a9357833e4d6b590c09e0571ae7b1" alt="Conversation variables insert variables" width="1216" height="854" data-path="public/img/ai/variables/prompt-use-variables.png" />

### 智能体变量

智能体变量是智能体内部的状态变量，用于存储智能体在对话中的状态信息。每个智能体可以定义私有的会话变量（开发中）以保持数据的隔离。

## 如何写入变量

在节点（**智能体**节点和**工具**节点）的输出中，可以通过 **write to memory** 字段列表将输出结果写入会话变量。写入会话变量时，需要指定变量名和变量值来源。

<img src="https://mintcdn.com/xpertai/CUk-Ab9Rv7YWeJmd/public/img/ai/variables/tool-write-variables.png?fit=max&auto=format&n=CUk-Ab9Rv7YWeJmd&q=85&s=9205d41cd9f679b0f968bf780cda65e3" alt="Tool write variables" width="1214" height="803" data-path="public/img/ai/variables/tool-write-variables.png" />

智能体输出写入会话变量时，可以将文本结果写入变量，也可以先制定 LLM 输出的结构，然后将结构中的属性分别写入会话变量。

<img src="https://mintcdn.com/xpertai/CUk-Ab9Rv7YWeJmd/public/img/ai/variables/agent-write-variables.png?fit=max&auto=format&n=CUk-Ab9Rv7YWeJmd&q=85&s=e1f0dd976de71c7f12234aecf839252d" alt="Agent write variables" width="1210" height="801" data-path="public/img/ai/variables/agent-write-variables.png" />

智能体定义**结构化输出**：仅在此节点未使用工具，知识库和子智能体时可用，而且 LLM 本身要支持结构化输出能力。

### 技术细节

* **多通道设计**：每个变量或者智能体对应一个独立的 State Channel。
* **类型安全**：通过 Annotation 对象定义变量的数据类型（如字符串、数组、自定义对象）。
* **更新策略**：每个通道可配置不同的 Reducer 函数（如 `append` 追加历史消息、`replace` 覆盖临时结果）。

示例代码结构：

```typescript theme={null}
const state = {
  messages: {
    value: (prev: Message[], curr: Message[]) => [...prev, ...curr], // 追加模式
    default: () => [],
  },
  context: {
    value: (prev: Context, curr: Context) => ({ ...prev, ...curr }), // 合并模式
    default: () => ({ topic: "", entities: [] }),
  },
};
```

## 核心优势

#### **a. 动态上下文管理**

* **多轮对话支持**：通过 `messages` 通道自动维护对话历史，支持基于上下文的推理。
* **条件分支控制**：利用变量值驱动边（Edges）的逻辑跳转（如根据 `user_intent` 切换处理节点）。

#### **b. 高效协同** （开发中）

* **并行处理**：多个节点可在同一 Super-Step 中异步更新不同变量（如同时处理语义解析和情感分析）。
* **增量更新**：通过 Reducer 函数避免全量状态复制，提升性能。

#### **c. 可观测性与调试**（开发中）

* **状态快照**：每个 Super-Step 后生成完整的对话变量快照，支持回放和诊断。
* **变量级监控**：可单独追踪关键变量（如 `context.topic` 的演进路径）。