Harness 与 Agent 工程 · 上下文与记忆 · 2026-05-06

看 AgentRun 如何玩转记忆存储,最佳实践来了!

阿里云AgentRun通过三种记忆存储能力,让智能体真正记住用户需求,打造个性化交互体验。

核心内容:

  1. AgentRun平台集成表格存储提供的三大记忆能力解析
  2. 从零开始配置记忆存储的完整操作指南
  3. 代码示例演示会话历史、长期记忆和会话状态的实际应用

阿里云 AgentRun 是一个以高代码为核心的一站式 Agentic AI 基础设施平台。秉持生态开放和灵活组装的理念,为企业级 Agent 应用提供从开发、部署到运维的全生命周期管理。AgentRun 通过集成表格存储(Tablestore),为智能体提供三种持久化记忆能力:在同一对话中维持上下文的会话历史、跨会话保留用户偏好等结构化信息的长期记忆,以及可直接读写的会话状态。本文介绍如何创建并配置记忆存储,并通过可运行的代码示例演示三种记忆类型的使用方式。记忆类型

Cloud Native

快速使用

Cloud Native

▍步骤一:创建记忆存储

  1. 登录函数计算控制台(https://account.aliyun.com/login/login.htm?oauth_callback=https%3A%2F%2Ffcnext.console.aliyun.com%2F&lang=zh),在左侧菜单栏单击函数智能 > 智能体 AgentRun,进入 AgentRun 控制台。重要:如果进入 AgentRun 控制台后,右上角有“体验新版”字样,单击切换到新版控制台。

  2. 在左侧菜单栏单击记忆,然后单击添加记忆存储,填写相关配置项:

  3. 单击开始部署,等待记忆存储部署完成。▍步骤二:创建 Agent 并体验记忆功能

  4. 在左侧菜单栏单击 Agent 运行时,然后单击创建 Agent,选择快速创建,填写相关配置项:

  5. 单击创建 Agent,等待 Agent 启动完成。3. 在模型对比测试窗口中: - 输入“我叫小明,最近在学习向量数据库”,观察 Agent 回复(说明:函数计算遵循 Serverless(无服务器)架构,只有在请求到达时才创建实例,并能及时释放实例帮助用户节省成本。因此,首次提问时,会有较长的等待时间。)

代码集成

Cloud Native

▍环境准备

pip3 install alibabacloud_agentrun20250910 openai tablestore agentrun-sdk agentrun-mem0ai google-adk litellm langchain-openai

配置环境变量(请勿将密钥硬编码在代码中):

## 阿里云账号凭据export ALIBABA_CLOUD_ACCESS_KEY_ID="your-access-key-id"export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your-access-key-secret"# Agent调用配置(在控制台Agent运行时 > 详情 > 概览 > 访问信息中获取)export AGENT_ENDPOINT="https://{ACCOUNT_ID}.agentrun-data.{REGION}.aliyuncs.com/agent-runtimes/{AGENT_NAME}/endpoints/Default/invocations"# Agent调用凭证(在控制台凭证管理中获取)export AGENT_API_KEY="your-agent-api-key"# 记忆存储名称(步骤一创建后获取)export MEMORY_COLLECTION_NAME="mem-xxxx"# DashScope API Key(LangChain 和 Google ADK 示例使用)export DASHSCOPE_API_KEY="your-dashscope-api-key"# Tablestore 配置(会话状态示例使用)export TABLESTORE_ENDPOINT="https://{INSTANCE}.{REGION}.ots.aliyuncs.com"export TABLESTORE_INSTANCE="your-instance-name"

▍会话历史

三轮对话测试:第 1 轮告知姓名和职业,第 2 轮直接问“我是谁”,验证 Agent 是否记住了上文;第 3 轮继续追问,验证完整上下文是否贯穿始终。每次运行生成新的 session_id,互不干扰。

import osimport reimport threadingimport timeimport uuidfrom openai import OpenAI# ── 配置 ──────────────────────────────────────────────────────────────────────AGENT_ENDPOINT = os.environ["AGENT_ENDPOINT"]AGENT_API_KEY = os.environ["AGENT_API_KEY"]MODEL = os.getenv("MODEL", "qwen3.5-plus")# 从 Endpoint URL 解析账号 ID 和 Agent 名称。# Endpoint 格式:https://{ACCOUNT_ID}.agentrun-data.{REGION}.aliyuncs.com/agent-runtimes/{AGENT_NAME}/endpoints/Default/invocations# 注意:这里使用账号 ID 仅适合单用户演示场景。在多用户应用中,# user_id 应代表终端用户(如应用内的用户 ID),而非开发者账号。_account_match = re.match(r"https://(\d+)\.agentrun-data\.", AGENT_ENDPOINT)USER_ID = _account_match.group(1) if _account_match else "default_user"_agent_match = re.search(r"/agent-runtimes/([^/]+)/endpoints/", AGENT_ENDPOINT)AGENT_ID = _agent_match.group(1) if _agent_match else "default_agent"client = OpenAI( base_url=f"{AGENT_ENDPOINT}/openai/v1", api_key=AGENT_API_KEY,)# ── 对话函数 ──────────────────────────────────────────────────────────────────def _spinner(stop_event: threading.Event): """在等待首个 Token 期间显示转圈动画。""" frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'] i = 0 while not stop_event.is_set(): print(f'\r助手: 正在思考... {frames[i % len(frames)]}', end='', flush=True) time.sleep(0.1) i += 1 print('\r' + ' ' * 35 + '\r', end='', flush=True)def chat(session_id: str, history: list, message: str) -> str: """向 Agent 发送消息,通过 session_id 和消息历史维持会话上下文。 history 为本轮之前的对话历史,格式为 [{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}, ...] 只保留 user/assistant 的文本内容(不含 tool_calls),历史消息与本轮消息 一起发送,Agent 可从上下文中直接读取之前的对话内容。 session_id 通过请求头 X-AgentRun-Conversation-ID 传递,AgentRun 用其 关联 Tablestore 中的会话记录(用 extra_body 传递无效,服务端不读请求体)。 """ print(f"用户: {message}") # 启动转圈动画(覆盖冷启动和 MCP 工具调用的等待时间) stop_event = threading.Event() spinner = threading.Thread(target=_spinner, args=(stop_event,), daemon=True) spinner.start() stream = client.chat.completions.create( model=MODEL, messages=history + [{"role": "user", "content": message}], stream=True, extra_headers={ "X-AgentRun-Conversation-ID": session_id, "X-AgentRun-User-ID": USER_ID, "X-AgentRun-Agent-ID": AGENT_ID, }, ) full_reply = [ ] first_token = True for chunk in stream: if chunk.choices and chunk.choices[0].delta.content: token = chunk.choices[0].delta.content if first_token: stop_event.set() spinner.join() print("助手: ", end="", flush=True) first_token = False print(token, end="", flush=True) full_reply.append(token) stop_event.set() spinner.join() print("\n") return "".join(full_reply)# ── 主程序 ────────────────────────────────────────────────────────────────────def main(): # 每次运行生成新的 session_id,避免与上次运行的历史混淆。 # 在实际应用中,session_id 通常由应用层管理(如绑定用户的对话 ID)。 session_id = str(uuid.uuid4()) history = [ ] # 维护对话历史(只含 user/assistant 文本消息) print("═" * 50) print("示例:多轮对话(会话历史)") print("═" * 50) print("提示:首次请求函数计算需要创建实例(冷启动),可能需要较长等待时间,请耐心等待。") # 第一轮:自我介绍 print("\n[第 1 轮]") q1 = "我叫小明,我是一名数据工程师,最近在研究 Tablestore" r1 = chat(session_id, history, q1) history.extend([ {"role": "user", "content": q1}, {"role": "assistant", "content": r1}, ]) # 第二轮:测试 Agent 是否记住了第一轮的内容 print("[第 2 轮]") q2 = "我叫什么名字?我从事什么工作?我最近在研究什么?" r2 = chat(session_id, history, q2) history.extend([ {"role": "user", "content": q2}, {"role": "assistant", "content": r2}, ]) # 第三轮:继续深入话题 print("[第 3 轮]") q3 = "针对我的工作,你有什么 Tablestore 使用建议?" chat(session_id, history, q3)if __name__ == "__main__": main()

说明:推荐使用流式模式(stream=True):Agent 在处理消息时会调用 MCP 记忆工具(读写 Tablestore),流式模式可避免客户端因等待 MCP 工具调用而超时。

将上述代码保存为 conversation_history.py 并运行:

python3 conversation_history.py

▍长期记忆

方式一:通过 MCP 集成

在记忆详情的长期记忆 > MCP 集成中启动服务配置,启动后获取 MCP 服务 URL(SSE),配置到支持 MCP 工具调用的 Agent 中,即可自动提取、更新、删除长期记忆。

说明:通过控制台使用 Agent 运行时,可在创建 Agent 配置记忆时开启 MCP(未提示表示已开启),Agent 会在每轮对话中自动调用 MCP 工具检索和更新长期记忆。对话中出现可提取的用户信息时(如:“我喜欢喝咖啡”),Agent 会自动存入向量库供后续跨 session 使用。

方式二:直接操作 mem0 向量存储

与方式一不同,方式二需要由代码显式调用 memory.add() 写入记忆—— mem0 不会自动监听对话,也不会自动判断“哪些内容值得记录”。这种方式适合在自定义 Agent 框架或数据管道中,由业务逻辑精确控制记忆的写入时机和内容。

本示例写入一段用户描述,mem0 内部调用 LLM 将其拆解为多条结构化记忆(如“名叫 Alice”、“喜欢喝咖啡”),然后用三个不同角度的语义查询验证检索效果。

import osimport timefrom agentrun.memory_collection import MemoryCollection# ── 配置 ──────────────────────────────────────────────────────────────────────MEMORY_COLLECTION_NAME = os.environ["MEMORY_COLLECTION_NAME"]# agentrun-sdk 自动从以下环境变量读取凭证(无需在代码中显式传入):# ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET# AGENTRUN_REGION(默认 cn-hangzhou)# ── 初始化 mem0 客户端 ────────────────────────────────────────────────────────# to_mem0_memory() 自动完成两件事:# 1. 从 AgentRun 控制平面读取记忆存储配置(Tablestore 实例、集合、向量维度等)# 2. 使用读取到的配置初始化 agentrun-mem0ai Memory 客户端memory = MemoryCollection.to_mem0_memory(MEMORY_COLLECTION_NAME)# ── 核心操作 ──────────────────────────────────────────────────────────────────def add_memories(user_id: str): """向记忆存储中添加用户信息。 memory.add() 支持两种输入: - str:直接写入一段描述文本,mem0 内部会自动提炼为结构化记忆 - list[dict]:完整的对话消息列表(role/content),mem0 从中提取用户偏好 本示例使用文本输入演示基本用法。 """ print(f"\n[添加记忆] user_id={user_id}") result = memory.add( "我叫 Alice,是一名 Python 工程师,平时喜欢喝咖啡,最近在研究向量数据库。", user_id=user_id, metadata={"source_app": "openmemory", "mcp_client": "python_sdk"}, ) results = result.get("results", [ ]) print(f" 写入 {len(results)} 条记忆:") for i, res in enumerate(results, 1): print(f" {i}. [{res.get('event')}] {res.get('memory', '')}")def search_memories(user_id: str, query: str): """从记忆存储中检索与查询语义最相关的记忆。""" print(f"\n[检索记忆] 查询: {query!r}") results = memory.search(query, user_id=user_id) hits = results.get("results", [ ]) if not hits: print(" (未找到相关记忆)") return for i, hit in enumerate(hits, 1): score = hit.get("score", 0) content = hit.get("memory", "") print(f" {i}. [{score:.4f}] {content}")# ── 主程序 ────────────────────────────────────────────────────────────────────def main(): print("═" * 55) print("长期记忆示例 —— 直接操作 mem0 向量存储") print("═" * 55) print("提示:首次请求函数计算需要创建实例(冷启动),可能需要较长等待时间,请耐心等待。") user_id = "alice-demo" # 写入记忆 add_memories(user_id) # 等待 Tablestore 向量索引刷新(首次写入后搜索需要短暂延迟) print("\n等待向量索引刷新...") time.sleep(3) # 语义检索:不同的查询角度 print() print("──" * 27) search_memories(user_id, "她喜欢什么饮料?") search_memories(user_id, "她是做什么工作的?") search_memories(user_id, "她最近在研究什么技术?")if __name__ == "__main__": main()

将上述代码保存为 long_term_memory.py 并运行:

python3 long_term_memory.py

方式三:LangChain 生态集成

以旅行规划助手为例,演示在 LangChain 对话循环中集成 mem0 长期记忆的完整模式:每轮对话开始时先检索与用户问题相关的历史记忆并注入 prompt,生成回复后再将本轮对话内容写回 mem0,使记忆在对话过程中持续积累。多轮后可观察到 Agent 能主动引用早先提到的旅行偏好。

import osimport threadingimport timefrom typing import Listfrom langchain_core.messages import SystemMessage, HumanMessage, BaseMessagefrom langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholderfrom langchain_openai import ChatOpenAIfrom agentrun.memory_collection import MemoryCollection# ── 配置 ──────────────────────────────────────────────────────────────────────MEMORY_COLLECTION_NAME = os.environ["MEMORY_COLLECTION_NAME"]DASHSCOPE_API_KEY = os.environ["DASHSCOPE_API_KEY"]# ── 初始化 LLM 和 mem0 客户端 ─────────────────────────────────────────────────# 通过 DashScope OpenAI 兼容接口调用大模型llm = ChatOpenAI( base_url="https://dashscope.aliyuncs.com/compatible-mode/v1", api_key=DASHSCOPE_API_KEY, model…
— 以上为试看内容(约 40%),开通会员后阅读全文 —

原文出处:https://www.53ai.com/news/RAG/2026050665432.html