鸿蒙智能体开发实战：19.使用变量

前言

在智能体开发中，很多时候需要动态存储和处理数据 ------比如记住用户的语言偏好、统计用户的对话次数、根据设备信息调整回复内容。变量（Variable） 就是实现这些能力的核心机制。本文详细介绍鸿蒙智能体平台的三种变量类型（用户变量、系统变量、计数变量），以及如何在角色指令、工作流和插件中使用它们。

变量概述

什么是变量

变量是用来存储智能体运行过程中动态变化数据的容器。它们让智能体能够记住用户的特征、跟踪对话状态、控制功能使用频率，使回复更加个性化和精准。

核心价值：变量让智能体从"无状态"进化为"有状态"，能够根据上下文做出差异化响应。

变量类型对比

鸿蒙智能体平台提供三种变量类型：

变量类型	存储内容	读写权限	作用范围
用户变量	用户个性化设置和偏好	可读可写	每个用户独立
系统变量	设备信息和对话环境数据	只读	自动生成
计数变量	功能使用次数统计	原子化读写	按用户或设备维度

图1：智能体编排页面中的变量配置总览

用户变量

用户变量概述

用户变量 用于储存每个用户使用智能体过程中需要持久化存储和读取的动态变化数据，如用户的语言偏好、个性化设置等。用户变量可以让智能体记住用户的特征，使回复更加个性化。

python 复制代码

# 用户变量配置示例
user_variables = {
    "language_preference": {
        "type": "string",
        "default": "zh-CN",
        "description": "用户语言偏好",
        "available_in": ["role_instructions", "workflow"]  # 可用范围
    },
    "user_name": {
        "type": "string",
        "default": "",
        "description": "用户名称",
        "available_in": ["role_instructions"]
    },
    "favorite_topics": {
        "type": "array",
        "default": [],
        "description": "用户感兴趣的话题",
        "available_in": ["workflow"]
    }
}

图2：用户变量配置界面，可勾选在角色指令和工作流中使用

用户变量的更新机制

不同模式下用户变量的更新方式有差异：

模式	变量更新方式
工作流模式	不支持基于用户上下文进行抽取，只能在工作流的变量组件中更新
单Agent（LLM模式）未绑定工作流	配置中任意开关打开时，支持基于用户上下文进行抽取并更新
单Agent（LLM模式）绑定工作流	工作流中有变量组件时不支持抽取，无变量组件时支持抽取

在角色指令中使用用户变量

markdown 复制代码

# 角色指令中引用用户变量的示例

你是一个贴心的语言助手。
用户的偏好语言是：{{language_preference}}
用户的名字是：{{user_name}}

请使用用户偏好的语言进行回复。
如果用户设置了名字，请在回复中称呼用户的名字。

系统变量

系统变量概述

系统变量 是用户在使用智能体时自动产生的数据。系统变量仅支持读取，开发者不可对系统变量进行新增、修改、删除操作。

json 复制代码

{
  "system_variables": [
    {
      "name": "device_id",
      "type": "string",
      "description": "设备标识符",
      "available_in": ["workflow", "plugin"]
    },
    {
      "name": "device_language",
      "type": "string",
      "description": "设备语言",
      "available_in": ["workflow", "plugin"]
    },
    {
      "name": "uid",
      "type": "string",
      "description": "用户唯一标识",
      "available_in": ["workflow", "plugin"]
    }
  ]
}

注意：系统变量开关默认为关闭状态，开发者可以根据实际业务需求开启使用必要的系统变量。

系统变量的使用场景

python 复制代码

# 系统变量使用示例
def personalize_response(system_vars: dict) -> str:
    """根据系统变量个性化回复"""
    language = system_vars.get("device_language", "zh-CN")
    device_id = system_vars.get("device_id", "unknown")

    greetings = {
        "zh-CN": "你好！",
        "en-US": "Hello!",
        "ja-JP": "こんにちは！"
    }

    greeting = greetings.get(language, "你好！")

    return f"{greeting} 你的设备标识为 {device_id[:8]}..."

计数变量

计数变量概述

计数变量具有原子化特性，可用于从用户、设备维度增加对智能体功能的调用管控。

python 复制代码

