本教程演示如何使用方舟 Managed Agents 的 **Memory Store（记忆存储）** 能力，构建一个能记住客户购物偏好的个人购物助手。跨会话保留的记忆让 Agent 无需在每次对话开始时重复询问尺码、预算、材质忌讳等信息，从而提供真正个性化的服务。 # 场景说明大多数销售助手每次对话都要从头开始。顾客告诉助手尺码、预算和不喜欢的材质，但下次顾客回来时，这些信息全都不见了，顾客不得不重复一遍，整个体验缺乏个性化。 Managed Agents 提供了开箱即用的记忆能力：Memory Store。它是一个由平台托管的持久化容器，Agent 可以在多次会话之间通过后端应用层 API 调用读写用户信息，从而记住用户。 # 你将构建什么 * 一个 Memory Store，用于保存单个客户的购物偏好。 * 一个配置为读写该 Memory Store 的购物 Agent。 * 两个独立的 Session，演示记忆如何跨会话延续。 * 一种从后端应用检查和初始化记忆的模式。 # 记忆如何工作 Memory Store 对 Agent 呈现为一个可读的文件目录，挂载在 Session 运行沙箱的 `/mnt/memory/{store-name}/` 路径下。应用程序可以通过 API 对相同的文件进行完整的读写：把已知信息预填到 Memory Store、审核 Agent 写入的内容，或将所有内容导出到自有系统。 ![图片](https://arkdocs.tos-cn-beijing.volces.com/flowcharts/tutorials/new-202607241248.svg) # 前置条件 * 已开通方舟 Managed Agents 和目标模型服务。 * 已创建 API Key，详情请参见 [API Key 管理](https://www.volcengine.com/docs/82379/1361424)。 * 本地已安装 `curl` 和 `jq`（用于解析 SSE 事件）。将 API Key、Base URL 配置为环境变量，方便后续 `curl` 命令复用： ```Bash export ARK_API_KEY="你的 API Key" export ARK_BASE_URL="https://ark.cn-beijing.volces.com/api/v3" ``` 所有请求统一使用以下鉴权头： ```Text Authorization: Bearer $ARK_API_KEY Content-Type: application/json ``` # 辅助函数：一步完成一轮对话为了让后续每一步不必重复输入长命令，先定义一个 shell 函数，一步完成「发送消息 + 订阅事件流」： ```Bash run_turn() { local session_id="$1" local user_text="$2" # ① 发送用户消息 curl -sS "$ARK_BASE_URL/sessions/$session_id/events" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg t "$user_text" \ '{events:[{type:"user.message",content:[{type:"text",text:$t}]}]}')" \ > /dev/null # ② 订阅 SSE 事件流，边接收边解析，直到 session.status_idle while IFS= read -r line; do [[ $line == data:* ]] || continue json=${line#data: } case $(jq -r '.type' <<<"$json") in agent.message) jq -j '.content[] | select(.type == "text") | .text' <<<"$json" ;; agent.tool_use) tool_name=$(jq -r '.name' <<<"$json") tool_input=$(jq -c '.input // {}' <<<"$json") printf '\n[Tool: %s] %s\n' "$tool_name" "$tool_input" ;; session.status_idle) printf '\n\nAgent finished.\n' break ;; session.status_terminated) printf '\n\nSession terminated.\n' break ;; esac done < <( curl -sS -N \ "$ARK_BASE_URL/sessions/$session_id/events/stream" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Accept: text/event-stream" 2>/dev/null ) } ``` # 第 1 步：创建 Memory Store Memory Store 是 Agent 存储客户偏好的容器。生产环境中，每位客户对应一个独立的 Memory Store，以保证隔离性。 ```Bash curl -X POST "$ARK_BASE_URL/memory_stores" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "shopper_preferences_demo", "description": "该记忆库保存客户的个人购物偏好。请在每次对话开始时读取，学到新偏好时立即写入。" }' ``` 响应示例： ```JSON { "id": "memstore-20260708080047-svq7t", "type": "memory_store", "name": "shopper_preferences_demo", "description": "该记忆库保存客户的个人购物偏好。请在每次对话开始时读取，学到新偏好时立即写入。", "memory_count": 0, "storage_bytes": 0, "session_count": 0, "created_at": "2026-07-08T08:00:47Z", "updated_at": "2026-07-08T08:00:47Z", "metadata": {} } ``` 记录返回的 `id`，后续步骤会将其作为 `STORE_ID` 使用。 # 第 2 步：创建购物 Agent 与 Environment 每个 Managed Agents Session 都需要一个 Agent（模型、System Prompt 和工具）和一个 Environment（Agent 运行所在的容器）。这两个资源一次创建后可以在多个客户与 Session 之间重复使用。创建 Agent： ```Bash curl -X POST "$ARK_BASE_URL/agents" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d @- <<'EOF' { "name": "Personal Shopper", "model": {"id": "doubao-seed-2-1-pro-260628"}, "system": "你是一位专业的品牌私人购物助手。你的核心职责是帮助客户找到符合他们个人品味和预算的商品。你需要主动了解客户的风格偏好、尺码信息、预算范围、感兴趣的品牌和品类等信息，并在对话中记住所有了解到的客户信息，以便在后续的交流和下次服务中能够提供更精准、个性化的推荐。你可以访问一个持久化的记忆库（挂载在 /mnt/memory/），里面可能存有该客户过往留下的偏好档案。对话开始时可以先查阅一下有没有相关信息，避免重复询问客户已经说过的事情。你的输出风格亲切、专业、有耐心，始终以客户的需求为中心，提供贴心的购物建议。", "tools": [ {"type": "agent_toolset_20260701"} ] } EOF ``` 创建 Environment： ```Bash curl -X POST "$ARK_BASE_URL/environments" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d @- <<'EOF' { "name": "shop_agent", "description": "为购物 Agent 提供基础运行环境", "config": { "type": "cloud", "networking": {"type": "unrestricted"} } } EOF ``` 将返回的 `agent.id` 和 `environment.id` 分别记录为 `AGENT_ID` 和 `ENVIRONMENT_ID`。

