动态变量使用最佳实践

1. 概述

动态变量管理功能，是指客户可以通过在创建智能体时设置变量、或者在会话过程中更新变量，并可以在系统多个功能模块中使用这些变量，来实现高度自定义的业务能力。目前支持动态变量的模块有：角色、Function Call、MCP等。

2. 动态变量分类和定义

注意：sys_ 为系统变量专用前缀，自定义变量请勿使用该前缀。系统变量支持的类型，会逐步更新，暂时只支持sys_user_id。

3. 动态变量管理方式

3.1 创建时初始化

在创建智能体时，在config参数中传入初始化值：

1{
2  "variables": {
3    "room_name": "客厅",
4    "device_name": "空调"
5  }
6}

3.2、会话中更新

在会话中，通过信令事件更新用户自定义变量，但不能通过该信令事件更改系统变量值。
更新用户自定义变量信令格式样例：

1[SET]:[VARIABLES]:{"room_name":"客厅","device_name":"空调"}

4. 动态变量使用

4.1 角色中使用

在控制台配置自定义角色时，可以在角色定义中可嵌入动态变量，同时在会话中设置对应动态变量，系统会自动将这些变量名替换成对应变量值。

4.1.1 示例：健身教练助手根据用户身体数据定制建议

Step 1：控制台配置角色

1你是一位专业的健身教练助手，根据用户的身体数据提供个性化的训练和饮食建议。
2
3用户昵称：{{nickname}}
4用户性别：{{gender}}
5用户年龄：{{age}}
6身高(cm)：{{height}}
7体重(kg)：{{weight}}
8健身目标：{{fitness_goal}}
9运动频率：{{exercise_frequency}}
10
11要求：
121. 根据用户的 BMI 和健身目标，推荐合适的训练计划
132. 如果用户目标是减脂，侧重有氧运动和饮食控制建议
143. 如果用户目标是增肌，侧重力量训练和蛋白质摄入建议
154. 回复时称呼用户昵称，语气积极鼓励

Step 2：创建实例时传入变量值

1{
2  "variables": {
3    "nickname": "小明",
4    "gender": "男",
5    "age": "28",
6    "height": "175",
7    "weight": "80",
8    "fitness_goal": "减脂",
9    "exercise_frequency": "每周3次"
10  }
11}

Step 3：替换动态变量后的角色定义

1你是一位专业的健身教练助手，根据用户的身体数据提供个性化的训练和饮食建议。
2
3用户昵称：小明
4用户性别：男
5用户年龄：28
6身高(cm)：175
7体重(kg)：80
8健身目标：减脂
9运动频率：每周3次
10
11要求：
121. 根据用户的 BMI 和健身目标，推荐合适的训练计划
132. 如果用户目标是减脂，侧重有氧运动和饮食控制建议
143. 如果用户目标是增肌，侧重力量训练和蛋白质摄入建议
154. 回复时称呼用户昵称，语气积极鼓励

配置建议：

• 如果配置了自定义变量，建议在创建智能体时传入初始值，否则会话中会直接去掉占位符
• 为关键变量设置默认值，变量值应简短明确，避免注入大段文本
• 不要注入密码、Token、密钥等敏感信息
  

4.2 Function Call 中使用

在控制台配置Function Call时，可以在函数描述和参数默认值中嵌入动态变量，同时在会话中设置对应动态变量，系统会自动将这些变量名替换成对应变量值。

4.2.1 示例: 智能家居设备控制-不同设备共用同一个函数定义

Step 1：控制台配置函数

在控制台配置 control_device 函数时，函数描述和参数中使用动态变量：

Step 2：创建实例时传入变量值

1{
2  "variables": {
3    "device_name": "空调"
4  }
5}

Step 3：替换动态变量后的Function Call例句

1打开空调
2关闭空调

用户问题说"好热，请打开空调"时，系统判断用户意图匹配动态变量替换后的例句，命中该 Function Call。
配置建议：

• 变量值在创建实例时由端侧传入，确保与实际设备环境一致
• 函数描述和参数默认值都可以使用动态变量
• 动态变量仅辅助模型理解调用上下文，不替代后端鉴权和设备安全校验

4.3 MCP 中使用

通过在 Description 中嵌入 __MCP_META__，可将系统变量映射至 MCP 工具参数：

1__MCP_META__: {"params":{"user_id": "sys_user_id", "query": "query"}}

变量映射说明

• params: 定义映射规则，Key 为 MCP Server 定义的工具参数名，Value 为来源变量。

• 系统变量 (以 sys_ 开头)：这些变量由平台侧自动注入，具备唯一性和全局性，直接从系统运行时获取。

  • sys_user_id: 当前登录用户的唯一标识。
  • sys_device_id: 当前交互设备的唯一标识。

• 内置查询变量：

  • query: 映射用户的原始提问内容，用于工具处理。

• 自定义变量：

  • 若需传递非系统变量，可通过指令 [SET]:[VARIABLES]:{"key":"value"} 在交互过程中手动设置。