# 计数变量配置示例
counter_variables = {
    "daily_usage_limit": {
        "name": "daily_usage",
        "dimension": "user",        # 计数维度：user / device
        "period": "daily",          # 周期：monthly / weekly / daily / hourly
        "initial_value": 0,         # 初始值
        "max_value": 100            # 最大值
    },
    "api_call_quota": {
        "name": "api_call_quota",
        "dimension": "user",
        "period": "monthly",
        "initial_value": 1000,
        "max_value": 1000
    }
}

计数变量规则

规则	说明
支持模式	云A2A模式暂不支持计数变量
数量限制	每个智能体最多增加10个
命名规则	只能包含小写字母、数字或下划线，必须以英文字母开头，最大长度20
计数维度	按用户（uid）或设备（odid）维度统计
计数周期	自然月、自然周、自然天、自然小时
保存后修改	创建成功后名称、维度、周期不可修改，需删除重建

python 复制代码

# 计数变量的使用逻辑
class CounterVariable:
    def __init__(self, name: str, dimension: str, period: str, initial: int):
        self.name = name
        self.dimension = dimension  # 'user' or 'device'
        self.period = period        # 'daily', 'weekly', 'monthly', 'hourly'
        self.value = initial

    def increment(self) -> int:
        """原子化递增"""
        self.value += 1
        return self.value

    def decrement(self) -> int:
        """原子化递减（配额管理场景）"""
        if self.value > 0:
            self.value -= 1
        return self.value

    def is_exceeded(self, limit: int) -> bool:
        """检查是否超过限制"""
        return self.value >= limit

    def reset_if_needed(self, current_time, last_reset_time):
        """根据周期自动重置"""
        if self.period == "daily" and self._is_new_day(current_time, last_reset_time):
            self.value = 0
        elif self.period == "monthly" and self._is_new_month(current_time, last_reset_time):
            self.value = 0

图3：计数变量配置界面，支持按用户或设备维度统计

变量的使用方式

1. 在角色指令中使用变量

变量可以在智能体的角色指令中直接引用，实现个性化对话：

markdown 复制代码

# 角色指令中的变量使用

你是{{user_name}}的专属学习助手。

用户偏好信息：
- 学习风格：{{learning_style}}
- 擅长科目：{{strong_subjects}}
- 薄弱科目：{{weak_subjects}}

请根据用户的学习风格调整教学方式：
- 如果用户是"视觉型"学习者，多用图表和示意图
- 如果用户是"听觉型"学习者，多用朗读和讲解
- 如果用户是"动手型"学习者，多提供练习和实验

当前对话次数：{{daily_usage}}
今日剩余免费次数：{{subtract 3 daily_usage}}

提示：在角色指令中，变量通过 {``{变量名}} 的格式引用。系统会自动将变量替换为当前用户的对应值。

2. 在工作流中使用变量

变量在工作流中的使用分为两种情况：

作为右值（获取变量值）：

json 复制代码

{
  "workflow_node": {
    "type": "llm_node",
    "system_prompt": "你是{{user_name}}的专属助手",
    "input_parameters": {
      "user_name": "${user_variables.user_name}",
      "language": "${system_variables.device_language}"
    }
  }
}

作为左值（更新变量值）：

json 复制代码

{
  "workflow_node": {
    "type": "variable_node",
    "operation": "update",
    "variable_name": "user_name",
    "value": "${previous_node.output.user_name}"
  }
}

3. 在插件中使用变量

变量也可以在插件的参数配置中使用：

json 复制代码

{
  "plugin_config": {
    "plugin_id": "weather_query",
    "parameters": {
      "city": "${user_variables.default_city}",
      "language": "${system_variables.device_language}"
    }
  }
}

查看当前取值或重置数据

查看变量值

在智能体编排页，点击右上角的【记忆】→【变量】，可以查看当前变量的值：

图4：记忆-变量页面，可查看和重置变量数据

查看变量值的操作步骤如下：

在智能体编排页面点击右上角【记忆】图标
在弹出的菜单中选择【变量】选项卡
查看用户变量、系统变量和计数变量的当前值
如需重置，点击对应变量后的【重置】按钮

python 复制代码

# 查看变量值的 API
def get_variable_values(agent_id: str, user_id: str) -> dict:
    """获取当前用户的所有变量值"""
    variables = {
        "user_variables": {
            "user_name": "张三",
            "language_preference": "zh-CN",
            "favorite_topics": ["科技", "历史"]
        },
        "system_variables": {
            "device_id": "odid_xxxxx",
            "device_language": "zh-CN"
        },
        "counter_variables": {
            "daily_usage": 5
        }
    }
    return variables