注意

networking.type=unrestricted 便于教程演示。生产环境应按最小可用范围收敛网络策略，只放行必要的出站主机。

# 第 3 步：创建 Session 并挂载 Memory Store Session 是一次会话上下文。挂载 Memory Store 时，通过 `instructions` 字段给出该会话的具体行为指令： ```Bash curl -X POST "$ARK_BASE_URL/sessions" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d @- < # 第 4 步：首次访问，Agent 学习偏好发送第一条用户消息，观察 Agent 如何一边对话一边读取或补充 Memory Store。 ```Bash curl -X POST "$ARK_BASE_URL/sessions/$SESSION_ID/events" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d @- <<'EOF' { "events": [ { "type": "user.message", "content": [ {"type": "text", "text": "你好，我想找一件秋冬外套，预算 800 以内，我平时穿 M 码，喜欢大地色系（驼色、卡其、焦糖），不接受动物皮革。"} ] } ] } EOF ``` 订阅事件流查看响应： ```Bash while IFS= read -r line; do [[ $line == data:* ]] || continue json=${line#data: } case $(jq -r '.type' <<<"$json") in agent.message) jq -j '.content[] | select(.type == "text") | .text' <<<"$json" ;; agent.tool_use) tool_name=$(jq -r '.name' <<<"$json") tool_input=$(jq -c '.input // {}' <<<"$json") printf '\n[Tool: %s] %s\n' "$tool_name" "$tool_input" ;; session.status_idle) printf '\n\nAgent finished.\n' break ;; esac done < <( curl -sS -N \ "$ARK_BASE_URL/sessions/$SESSION_ID/events/stream" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Accept: text/event-stream" ) ``` # 第 5 步：应用侧写入 Memory 从对话中提取用户偏好后，由应用后端直接调 REST API 落库，应用侧掌控写入时机和内容格式： ```Bash curl -X POST "$ARK_BASE_URL/memory_stores/$STORE_ID/memories" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "path": "/user_preferences.md", "content": "# 用户购物偏好\n- 尺码：M\n- 颜色偏好：大地色系（驼色、卡其、焦糖）\n- 预算：秋冬外套 ≤ 800 元\n- 材质禁忌：完全不接受动物皮革（真皮、真皮拼接、天然麂皮）\n- 可接受：人造革、仿麂皮" }' ``` 响应示例： ```JSON { "id": "mem-20260708084847-c5xnj", "type": "memory", "memory_store_id": "memstore-20260708080047-svq7t", "path": "/user_preferences.md", "content_sha256": "c459e3ea973af3e5f5a10d1548136cedceeec613893dc8e641e3f3886fe0f3b5", "content_size_bytes": 256, "memory_version_id": "memver-20260708084847-zdg9g", "created_at": "2026-07-08T08:48:47Z", "updated_at": "2026-07-08T08:48:47Z" } ``` # 第 6 步：检查 Memory Store 内容应用后端可以直接读取 Memory Store 的内容，用于审计、向用户展示「我们记住了什么」，或做数据分析： ```Bash curl "$ARK_BASE_URL/memory_stores/$STORE_ID/memories?view=full" \ -H "Authorization: Bearer $ARK_API_KEY" ``` 响应示例： ```JSON { "data": [ { "type": "memory", "path": "/user_preferences.md", "id": "mem-20260708084847-c5xnj", "memory_store_id": "memstore-20260708080047-svq7t", "content_size_bytes": 256, "memory_version_id": "memver-20260708084847-zdg9g", "created_at": "2026-07-08T08:48:47Z", "updated_at": "2026-07-08T08:48:47Z" } ], "prefixes": [] } ``` # 第 7 步：再次访问，Agent 自主回忆关闭原 Session，创建一个新的 Session，挂载同一个 Memory Store。观察 Agent 在完全新的会话里如何主动读取偏好——不问尺码、不问预算、不问颜色。重复第 3 步创建新 Session（`resources` 保持不变），记录新的 `NEW_SESSION_ID`，然后发送新的消息： ```Bash curl -X POST "$ARK_BASE_URL/sessions/$NEW_SESSION_ID/events" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "events": [ { "type": "user.message", "content": [ {"type": "text", "text": "最近有什么新款外套推荐？帮我看看有什么值得入手的。"} ] } ] }' ``` 订阅事件流后可以看到 Agent 主动读取 Memory Store 的顺序： ```Text [Tool: bash] ls -la /mnt/memory/ -- 查询记忆挂载目录 [Tool: bash] ls -la /mnt/memory/memstore-20260708080047-svq7t/ -- 进入 store 子目录 [Tool: read] /mnt/memory/memstore-20260708080047-svq7t/user_preferences.md -- 读取偏好文件 ``` Agent 读取到偏好后，会基于「M 码、大地色系、预算 ≤ 800 元、不接受动物皮革」直接给出符合条件的推荐，不再重复询问。

