会话变量

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

功能定位

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

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

技术实现

系统变量

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

系统变量：

系统变量名称	描述
sys_language	系统使用的语言
user_email	用户的电子邮件地址
user_timezone	用户所在的时区

会话变量

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

数字专家的会话变量

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

提示词中插入会话变量

智能体变量

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

如何写入变量

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

工具结果写入会话变量

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

智能体结果写入会话变量

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

技术细节

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

示例代码结构：

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 的演进路径）。

典型应用场景

a. 多模态对话

// 定义变量：支持文本、图像、结构化数据
const state = {
  text_input: { /* ... */ },
  image_attachments: { /* ... */ },
  extracted_data: { /* ... */ },
};

b. 长上下文推理

• 通过 title 总结会话标题。
• 使用 summary 通道存储压缩后的摘要，平衡性能与信息完整性。

c. 个性化交互

• 在 memories 通道中存储用户偏好。
• 通过 messages 通道实现跨对话周期的状态保持。