变量用来存储动态变化的信息，使智能体能够根据不同情况灵活调整，满足用户的特定需求和偏好。扣子智能体支持使用系统变量和用户变量。你可以在工作流、插件中引用预设的系统变量；也可以创建用户变量来保存用户个人信息，例如语言偏好等。 ## 变量类型 使用扣子开发智能体时，可以通过系统变量和用户变量来满足不同的业务需求和场景。每种变量类型都有其特定的用途和优势，以下是对这些变量类型的介绍说明。 ### 系统变量 系统默认创建了用户信息、飞书、音视频等类别的系统变量，你可以根据实际业务需求选择开启所需的系统变量。开启后，系统将在用户请求时自动存储变量数据，这些数据为只读状态，用户或开发者均无法修改。你可以通过工作流节点例如问答、结束等节点获取系统变量值。 每个系统变量获取的数据不同，支持使用的渠道也不同，具体说明如下： | **变量分类** | **变量名称** | **变量描述** | **数据类型** | **支持渠道** | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | ------------ | | 用户信息 | sys\_uuid | 扣子账号 UID、发布渠道 ID 与智能体 ID 组合后的编码值，用于识别和追踪用户行为。sys\_uuid并非扣子账号的 UID。 | String | 全部渠道 | | sys\_longitude | 扣子用户实时位置的经度信息。使用此变量会触发用户授权。 | String | 扣子商店和扣子模板 | | | sys\_latitude | 扣子用户实时位置的纬度信息。使用此变量会触发用户授权。 | String | 扣子商店和扣子模板 | | | sys\_lat\_lon | 扣子用户实时位置的经纬度信息，纬度在前，经度在后。使用此变量会触发用户授权。 | String | 扣子商店和扣子模板 | | | sys\_lon\_lat | 扣子用户实时位置的经纬度信息，经度在前，纬度在后。使用此变量会触发用户授权。 | String | 扣子商店和扣子模板 | | | 飞书 | sys\_lark\_chat\_id | 飞书群的群 ID。详细说明，请参考[群 ID 说明](https://open.larkoffice.com/document/server-docs/group/chat/chat-id-description#394516c9)。例如搭建用于总结飞书群消息的智能体时，可以在工作流中添加[飞书消息](https://www.coze.cn/store/plugin/7395041302766944275?from=add_plugin_menu)插件中的get\_chat\_messages工具，并设置工具中的container\_id参数引用sys\_lark\_chat\_id变量，当智能体被添加到不同的飞书群时，它能够自动识别并获取当前群的 ID，并对该群内的聊天消息进行高效总结。 | String | 飞书 | | sys\_lark\_chat\_mode | 飞书群的群模式，包括普通对话群组、话题群组和单聊。详细说明，请参考[群组管理概述](https://open.larkoffice.com/document/server-docs/group/chat/intro)。例如在搭建一个飞书消息相关的智能体时，可以引用sys\_lark\_chat\_mode变量获取群模式。当智能体被发布到飞书后，可以根据群模式动态调整消息的处理逻辑。 | String | 飞书 | | | sys\_lark\_open\_id | 飞书用户在应用内的身份 ID。详细说明，请参考[用户身份](https://open.larkoffice.com/document/home/user-identity-introduction/introduction)。例如在搭建智能客服智能体时，可以引用系统变量sys\_lark\_open\_id，当智能体被发布到飞书后，可以识别并验证用户身份，根据用户的历史咨询记录和偏好，提供定制化的服务建议，提高客服效率和用户满意度。 | String | 飞书 | | | sys\_lark\_thread\_id | 飞书的话题 ID。详细说明，请参考[话题概述](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/thread-introduction)。例如搭建基于话题的知识管理智能体时，可以在工作流中添加[飞书消息](https://www.coze.cn/store/plugin/7395041302766944275?from=add_plugin_menu)插件中的get\_thread\_messages工具，并设置工具中的container\_id参数引用sys\_lark\_thread\_id变量。当智能体被添加到飞书群时，它能够自动获取历史话题的 ID，并根据话题 ID 对信息进行分类和整理。 | String | 飞书 | | | 音视频 | sys\_voiceprint\_name | 声纹名称，用于标识对话人的身份，例如爸爸、妈妈等。例如你在智能体中开启声纹识别功能后，可以通过sys\_voiceprint\_name变量，以实现用户在与智能体语音通话时，智能体能够从声纹组中匹配说话人的身份，并根据匹配到的身份信息，提供针对性的回复。详细说明，请参考[声纹识别](https://www.coze.cn/open/docs/guides/voiceprint_recognition)。* 打开**声纹识别**功能后，sys\_voiceprint\_name变量自动为启用状态。* 关闭**声纹识别**功能后，sys\_voiceprint\_name变量自动为关闭状态。 | String | API | | sys\_voiceprint\_info | 声纹的描述信息，由用户自己定义，例如你可以添加用户信息爸爸是四十岁男性，关注科技类新闻，喜欢打球。在智能体声纹识别功能中，你还可以通过sys\_voiceprint\_info变量来补充用户信息，使用智能体能够根据该信息提供更贴切、更个性化的回复。详细说明，请参考[声纹识别](https://www.coze.cn/open/docs/guides/voiceprint_recognition)。* 打开**声纹识别**功能后，sys\_voiceprint\_info变量自动为启用状态。* 关闭**声纹识别**功能后，sys\_voiceprint\_info变量自动为关闭状态。 | String | API | | | sys\_images | 视频通话抽帧图片列表。开启视频通话功能后，系统会自动进行视频画面抽帧，并将抽帧图片以 URL 形式存储到sys\_images变量中。你可以通过sys\_images变量使用这些图片。* 打开**视频通话**功能后，sys\_images变量自动为启用状态。* 关闭**视频通话**功能后，sys\_images变量自动为关闭状态。 | array | API | | ### 用户变量 用户变量以 Key-Value 形式存储每个用户在使用智能体过程中，需要持久化存储和读取的数据，例如用户的个性化设置、语言偏好、历史交互记录等。开发者可以在扣子开发平台中配置用户变量，并在用户与智能体交互时存储和检索这些变量，用户变量的值在用户会话之间持久化存储，支持可读可写。 ## 使用限制 * 用户变量仅支持 String 类型。 * 在智能体中，最多可创建 10 个用户变量。 * 系统变量不支持修改、删除，不支持开启提示词访问。 ## 创建及使用用户变量 你可以根据业务场景的需求，为智能体创建用户变量。创建后，你可以在提示词中为智能体声明用户变量的具体使用场景，或在工作流、插件的配置参数中引用用户变量。 * 如果用户更新了数据（例如，用户在会话内提供了新的用户名），则智能体会自动修改变量为最新值。 * 如果变量被删除，则变量内保存的用户数据也会被删除。 1. 创建用户变量。 在智能体的编排页面，单击**变量**对应的 **+**，然后在**编辑变量**对话框中，新增用户变量。重要参数说明如下表所示： | **配置** | **说明** | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 名称 | 用户变量的名称。必须确保每个变量名在智能体内唯一，不能与智能体内的其他变量重名。 | | 描述 | 描述变量的额外信息，包括变量的用途以及任何其他重要的使用说明。建议填写准确的变量名称与描述，以提高智能体命中用户数据的准确性。 | | 默认值 | 为变量指定一个初始值。 | | 开启提示词访问 | 打开**启用变量**开关且勾选**操作**列后，表示启用变量并开启提示词访问功能，即你可以在智能体的人设与提示词中使用用户变量。仅打开**启用变量**开关，未勾选**操作**列时，表示仅支持在工作流、插件中使用该变量。 | | 启用变量 | 打开**启用变量**开关后，你才能在工作流、插件中使用该变量。 | 2. 使用用户变量。 当你创建并启用变量后，与智能体对话时，系统会自动识别与变量匹配的内容，并将其存储至变量中。 例如在提示词中添加 称呼你的用户为{{name}}。当你在与智能体对话时，告诉智能体你的名字，系统会将你的名字记录到变量 {{name}} 中，后续智能体将根据你的名字称呼你。  ## 开启并使用系统变量 系统变量默认为关闭状态，你需要先启用目标系统变量，然后可以在工作流、插件的配置参数中引用系统变量。 1. 启用系统变量。 在智能体的编排页面，单击**变量**对应的 **+**，然后在**编辑变量**对话框中，找到待启用的目标系统变量，打开**启用变量**开关。 sys\_voiceprint\_name、sys\_voiceprint\_info 和 sys\_images 变量不支持手动开启。当相关功能被启用时，这些变量将自动启动并生效，无需用户手动操作。 2. 使用系统变量。 启用系统变量后，你可以在插件或工作流中使用系统变量。例如在工作流中添加[飞书消息](https://www.coze.cn/store/plugin/7395041302766944275?from=add_plugin_menu)插件中的 get\_chat\_messages 工具，并设置其中的 container\_id 参数引用系统变量 sys\_lark\_chat\_id。当智能体被发布到飞书并添加到不同的飞书群后，它能够自动识别并获取当前群的 ID。  ## 用户变量示例 以**翻译大师**智能体为例，定义一个用户变量 name，当用户首次使用 AI 翻译智能体时，工作流会引导用户输入他们希望被称呼的昵称，这个昵称会被赋值给用户变量 name。随后，每次用户请求翻译服务时，智能体会先亲切地使用这个昵称来称呼用户，然后再提供翻译结果。这样的个性化互动不仅增强了用户体验，也使得翻译服务更加友好和贴心。 工作流的流程如下：  1. 登录[扣子开发平台](https://www.coze.com/home)。 2. 在左侧导航栏中选择**工作空间**，并在页面顶部空间列表中选择目标工作空间。 3. 在**项目开发**页面，选择智能体或创建一个智能体。 4. 创建变量。 1. 单击**变量**对应的 **+**。 2. 在**用户变量**区域，设置变量的名称、描述和默认值，然后单击**保存**。 本示例变量名称设置为name。  5. 创建工作流。 1. 单击**工作流**对应的添加图标 **+**，然后单击**创建工作流->创建工作流**。 2. 输入工作流的名称和描述，然后单击**确认**。 3. 在工作流画布中编排工作流，然后试运行并发布工作流。工作流中的各个节点配置如下： | **节点类型** | **说明** | **示例** | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | 开始节点 | 工作流的起始节点，本示例无需配置任何输入参数。 |  | | 问答节点（询问称呼） | 用于询问用户希望被称呼的昵称，需要设置：* 提问内容：设置为**你希望我称呼你为什么？*** 回答类型：选择**直接回答**。 |  | | 变量赋值节点 | 用于为变量name赋值，引用问答节点（询问称呼）的输出参数。如果工作流中无变量，请先前往试运行，关联有变量配置的智能体后再选择变量。 |  | | 问答节点（询问翻译内容） | 用于询问用户希望翻译的内容，需要设置：* 提问内容：设置为**你想翻译什么？*** 回答类型：选择**直接回答**。 |  | | 大模型节点 | 用于翻译用户的输入内容，需要设置：* 输入：引用问答节点（询问翻译内容）的输出参数。* 系统提示词：设置翻译大师的人设，可以通过 AI 自动生成。* 用户提示词：设置为**翻译{{input}}为英文**。* 输出：变量名设置为**output**。 |  | | 结束节点 | 选择返回文本模式，并设置输出变量和回答内容。* 输出变量：* 定义 output 参数，引用大模型节点的输出参数 output。* 定义 name 参数，引用用户变量 name。* 回答内容：设置为**亲爱的{{name}}，你查询的译文为{{output}}**。 |  | 4. 将工作流添加到智能体。 5. 配置人设与回复逻辑。  7. 测试智能体效果。  ## 系统变量示例 以搭建**飞书聊天总结**智能体为例，你可以在工作流中添加[飞书消息](https://www.coze.cn/store/plugin/7395041302766944275?from=add_plugin_menu)插件中的 get\_chat\_messages 工具， 以获取飞书群内的聊天消息。同时，添加大模型节点，借助其强大的语言处理能力对聊天记录进行智能总结。在设置过程中，设置 get\_chat\_messages 工具中的 container\_id 参数引用系统变量 sys\_lark\_chat\_id，从而动态获取目标群的 ID。当智能体被添加到不同的飞书群时，它能够自动识别并获取当前群的 ID，并对该群内的聊天消息进行高效总结。 工作流如下所示：  1. 登录[扣子开发平台](https://www.coze.cn/home)。 2. 在左侧导航栏中选择**工作空间**，并在页面顶部空间列表中选择目标工作空间。 3. 在**项目开发**页面，选择智能体或创建一个智能体。 4. 发布智能体到飞书。 1. 单击右上角的**发布**。 2. 勾选**飞书**，然后单击**发布**。 首次发布时需要进行授权，根据引导完成授权。 5. 记录飞书应用的 ID 和 Secret。 发布到飞书后，系统将默认在[飞书开发者后台](https://open.larkoffice.com/app?lang=zh-CN)创建一个与智能体同名的飞书应用。记录该应用的 ID 和 Secret，在搭建工作流时，需输入该信息。  6. 开启系统变量 sys\_lark\_chat\_id。 返回到智能体，单击**变量**对应的 **+**，然后启用系统变量 sys\_lark\_chat\_id。  7. 创建工作流。 1. 单击**工作流**对应的 **+**，然后选择**创建工作流->创建工作流**。 2. 输入工作流的名称和描述，然后单击**确认**。 3. 在工作流画布中编排工作流。 工作流中的各个节点配置如下： | **节点类型** | **说明** | **示例** | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | | 开始节点 | 工作流的起始节点，本示例无需配置任何输入参数。 |  | | 插件节点 | 添加**飞书消息**插件中的** get\_chat\_messages **工具**，**用于获取指定单聊或群聊的消息记录，需要设置：* container\_id：引用系统变量sys\_lark\_chat\_id。当智能体被添加到飞书群后，将获取到该群的 ID，并总结该群的消息。* appid：输入智能体所在飞书开放平台应用的 ID，即你在上述步骤 5 中获取的应用的 ID。* appsecret：输入智能体所在飞书开放平台应用的 Secret，即你在上述步骤 5 中获取的应用的 Secret。 |  | | 大模型节点 | 用于总结飞书聊天记录，需要设置：* 输入：引用**get\_chat\_messages **节点的data参数。* 系统提示词：设置聊天总结的人设，可以通过 AI 自动生成。* 用户提示词：设置为总结{{input}}。* 输出：变量名设置为output。 |  | | 结束节点 | 选择返回文本模式，并设置输出变量和回答内容。* 输出变量：定义output参数，引用大模型节点的输出参数output。* 回答内容：设置为{{output}}。 |  | 4. 发布工作流。 5. 将工作流添加到智能体。 6. 配置人设与回复逻辑。  9. 重新发布智能体到飞书。 10. 测试智能体效果。 在飞书群里，通过添加机器人方式，将智能体添加到飞书群中，并测试智能体效果。  ## 相关操作 ### 查看变量值 你可以在智能体编排页面的右上角，选择**记忆** > **变量**，查看变量值。