为应用添加记忆

在多轮对话场景中，用户往往期望智能体能够记住自己的偏好、身份和交互习惯，从而获得连贯且个性化的服务体验。在单智能体配置中，支持通过配置变量为应用开启“记忆”功能。

AgentArts提供以下记忆类型，满足不同场景下的记忆需求：

用户变量：存储用户属性与偏好（如姓名、语言习惯、关注领域），支持自动识别提取、跨会话持久化和动态更新。
入参变量：通过API调用向智能体动态注入外部信息（如用户 ID、业务单据编号），支持String、Boolean、Integer、Number类型，支持在工作流、插件和MCP服务的入参配置处引用。

约束与限制

表1 记忆限制说明
类别	说明
变量	每个应用最多支持创建30个变量。变量名称：不允许为空，最长支持100个字符，不能带有^符号。描述和默认值最长支持500个字符。

变量类型说明

表2 变量类型说明
变量类型	说明	适用场景
用户变量	用户变量专门用于存储与用户属性、偏好相关的特定信息（如：用户姓名、语言习惯、关注领域等）。使用示例可参考示例：配置与使用用户变量。	自动识别与提取：在对话过程中，智能体具备语义感知能力，能够自动识别与预设变量匹配的内容，并将其提取存储至对应的变量中，无需用户显式重复提供。跨会话持久化：用户变量支持会话间的持久化存储。当同一用户在不同时间发起新的会话时，智能体仍可读取并沿用此前记录的变量值，确保服务的连续性。灵活读写与更新：变量支持实时读取与动态写入。随着对话的深入，智能体可以根据用户的最新反馈及时更新变量值，确保记忆的准确性与时效性。个性化应用：通过在提示词中引用用户变量，可以约束智能体的回复风格或业务逻辑。例如，根据存储的“语言偏好”变量，智能体将始终以用户习惯的语种进行交流。
入参变量	入参变量用于在API调用时向智能体动态传入外部信息，通常用于注入具有确定性的业务逻辑、上下文信息或特定参数（如：用户ID、业务单据编号等确定性数据）。支持的数据类型包括String、Boolean、Integer、Number。使用示例可参考示例：配置与使用入参变量。	确定性信息注入：入参变量适用于传入明确、确定的外部信息，而非由智能体自主推理获取的内容。例如，将当前用户的身份信息或业务状态作为入参传入，智能体据此执行对应的处理逻辑。 API动态赋值：入参变量的值通过调用智能体API时传入，每次调用可传入不同的值，实现参数的动态替换，无需修改智能体配置。组件间灵活引用：入参变量创建后，可在工作流、插件、MCP服务的入参配置处进行引用，将外部传入的信息无缝传递至各组件中使用。

示例：配置与使用用户变量

以构建一个“智能客服助手”为例，指导您如何配置用户变量并实现动态交互。

参考表3创建一个“智能客服助手”单智能体。

表3 单智能体示例
单智能体信息	示例值
名称	智能客服助手
描述	根据用户的提问进行问答。

添加用户变量。用户变量允许智能体在对话过程中识别并记录用户的特定属性。

表4 配置参数
配置信息	说明
名称	定义用户变量的名称，用户变量名称在单智能体中不支持重复。
描述	详细说明变量的用途和预期存储的内容，帮助智能体更好地理解和处理用户数据。
默认值	可选，为变量设置一个默认值，以便在用户未提供特定信息时使用。

如图1所示，分别添加“name”和“language”用户变量。

表5 添加用户变量
名称	描述	默认值
name	用户称呼	-
language	交流语言	-

图1 添加用户变量

