变量管理

概述

变量可以存储用户特征，如语言偏好、行为习惯等。通过变量管理，能够使智能体动态记忆用户信息并生成个性化回复。

• 核心机制：变量以 key-value（键值对）形式存储数据。
• 赋值逻辑：大语言模型自动分析用户输入的语义，匹配对应变量并动态赋值。
• 应用场景：在提示词中声明变量用途（例如：根据用户的语言偏好切换回答语种）。

变量类型

您可通过 系统变量 和 用户变量 满足不同业务需求。二者区别如下：

App 用户变量

存储 App 用户与智能设备关联的静态信息，用于优化智能体在家庭场景中的服务。

• 典型场景

  • 天气播报：通过 家庭经纬度 变量获取本地实时天气。
  • 设备控制：通过 房间信息、家庭设备分类、设备 AI 指令属性 变量定位设备并调节其属性（如调节卧室中的灯具的亮度）。

• 支持变量表

  变量名称	描述	默认值	支持渠道	其他说明
  sys.categories	家庭设备分类	系统自动生成	Tuya、Smart Life、OEM App	只读
  sys.homeLatitude	家庭纬度坐标	系统自动生成	Tuya、Smart Life、OEM App	只读
  sys.rooms	家庭房间划分信息	系统自动生成	Tuya、Smart Life、OEM App	只读
  sys.currentTime	家庭所在时区的当前时间	系统自动生成	Tuya、Smart Life、OEM App	只读
  sys.homeLongitude	家庭经度坐标	系统自动生成	Tuya、Smart Life、OEM App	只读
  sys.deviceNames	设备名称列表	系统自动生成	Tuya、Smart Life、OEM App	只读
  sys.attributes	家庭设备的 AI 指令属性	系统自动生成	Tuya、Smart Life、OEM App	只读

• 使用规则

  • 启用方式：默认关闭，需要您在开发者平台手动启用。
  • 数据权限：
    • 仅通过 智能生活 App、涂鸦 App 及 OEM 渠道获取。
    • 数据由系统自动生成，禁止人工修改（如用户搬家并更新经纬度时，需重新触发定位请求）。

角色变量

专用于 业务面板场景（如 AI 娃娃、智能音箱），允许用户自定义角色属性，增强交互拟真度。

• 典型场景

  • 儿童陪伴机器人：通过 role_name 变量让用户设定角色称呼（如 “小助手乐乐”）。

• 默认变量表

  变量名称	描述	支持渠道	其他说明
  sys.roleName	角色名称	AI 玩具面板	只读
  sys.roleIntroduce	角色描述	AI 玩具面板	只读
  sys.roleSupplementDesc	角色补充描述	AI 玩具面板	只读

• 使用规则

  • 变量需要在开发者平台开启后才能使用。
  • C 端使用：C 端用户可修改角色变量值。修改实时生效，无需重新部署智能体。

  更多详细介绍，请参考 使用变量。

记忆变量

用于存储用户在智能体交互过程中需要 长期保留 的个性化数据，支持跨会话持久化读写。

• 典型场景

  • 根据兴趣匹配内容：通过 sys.memoryInterests 变量记录用户选择的兴趣爱好，对话时可以根据爱好来推荐相关的咨询内容，进行适配回答。
  • 根据记忆归纳的内容，了解用户之前的习惯：通过 sys.memoryHistoryChatSummary 变量保存历史对话总结，延续上下文信息，给予更贴切的回复。

• 默认变量表

  变量名称	描述	支持渠道	其他说明
  sys.memoryUserFullName	姓名。记录并总结用户的姓名，便于个性化交流	全渠道	根据每次会话总结
  sys.memoryInterests	兴趣爱好。记录用户的兴趣爱好，以便提供相关内容推荐	全渠道	同上
  sys.memoryAge	年龄。记录用户的年龄信息，用于优化交流体验	全渠道	同上
  sys.memoryBirthday	生日信息。记录用户的生日信息，便于提供提醒或祝福	全渠道	同上
  sys.memoryProfession	职业。记录用户的职业信息，以便更好地理解需求	全渠道	同上
  sys.memoryGoalsAndWishes	目标和愿望。记录用户的目标和愿望，便于个性化支持	全渠道	同上
  sys.memoryPetsKeptAtHome	用户家里养的宠物，以便个性化互动	全渠道	同上
  sys.memoryHistoryChatSummary	归纳用户的历史对话，便于延续上下文	全渠道	同上

• 典型场景

  • 根据兴趣匹配内容：通过 sys.memoryInterests 变量记录用户选择的兴趣爱好，对话时可以根据爱好来推荐相关的咨询内容，适配回答。
  • 根据记忆归纳的内容，了解用户之前的习惯：通过 sys.memoryHistoryChatSummary 变量保存历史对话总结，延续上下文信息，给予更贴切的回复。

• 使用规则

  • 启用方式：默认关闭，需在开发者平台手动启用。
  • 数据权限：
    • 智能体所有投放渠道均可以获取该数据。
    • 数据由系统自动生成，禁止人工修改（如用户搬家需更新经纬度时，需重新触发定位请求）。

自定义变量

允许您 完全自主定义 变量类型，用于捕捉用户与智能体在动态交互场景中的临时状态或扩展业务需求（如用户角色、实时情绪等）。

• 典型场景
  • 情绪感知：通过 current_mood 变量（取值范围 0-10）动态调整回复语气。
  • 身份适配：通过 user_role 变量（如“家长”、“访客”）切换智能体应答策略。
• 定义建议

自定义变量示例

使用变量

1. 登录 涂鸦开发者平台。

2. 进入 智能体开发平台，单击 创建Agent 或 Agent管理 进入智能体开发页面。

   

3. 在智能体开发页面，定位到 变量 区域并单击右侧的添加 （+） 按钮。

   

4. 管理变量：您可以在 编辑变量 页面创建自定义变量、开启系统变量、或开启角色变量管理。

   • 创建自定义变量：单击 新增，填写变量的名称、描述和默认值，然后单击 保存。建议填写准确的变量名称与描述，以提高智能体命中用户数据的准确性。

     

   • 开启系统变量：打开开启开关，开启 App 用户变量、记忆变量。开启后则自动引用该变量相关信息至系统 Prompt。

     

     若您需要对变量添加特殊描述，可以在 Prompt 中补充变量的使用场景。

   • 开启角色变量管理：角色变量适用于 AI 玩具、印象等需要有角色预设的场景，需要与对应品类面板配合使用，从而实现 C 端用户自定义智能体角色、音色、性格等功能。

     1. 打开开启开关，启用角色变量组。

        

     2. 在 角色预设管理 页面，单击 添加预设 来添加官方角色或自定义角色。

        

     3. 变量启用后，在完成智能体的开发以及智能体与产品设备端的关联后，配合 AI 玩具面板，即可在面板端查看到预设角色信息。