前言在智能体开发中很多时候需要动态存储和处理数据——比如记住用户的语言偏好、统计用户的对话次数、根据设备信息调整回复内容。变量Variable就是实现这些能力的核心机制。本文详细介绍鸿蒙智能体平台的三种变量类型用户变量、系统变量、计数变量以及如何在角色指令、工作流和插件中使用它们。变量概述什么是变量变量是用来存储智能体运行过程中动态变化数据的容器。它们让智能体能够记住用户的特征、跟踪对话状态、控制功能使用频率使回复更加个性化和精准。核心价值变量让智能体从无状态进化为有状态能够根据上下文做出差异化响应。变量类型对比鸿蒙智能体平台提供三种变量类型变量类型存储内容读写权限作用范围用户变量用户个性化设置和偏好可读可写每个用户独立系统变量设备信息和对话环境数据只读自动生成计数变量功能使用次数统计原子化读写按用户或设备维度图1智能体编排页面中的变量配置总览用户变量用户变量概述用户变量用于储存每个用户使用智能体过程中需要持久化存储和读取的动态变化数据如用户的语言偏好、个性化设置等。用户变量可以让智能体记住用户的特征使回复更加个性化。# 用户变量配置示例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用户变量配置界面可勾选在角色指令和工作流中使用用户变量的更新机制不同模式下用户变量的更新方式有差异模式变量更新方式工作流模式不支持基于用户上下文进行抽取只能在工作流的变量组件中更新单AgentLLM模式未绑定工作流配置中任意开关打开时支持基于用户上下文进行抽取并更新单AgentLLM模式绑定工作流工作流中有变量组件时不支持抽取无变量组件时支持抽取在角色指令中使用用户变量# 角色指令中引用用户变量的示例 你是一个贴心的语言助手。 用户的偏好语言是{{language_preference}} 用户的名字是{{user_name}} 请使用用户偏好的语言进行回复。 如果用户设置了名字请在回复中称呼用户的名字。系统变量系统变量概述系统变量是用户在使用智能体时自动产生的数据。系统变量仅支持读取开发者不可对系统变量进行新增、修改、删除操作。{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]}]}注意系统变量开关默认为关闭状态开发者可以根据实际业务需求开启使用必要的系统变量。系统变量的使用场景# 系统变量使用示例defpersonalize_response(system_vars:dict)-str:根据系统变量个性化回复languagesystem_vars.get(device_language,zh-CN)device_idsystem_vars.get(device_id,unknown)greetings{zh-CN:你好,en-US:Hello!,ja-JP:こんにちは}greetinggreetings.get(language,你好)returnf{greeting}你的设备标识为{device_id[:8]}...计数变量计数变量概述计数变量具有原子化特性可用于从用户、设备维度增加对智能体功能的调用管控。# 计数变量配置示例counter_variables{daily_usage_limit:{name:daily_usage,dimension:user,# 计数维度user / deviceperiod:daily,# 周期monthly / weekly / daily / hourlyinitial_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维度统计计数周期自然月、自然周、自然天、自然小时保存后修改创建成功后名称、维度、周期不可修改需删除重建# 计数变量的使用逻辑classCounterVariable:def__init__(self,name:str,dimension:str,period:str,initial:int):self.namename self.dimensiondimension# user or deviceself.periodperiod# daily, weekly, monthly, hourlyself.valueinitialdefincrement(self)-int:原子化递增self.value1returnself.valuedefdecrement(self)-int:原子化递减配额管理场景ifself.value0:self.value-1returnself.valuedefis_exceeded(self,limit:int)-bool:检查是否超过限制returnself.valuelimitdefreset_if_needed(self,current_time,last_reset_time):根据周期自动重置ifself.perioddailyandself._is_new_day(current_time,last_reset_time):self.value0elifself.periodmonthlyandself._is_new_month(current_time,last_reset_time):self.value0图3计数变量配置界面支持按用户或设备维度统计变量的使用方式1. 在角色指令中使用变量变量可以在智能体的角色指令中直接引用实现个性化对话# 角色指令中的变量使用 你是{{user_name}}的专属学习助手。 用户偏好信息 - 学习风格{{learning_style}} - 擅长科目{{strong_subjects}} - 薄弱科目{{weak_subjects}} 请根据用户的学习风格调整教学方式 - 如果用户是视觉型学习者多用图表和示意图 - 如果用户是听觉型学习者多用朗读和讲解 - 如果用户是动手型学习者多提供练习和实验 当前对话次数{{daily_usage}} 今日剩余免费次数{{subtract 3 daily_usage}}提示在角色指令中变量通过{{变量名}}的格式引用。系统会自动将变量替换为当前用户的对应值。2. 在工作流中使用变量变量在工作流中的使用分为两种情况作为右值获取变量值{workflow_node:{type:llm_node,system_prompt:你是{{user_name}}的专属助手,input_parameters:{user_name:${user_variables.user_name},language:${system_variables.device_language}}}}作为左值更新变量值{workflow_node:{type:variable_node,operation:update,variable_name:user_name,value:${previous_node.output.user_name}}}3. 在插件中使用变量变量也可以在插件的参数配置中使用{plugin_config:{plugin_id:weather_query,parameters:{city:${user_variables.default_city},language:${system_variables.device_language}}}}查看当前取值或重置数据查看变量值在智能体编排页点击右上角的【记忆】→【变量】可以查看当前变量的值图4记忆-变量页面可查看和重置变量数据查看变量值的操作步骤如下在智能体编排页面点击右上角【记忆】图标在弹出的菜单中选择【变量】选项卡查看用户变量、系统变量和计数变量的当前值如需重置点击对应变量后的【重置】按钮# 查看变量值的 APIdefget_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}}returnvariables重置数据在变量查看页面内也可以对变量进行数据重置和数据更新操作# 变量重置操作defreset_variable(agent_id:str,variable_name:str,user_id:str)-bool:重置指定变量为初始值# 在平台界面操作记忆 → 变量 → 选择变量 → 重置print(f变量{variable_name}已重置为初始值)returnTrue注意计数变量暂不支持查看和重置。变量使用的最佳实践1. 用户变量设计原则# 用户变量设计规范variable_design_principles{明确命名:使用清晰、有语义的变量名如 language_preference 而非 lp,设置默认值:为变量设置合理的默认值避免引用空值,最小化设计:只创建必要的变量避免过多变量影响性能,范围控制:合理设置变量的可用范围角色指令/工作流/插件}2. 计数变量在配额管理中的应用# 使用计数变量实现 API 配额管理classQuotaManager:def__init__(self,counter_var:CounterVariable,limit:int):self.countercounter_var self.limitlimitdefcheck_quota(self)-tuple[bool,int]:检查配额返回 (是否允许, 当前使用量)currentself.counter.valueifcurrentself.limit:returnFalse,currentreturnTrue,currentdefconsume_quota(self)-tuple[bool,str]:消耗一次配额allowed,currentself.check_quota()ifnotallowed:returnFalse,f配额已用完{current}/{self.limit}new_valueself.counter.increment()returnTrue,f剩余配额{self.limit-new_value}3. 系统变量的灵活运用# 根据系统变量实现多语言支持defmultilingual_response(system_vars:dict,user_vars:dict)-str:根据系统和用户变量确定回复语言# 优先级用户设置 设备语言 默认language(user_vars.get(language_preference)orsystem_vars.get(device_language)orzh-CN)responses{zh-CN:您好有什么可以帮助您的,en-US:Hello! How can I help you?,ja-JP:こんにちは何かお手伝いしましょうか}returnresponses.get(language,responses[zh-CN])4. 变量与触发器的协同# 变量与触发器配合使用trigger_with_variables{trigger:webhook_event,task:{type:workflow,parameters:{userId:${system_variables.uid},userName:${user_variables.user_name},deviceLang:${system_variables.device_language}}}}常见问题FAQQ1用户变量在对话中不生效怎么办答请检查1变量是否已在变量页面创建并打开对应开关2角色指令中引用的变量名是否与实际名称一致3如果是工作流模式需要在工作流的变量组件中更新变量。Q2计数变量可以跨智能体共享吗答不可以。每个智能体的计数变量是独立的每个智能体最多增加10个计数变量。Q3变量的值可以在对话中被用户修改吗答用户变量可以通过智能体的对话逻辑进行更新取决于模式的更新机制但系统变量是只读的用户无法修改。Q4为什么变量功能开关打开了但工作流中获取不到答请确认1变量已正确添加到工作流节点的参数引用中2工作流模式的智能体中用户变量只能在工作流的变量组件中更新不支持自动抽取。Q5计数变量的值在周期结束后会自动重置吗答是的计数变量按配置的周期自然月/周/天/小时自动清零重置。总结本文全面介绍了鸿蒙智能体平台的变量系统用户变量持久化存储用户个性化设置支持在角色指令和工作流中读写系统变量自动生成的设备环境数据只读可在工作流和插件中使用计数变量原子化的调用频率管控按用户或设备维度统计使用方式角色指令、工作流、插件三种场景的变量引用语法查看重置在记忆-变量页面查看或重置变量值最佳实践命名规范、配额管理、多语言支持、触发器协同掌握变量的使用是构建智能、个性化智能体的基础它让智能体能够真正记住用户提供差异化的服务体验。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源变量概述与配置用户变量使用指南系统变量说明计数变量说明变量节点查询计数变量节点配额管理节点小艺开放平台
鸿蒙智能体开发实战：19.使用变量
前言在智能体开发中很多时候需要动态存储和处理数据——比如记住用户的语言偏好、统计用户的对话次数、根据设备信息调整回复内容。变量Variable就是实现这些能力的核心机制。本文详细介绍鸿蒙智能体平台的三种变量类型用户变量、系统变量、计数变量以及如何在角色指令、工作流和插件中使用它们。变量概述什么是变量变量是用来存储智能体运行过程中动态变化数据的容器。它们让智能体能够记住用户的特征、跟踪对话状态、控制功能使用频率使回复更加个性化和精准。核心价值变量让智能体从无状态进化为有状态能够根据上下文做出差异化响应。变量类型对比鸿蒙智能体平台提供三种变量类型变量类型存储内容读写权限作用范围用户变量用户个性化设置和偏好可读可写每个用户独立系统变量设备信息和对话环境数据只读自动生成计数变量功能使用次数统计原子化读写按用户或设备维度图1智能体编排页面中的变量配置总览用户变量用户变量概述用户变量用于储存每个用户使用智能体过程中需要持久化存储和读取的动态变化数据如用户的语言偏好、个性化设置等。用户变量可以让智能体记住用户的特征使回复更加个性化。# 用户变量配置示例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用户变量配置界面可勾选在角色指令和工作流中使用用户变量的更新机制不同模式下用户变量的更新方式有差异模式变量更新方式工作流模式不支持基于用户上下文进行抽取只能在工作流的变量组件中更新单AgentLLM模式未绑定工作流配置中任意开关打开时支持基于用户上下文进行抽取并更新单AgentLLM模式绑定工作流工作流中有变量组件时不支持抽取无变量组件时支持抽取在角色指令中使用用户变量# 角色指令中引用用户变量的示例 你是一个贴心的语言助手。 用户的偏好语言是{{language_preference}} 用户的名字是{{user_name}} 请使用用户偏好的语言进行回复。 如果用户设置了名字请在回复中称呼用户的名字。系统变量系统变量概述系统变量是用户在使用智能体时自动产生的数据。系统变量仅支持读取开发者不可对系统变量进行新增、修改、删除操作。{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]}]}注意系统变量开关默认为关闭状态开发者可以根据实际业务需求开启使用必要的系统变量。系统变量的使用场景# 系统变量使用示例defpersonalize_response(system_vars:dict)-str:根据系统变量个性化回复languagesystem_vars.get(device_language,zh-CN)device_idsystem_vars.get(device_id,unknown)greetings{zh-CN:你好,en-US:Hello!,ja-JP:こんにちは}greetinggreetings.get(language,你好)returnf{greeting}你的设备标识为{device_id[:8]}...计数变量计数变量概述计数变量具有原子化特性可用于从用户、设备维度增加对智能体功能的调用管控。# 计数变量配置示例counter_variables{daily_usage_limit:{name:daily_usage,dimension:user,# 计数维度user / deviceperiod:daily,# 周期monthly / weekly / daily / hourlyinitial_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维度统计计数周期自然月、自然周、自然天、自然小时保存后修改创建成功后名称、维度、周期不可修改需删除重建# 计数变量的使用逻辑classCounterVariable:def__init__(self,name:str,dimension:str,period:str,initial:int):self.namename self.dimensiondimension# user or deviceself.periodperiod# daily, weekly, monthly, hourlyself.valueinitialdefincrement(self)-int:原子化递增self.value1returnself.valuedefdecrement(self)-int:原子化递减配额管理场景ifself.value0:self.value-1returnself.valuedefis_exceeded(self,limit:int)-bool:检查是否超过限制returnself.valuelimitdefreset_if_needed(self,current_time,last_reset_time):根据周期自动重置ifself.perioddailyandself._is_new_day(current_time,last_reset_time):self.value0elifself.periodmonthlyandself._is_new_month(current_time,last_reset_time):self.value0图3计数变量配置界面支持按用户或设备维度统计变量的使用方式1. 在角色指令中使用变量变量可以在智能体的角色指令中直接引用实现个性化对话# 角色指令中的变量使用 你是{{user_name}}的专属学习助手。 用户偏好信息 - 学习风格{{learning_style}} - 擅长科目{{strong_subjects}} - 薄弱科目{{weak_subjects}} 请根据用户的学习风格调整教学方式 - 如果用户是视觉型学习者多用图表和示意图 - 如果用户是听觉型学习者多用朗读和讲解 - 如果用户是动手型学习者多提供练习和实验 当前对话次数{{daily_usage}} 今日剩余免费次数{{subtract 3 daily_usage}}提示在角色指令中变量通过{{变量名}}的格式引用。系统会自动将变量替换为当前用户的对应值。2. 在工作流中使用变量变量在工作流中的使用分为两种情况作为右值获取变量值{workflow_node:{type:llm_node,system_prompt:你是{{user_name}}的专属助手,input_parameters:{user_name:${user_variables.user_name},language:${system_variables.device_language}}}}作为左值更新变量值{workflow_node:{type:variable_node,operation:update,variable_name:user_name,value:${previous_node.output.user_name}}}3. 在插件中使用变量变量也可以在插件的参数配置中使用{plugin_config:{plugin_id:weather_query,parameters:{city:${user_variables.default_city},language:${system_variables.device_language}}}}查看当前取值或重置数据查看变量值在智能体编排页点击右上角的【记忆】→【变量】可以查看当前变量的值图4记忆-变量页面可查看和重置变量数据查看变量值的操作步骤如下在智能体编排页面点击右上角【记忆】图标在弹出的菜单中选择【变量】选项卡查看用户变量、系统变量和计数变量的当前值如需重置点击对应变量后的【重置】按钮# 查看变量值的 APIdefget_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}}returnvariables重置数据在变量查看页面内也可以对变量进行数据重置和数据更新操作# 变量重置操作defreset_variable(agent_id:str,variable_name:str,user_id:str)-bool:重置指定变量为初始值# 在平台界面操作记忆 → 变量 → 选择变量 → 重置print(f变量{variable_name}已重置为初始值)returnTrue注意计数变量暂不支持查看和重置。变量使用的最佳实践1. 用户变量设计原则# 用户变量设计规范variable_design_principles{明确命名:使用清晰、有语义的变量名如 language_preference 而非 lp,设置默认值:为变量设置合理的默认值避免引用空值,最小化设计:只创建必要的变量避免过多变量影响性能,范围控制:合理设置变量的可用范围角色指令/工作流/插件}2. 计数变量在配额管理中的应用# 使用计数变量实现 API 配额管理classQuotaManager:def__init__(self,counter_var:CounterVariable,limit:int):self.countercounter_var self.limitlimitdefcheck_quota(self)-tuple[bool,int]:检查配额返回 (是否允许, 当前使用量)currentself.counter.valueifcurrentself.limit:returnFalse,currentreturnTrue,currentdefconsume_quota(self)-tuple[bool,str]:消耗一次配额allowed,currentself.check_quota()ifnotallowed:returnFalse,f配额已用完{current}/{self.limit}new_valueself.counter.increment()returnTrue,f剩余配额{self.limit-new_value}3. 系统变量的灵活运用# 根据系统变量实现多语言支持defmultilingual_response(system_vars:dict,user_vars:dict)-str:根据系统和用户变量确定回复语言# 优先级用户设置 设备语言 默认language(user_vars.get(language_preference)orsystem_vars.get(device_language)orzh-CN)responses{zh-CN:您好有什么可以帮助您的,en-US:Hello! How can I help you?,ja-JP:こんにちは何かお手伝いしましょうか}returnresponses.get(language,responses[zh-CN])4. 变量与触发器的协同# 变量与触发器配合使用trigger_with_variables{trigger:webhook_event,task:{type:workflow,parameters:{userId:${system_variables.uid},userName:${user_variables.user_name},deviceLang:${system_variables.device_language}}}}常见问题FAQQ1用户变量在对话中不生效怎么办答请检查1变量是否已在变量页面创建并打开对应开关2角色指令中引用的变量名是否与实际名称一致3如果是工作流模式需要在工作流的变量组件中更新变量。Q2计数变量可以跨智能体共享吗答不可以。每个智能体的计数变量是独立的每个智能体最多增加10个计数变量。Q3变量的值可以在对话中被用户修改吗答用户变量可以通过智能体的对话逻辑进行更新取决于模式的更新机制但系统变量是只读的用户无法修改。Q4为什么变量功能开关打开了但工作流中获取不到答请确认1变量已正确添加到工作流节点的参数引用中2工作流模式的智能体中用户变量只能在工作流的变量组件中更新不支持自动抽取。Q5计数变量的值在周期结束后会自动重置吗答是的计数变量按配置的周期自然月/周/天/小时自动清零重置。总结本文全面介绍了鸿蒙智能体平台的变量系统用户变量持久化存储用户个性化设置支持在角色指令和工作流中读写系统变量自动生成的设备环境数据只读可在工作流和插件中使用计数变量原子化的调用频率管控按用户或设备维度统计使用方式角色指令、工作流、插件三种场景的变量引用语法查看重置在记忆-变量页面查看或重置变量值最佳实践命名规范、配额管理、多语言支持、触发器协同掌握变量的使用是构建智能、个性化智能体的基础它让智能体能够真正记住用户提供差异化的服务体验。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源变量概述与配置用户变量使用指南系统变量说明计数变量说明变量节点查询计数变量节点配额管理节点小艺开放平台