重置数据

在变量查看页面内，也可以对变量进行数据重置 和数据更新操作：

python 复制代码

# 变量重置操作
def reset_variable(agent_id: str, variable_name: str, user_id: str) -> bool:
    """重置指定变量为初始值"""
    # 在平台界面操作：记忆 → 变量 → 选择变量 → 重置
    print(f"变量 {variable_name} 已重置为初始值")
    return True

注意：计数变量暂不支持查看和重置。

变量使用的最佳实践

1. 用户变量设计原则

python 复制代码

# 用户变量设计规范
variable_design_principles = {
    "明确命名": "使用清晰、有语义的变量名，如 language_preference 而非 lp",
    "设置默认值": "为变量设置合理的默认值，避免引用空值",
    "最小化设计": "只创建必要的变量，避免过多变量影响性能",
    "范围控制": "合理设置变量的可用范围（角色指令/工作流/插件）"
}

2. 计数变量在配额管理中的应用

python 复制代码

# 使用计数变量实现 API 配额管理
class QuotaManager:
    def __init__(self, counter_var: CounterVariable, limit: int):
        self.counter = counter_var
        self.limit = limit

    def check_quota(self) -> tuple[bool, int]:
        """检查配额，返回 (是否允许, 当前使用量)"""
        current = self.counter.value
        if current >= self.limit:
            return False, current
        return True, current

    def consume_quota(self) -> tuple[bool, str]:
        """消耗一次配额"""
        allowed, current = self.check_quota()
        if not allowed:
            return False, f"配额已用完（{current}/{self.limit}）"

        new_value = self.counter.increment()
        return True, f"剩余配额：{self.limit - new_value}"

3. 系统变量的灵活运用

python 复制代码

# 根据系统变量实现多语言支持
def multilingual_response(system_vars: dict, user_vars: dict) -> str:
    """根据系统和用户变量确定回复语言"""
    # 优先级：用户设置 > 设备语言 > 默认
    language = (
        user_vars.get("language_preference")
        or system_vars.get("device_language")
        or "zh-CN"
    )

    responses = {
        "zh-CN": "您好！有什么可以帮助您的？",
        "en-US": "Hello! How can I help you?",
        "ja-JP": "こんにちは！何かお手伝いしましょうか？"
    }

    return responses.get(language, responses["zh-CN"])

4. 变量与触发器的协同

python 复制代码

# 变量与触发器配合使用
trigger_with_variables = {
    "trigger": "webhook_event",
    "task": {
        "type": "workflow",
        "parameters": {
            "userId": "${system_variables.uid}",
            "userName": "${user_variables.user_name}",
            "deviceLang": "${system_variables.device_language}"
        }
    }
}

常见问题（FAQ）

Q1：用户变量在对话中不生效怎么办？

答：请检查：1）变量是否已在变量页面创建并打开对应开关；2）角色指令中引用的变量名是否与实际名称一致；3）如果是工作流模式，需要在工作流的变量组件中更新变量。

Q2：计数变量可以跨智能体共享吗？

答：不可以。每个智能体的计数变量是独立的，每个智能体最多增加10个计数变量。

Q3：变量的值可以在对话中被用户修改吗？

答：用户变量可以通过智能体的对话逻辑进行更新（取决于模式的更新机制），但系统变量是只读的，用户无法修改。

Q4：为什么变量功能开关打开了但工作流中获取不到？

答：请确认：1）变量已正确添加到工作流节点的参数引用中；2）工作流模式的智能体中，用户变量只能在工作流的变量组件中更新，不支持自动抽取。

Q5：计数变量的值在周期结束后会自动重置吗？

答：是的，计数变量按配置的周期（自然月/周/天/小时）自动清零重置。

总结

本文全面介绍了鸿蒙智能体平台的变量系统：

用户变量：持久化存储用户个性化设置，支持在角色指令和工作流中读写
系统变量：自动生成的设备环境数据，只读，可在工作流和插件中使用
计数变量：原子化的调用频率管控，按用户或设备维度统计
使用方式：角色指令、工作流、插件三种场景的变量引用语法
查看重置：在记忆-变量页面查看或重置变量值
最佳实践：命名规范、配额管理、多语言支持、触发器协同

掌握变量的使用是构建智能、个性化智能体的基础，它让智能体能够真正"记住"用户，提供差异化的服务体验。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：