跳转到主要内容

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 自己决定路径规则。

​
会话变量

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

​
智能体变量

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

​
如何写入变量

在节点（智能体节点和工具节点）的输出中，可以通过 write to memory 字段列表将输出结果写入会话变量。写入会话变量时，需要指定变量名和变量值来源。 Tool write variables 智能体输出写入会话变量时，可以将文本结果写入变量，也可以先制定 LLM 输出的结构，然后将结构中的属性分别写入会话变量。 Agent write variables 智能体定义结构化输出：仅在此节点未使用工具，知识库和子智能体时可用，而且 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 的演进路径）。