在提示词中引入变量。通过“{{memory.变量名}}”的语法格式，可以将已定义的变量编排进提示词中，从而约束智能体的回复逻辑。
在提示词编辑框中输入以下结构化指令：
```
## 角色 
你是一个智能客服助手，请根据用户的提问进行问答。  

## 用户信息 
- 用户称呼：{{memory.name}} 
- 交流语言：{{memory.language}}  

## 规则 
1. 始终使用{{memory.language}}与用户交流 
2. 称呼用户为"{{memory.name}}"
```
编写提示词时，可单击提示词编辑框的“”引用变量图标，在弹出的列表中快速选择并插入变量引用。

图2 引用变量
预览调试与动态变量感知。用户变量会根据对话内容自动提取与实时更新，可以在“预览调试”窗口验证智能体对变量的处理逻辑。
1. 初次赋值测试：在“预览调试”窗口输入：我叫小王，请用中文跟我交流。
  原理说明：大模型会自动识别意图，将“小王”赋值给“name”，将“中文”赋值给“language”。
  
  查看变量：如图3所示，单击右上角的记忆图标，进入“用户变量”页签，即可查看当前已配置变量的实时取值。
  
  图3 预览调试变量
  
  图4 变量成功赋值
2. 动态更新测试：在同一对话流中输入：我不叫小王，我叫小李，用英文跟我交流吧。
  行为观测：将自动覆盖旧值，变量“name”更新为“Li”，“language”更新为“英文”，且智能体后续的回复将立即切换为英文。
  
  状态重置：若需重新模拟，可单击重置按钮，将所有变量赋值清空。
  
  图5 变量动态变化

示例：配置与使用入参变量

使用场景：

当需要在智能体中固定某些参数值时，即适合使用入参变量。典型场景包括：

固定组件入参：为工作流、插件、MCP服务中的某个参数绑定固定值。例如，将天气查询服务的城市参数固定为“上海”，无论用户如何提问，服务始终查询上海的天气。
固定提示词上下文：在提示词中引用入参变量，为智能体注入固定的背景信息或约束条件。

以下通过一个天气查询场景，演示“入参变量”的完整配置方法和典型引用方式。

示例场景说明：

本示例将创建一个"城市旅行助手"智能体，为其添加天气查询插件，并通过入参变量将城市参数固定为"上海"。配置完成后，无论用户如何提问，智能体始终基于"上海"进行回复。

创建单智能体。

参考表6创建一个“城市旅行助手”单智能体。

表6 单智能体入参变量示例
单智能体信息	示例值
名称	城市旅行助手
描述	根据用户的提问进行旅行目的地问答。

添加插件。

进入“城市旅行助手”的单智能体配置界面，添加“天气查询”类插件。添加插件的详细操作步骤可参考添加插件。

新增入参变量。

在“记忆”模块的“入参变量”处，单击“

”新增入参变量，参考表7添加入参变量，单击“确定”。

表7 添加入参变量
参数	说明	配置示例
名称	入参变量的名称，支持中英文字符，不支持 ^，最长 100 个字符。	城市
描述	非必填。用于标识该入参变量的用途，最长 200 个字符。	旅行目的地
类型	选择入参变量的数据类型，当前支持String、Boolean、Integer、Number。	String
默认值	非必填。入参变量的默认值。	上海

图6 添加入参变量

在插件参数中引用变量。
1. 鼠标放置在“天气查询”插件处，单击“天气查询”插件的“参数配置”图标。
  图7 参数配置
2. 在“插件参数配置”界面，单击“location”参数的“默认值”列，选择“引用”，然后选择已配置的“城市”入参变量。
3. 关闭“location”参数的“可见性”开关，固定该参数不被智能体修改，单击“确定”完成插件参数配置。
  如果“可见性”开关保持开启，智能体在对话过程中会根据用户的提问内容自动覆盖默认值，入参变量的固定效果将不生效。
  图8 插件参数配置
预览调试。

在右侧“预览调试”窗口进行提问。此时无需在提问中提及城市名称，智能体也会默认查询并回复上海的天气信息。

单击右上角的“”记忆图标，进入“入参变量”页签，即可查看当前已配置的入参变量取值。
图9 预览调试