注意

Memory Store 采用文件挂载语义而非上下文注入语义。挂载后记忆以只读文件出现在沙箱 /mnt/memory// 子目录下，平台不会把内容自动塞进模型上下文。因此必须在 System Prompt 或 Session instructions 中明确指示 Agent 「先执行 ls -R /mnt/memory 找到并读取全部记忆文件」，否则 Agent 用顶层通配符匹配不到子目录里的文件，会误判「没有记忆」。

# 进阶模式一：从已有数据预填 Memory Store 如果业务系统已经有客户画像（会员等级、历史订单、CRM 备注），可以在客户第一次进入 Agent 之前直接把已知信息写入 Memory Store，让 Agent 一开始就「认识」客户： ```Bash curl -X POST "$ARK_BASE_URL/memory_stores/$STORE_ID/memories" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "path": "/history.md", "content": "# 已知信息\n- 会员等级：Gold\n- 常购品类：户外服饰\n- 上次购买日期：2026-06-20\n- 常用支付：微信支付" }' ``` # 进阶模式二：组合每客户存储与共享存储典型生产模式：一个 Session 同时挂载多个 Memory Store——一个客户私有（可读写）、一个品牌共享（只读）： ```Bash curl -X POST "$ARK_BASE_URL/sessions" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d @- < # 进阶模式三：覆盖修正已有记忆 Agent 可能记错内容（例如把「过敏」记成「不喜欢」）。当前 API 不支持 PATCH 直接更新，需要通过「DELETE + POST」组合实现覆盖修正：先删除旧记录，再用同一个 `path` 重新写入。 ```Bash # ① 查出要更新的 memory_id MEMORY_ID=$(curl -sS "$ARK_BASE_URL/memory_stores/$STORE_ID/memories" \ -H "Authorization: Bearer $ARK_API_KEY" \ | jq -r '.data[] | select(.path=="/user_preferences.md") | .id') # ② 删除旧记录 curl -X DELETE "$ARK_BASE_URL/memory_stores/$STORE_ID/memories/$MEMORY_ID" \ -H "Authorization: Bearer $ARK_API_KEY" # ③ 用同一 path 重新写入 curl -X POST "$ARK_BASE_URL/memory_stores/$STORE_ID/memories" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "path": "/user_preferences.md", "content": "# 用户购物偏好（更新后版本）\n- 尺码：M\n- 颜色偏好：大地色系（驼色、卡其、焦糖）\n- 预算：秋冬外套 ≤ 800 元\n- 材质禁忌：完全不接受动物皮革\n- 新增：严重花生过敏，请勿推荐相关周边食品\n- 可接受：人造革、仿麂皮" }' ``` # 第 8 步：清理资源 Demo 结束后，请按以下顺序清理资源，避免占用额度和留下测试数据： ```Bash # 1. 删除 Session（Environment 上如有 Session 未清，第 3 步会报 InvalidAction） curl -X DELETE "$ARK_BASE_URL/sessions/$SESSION_ID" \ -H "Authorization: Bearer $ARK_API_KEY" # 2. 删除 Agent（如不再复用） curl -X DELETE "$ARK_BASE_URL/agents/$AGENT_ID" \ -H "Authorization: Bearer $ARK_API_KEY" # 3. 删除 Environment（该环境下的所有 Session 必须先删完，否则会拒绝） curl -X DELETE "$ARK_BASE_URL/environments/$ENVIRONMENT_ID" \ -H "Authorization: Bearer $ARK_API_KEY" # 4. 删除 Memory Store curl -X DELETE "$ARK_BASE_URL/memory_stores/$STORE_ID" \ -H "Authorization: Bearer $ARK_API_KEY" ```

警告

删除 Memory Store 不可恢复，操作前请确认该 Store 中的偏好数据已无长期保留价值。

火山方舟