LangChain 之 Agent 长期记忆工具读写

简介: 本文详解LangChain中ToolRuntime驱动的长期记忆实践,直击工具取不到Store、模型记混用户等痛点。涵盖注入机制、参数校验、Command规范、写入策略、异常兜底与生产装配,并通过双实验验证跨会话/跨用户隔离性,助你将记忆从Demo级落地为高可靠能力。

把 Store 传给 create_agent 之后,工具里却取到空值;工具明明写了记忆,模型下一轮还是答不上来;更麻烦的是模型自作主张,把 A 用户的偏好写进了 B 用户的命名空间。这几类问题都不在 Store 本身,而在工具这一侧的写法。

长期记忆的主力入口就是工具。LangChain 官方把读写示例放在工具里,Notion 笔记的长期记忆章节也把「工具中实现读写」单独列成一节。原因不难理解,模型能自己判断这一轮要不要查、要不要记,应用侧不必预先猜测。灵活是有代价的,参数怎么注入、身份从哪来、工具返回什么、写失败怎么办,每一处都有规矩。

本篇只讲这一条路径,从 ToolRuntime 的注入机制开始,给一套带参数校验的读写工具,再处理 Command、写入策略、异常兜底与生产装配,最后用两个实验验证结果。

一、工具拿不到 Store,多半是签名没写对

工具函数里想访问运行时信息,写法只有一个,在签名里声明 runtime: ToolRuntime。类型注解不能省,它同时定义了工具的输入结构。调用时由 ToolNode 自动注入,这个参数不会出现在发给模型的工具描述里,模型看不见它,也不需要为它填值。

from dataclasses import dataclass
from langchain.tools import ToolRuntime, tool

@dataclass
class Context:
    user_id: str
    tenant_id: str

@tool
def load_profile(runtime: ToolRuntime[Context]) -> str:
    """读取当前用户的档案。"""
    assert runtime.store is not None
    item = runtime.store.get(("users",), runtime.context.user_id)
    return str(item.value) if item else "暂无档案"

这里有三条容易忽略的规则。

第一,runtime 和 config 是保留参数名,不能拿它们当普通业务参数,否则运行时报错。第二,runtime.store 的类型允许为 None,忘了给 create_agent 传 store,工具里拿到的就是空值,所以取值前先断言,报错信息也比后续一串属性错误好定位。第三,官方已把 InjectedState、InjectedStore、get_runtime()、InjectedToolCallId 列为迁移前的旧写法,新代码统一收口到 ToolRuntime 一个对象,不必再记四套接口。

二、ToolRuntime 的八个属性,先分清三类上下文

ToolRuntime 像一只工具箱,把本次调用相关的运行时信息都装了进来。官方文档给出的属性如下。

属性 含义 典型用途
state 短期记忆,当前会话内的可变数据 读消息列表,取本会话的订单号
context 调用时传入的静态配置,不随对话变化 用户 id、租户 id、环境标识
store 长期记忆,跨会话存活的 JSON 文档库 读写用户偏好、档案、经验
stream_writer 流式写入器 工具执行中推送进度
tool_call_id 本次工具调用的唯一标识 构造 ToolMessage 或 Command
config 本次执行的 RunnableConfig 读取回调、标签、元数据
execution_info 执行标识与重试信息 取 thread_id、run_id、尝试次数
server_info 平台侧元数据 取 assistant_id、graph_id、登录用户

execution_info 与 server_info 需要 langgraph 1.1.5 以上版本,本地开发时 server_info 为 None,stream_writer 也要求工具运行在 LangGraph 的执行上下文里。

最容易混的是前三个。state 按 thread_id 隔离,会话结束就不管了;context 是每次 invoke 传进来的只读身份,本身不持久化;store 按 namespace 归档,任何 thread 都能取。工具里写偏好用 store,写「这一轮刚查过的订单号」用 state,判断「当前是谁」用 context,三者别互相替代。

泛型可以补上类型提示。官方示例给出 ToolRuntime[UserContext] 与 ToolRuntime[None, CustomState] 两种写法,前者约束 context,后者第二个参数约束自定义 state,不需要约束的那一位写 None。合起来就是第一位管 context,第二位管 state。

from langchain.agents import AgentState
from langchain.tools import ToolRuntime, tool

class SessionState(AgentState):
    current_order_id: str

@tool
def who_am_i(runtime: ToolRuntime[Context]) -> str:
    """返回当前调用的身份信息。"""
    return f"tenant={runtime.context.tenant_id}, user={runtime.context.user_id}"

@tool
def current_order(runtime: ToolRuntime[None, SessionState]) -> str:
    """返回本会话正在处理的订单号。"""
    return runtime.state.get("current_order_id", "无")

在这里插入图片描述

三、读写工具对,身份和写入内容都要约束住

把读写拆成两个工具是常见做法。写工具最怕模型自由发挥,类别填错、字段缺失、把整段对话塞进 value。用 Pydantic 模型配 args_schema,把类别限定成枚举,脏数据在参数校验阶段就被挡住,进不了 Store。官方示例也用 TypedDict 定义结构,写入时 dict(user_info) 转成字典,思路一致。

import uuid
from typing import Literal
from pydantic import BaseModel, Field
from langchain.tools import ToolRuntime, tool

class PreferenceInput(BaseModel):
    category: Literal["color", "food", "lang"] = Field(
        description="偏好类别,只能是 color、food、lang")
    value: str = Field(description="具体偏好内容,如蓝色、意大利面")

@tool(args_schema=PreferenceInput)
def save_preference(category: str, value: str,
                    runtime: ToolRuntime[Context]) -> str:
    """把一条用户偏好写入长期记忆,仅在用户明确表达偏好时调用。"""
    assert runtime.store is not None
    ns = (runtime.context.tenant_id, runtime.context.user_id, "preferences")
    runtime.store.put(ns, str(uuid.uuid4()),
                      {
   "category": category, "value": value})
    return "偏好已保存"

@tool
def load_preferences(runtime: ToolRuntime[Context]) -> str:
    """列出当前用户已保存的全部偏好。"""
    assert runtime.store is not None
    ns = (runtime.context.tenant_id, runtime.context.user_id, "preferences")
    items = runtime.store.search(ns, limit=50)
    if not items:
        return "暂无偏好记录"
    lines = [f"{it.value['category']} - {it.value['value']}" for it in items]
    return ";".join(["已保存的偏好"] + lines)

四个细节决定这套工具能不能用住。用户 id 和租户 id 从 runtime.context 取,绝不让模型填,模型猜错身份就会串数据。namespace 前段带上这两个值,写入用完整命名空间,因为 search 传短前缀会连带返回所有子命名空间的条目。docstring 写明「仅在用户明确表达偏好时调用」,模型靠工具描述判断调用时机,描述含糊就会出现每轮乱写或该写不写。search 的 limit 默认只有 10,超出部分静默截断,这里显式给 50。

put 的三个参数分别是命名空间元组、字符串 key 和字典 value,value 必须是字典,不能直接塞字符串。

四、返回 Command 时,ToolMessage 不能省

工具在读写长期记忆之外,还常要更新本会话状态。比如查订单时把订单号记进 state,供后续轮次复用。这时工具要返回 Command,而不是字符串。

from langchain.messages import ToolMessage
from langgraph.types import Command
from langchain.tools import ToolRuntime, tool

@tool
def bind_order(order_id: str,
               runtime: ToolRuntime[Context, SessionState]) -> Command:
    """记录本轮查询的订单号,并同步写入长期记忆。"""
    assert runtime.store is not None
    ctx = runtime.context
    runtime.store.put((ctx.tenant_id, ctx.user_id, "orders"), order_id,
                      {
   "last_action": "queried"})
    return Command(update={
   
        "current_order_id": order_id,
        "messages": [ToolMessage(
            content=f"订单 {order_id} 已记录",
            tool_call_id=runtime.tool_call_id,
        )],
    })

红线只有一条,消息历史里每一次工具调用都必须有对应的 ToolMessage。工具返回普通字符串时框架会自动包装,返回 Command 时不会自动包装,漏写或 tool_call_id 不匹配,ToolNode 会直接抛 ValueError。用 runtime.tool_call_id 取本次调用标识,别自己生成。

另一处是并发。模型可能在同一批次里并行调用多个工具,若它们都改同一个 state 字段,要给字段定义 reducer 决定如何合并,否则后写覆盖先写。

from typing import Annotated
import operator

class SessionState(AgentState):
    viewed_order_ids: Annotated[list[str], operator.add]

还要注意两个容器不是一回事。store.put 写的是跨会话的长期记忆,Command.update 改的是当前 thread 的短期状态,换一个 thread_id 后者就断了,前者仍在。

在这里插入图片描述

五、写入策略,key 决定后面好不好维护

namespace 定作用域,key 定更新语义。同一个 namespace 里对同一个 key 再次 put,是整份文档覆盖,不是按字段合并。只改一个字段却只传了那一个字段,其余字段会丢。

key 策略 写法 适合 注意
固定 key 覆盖 put(ns, "profile", value) 用户档案、配置 覆盖前先 get,把原字段补全再写
唯一 key 追加 put(ns, str(uuid.uuid4()), value) 偏好流、事件记录 需要 search 枚举,并做去重
业务主键 put(ns, order_id, value) 订单、工单等实体 主键稳定才具备幂等性

追加写最容易出现重复条目,用户每提一次偏好就写一条,几轮下来 Store 里全是同义记录。工具内部可以先按类别清理再写,把去重放在写入口,比事后跑清洗脚本省事。

def remember_once(store, ns, category, value):
    """同一类别只保留最新一条,避免每轮重复写入。"""
    for it in store.search(ns, limit=100):
        if it.value.get("category") == category:
            store.delete(ns, it.key)
    store.put(ns, f"{category}_latest",
              {
   "category": category, "value": value})

这段逻辑放在工具内部,也可以挪到会话结束后的后台任务里。判断新旧用 Item 的 updated_at,写错的记忆用 delete(namespace, key) 清掉,注意 delete 同样要传完整的命名空间。

六、工具异常要转成 ToolMessage

数据库抖动、连接超时、value 序列化失败,工具里抛出的异常会中断整轮 Agent 循环。记忆读写属于辅助能力,它失败时更合理的做法是降级,让模型知道这件事然后继续回答。用 @wrap_tool_call 中间件包一层即可。

from collections.abc import Callable
from langchain.agents.middleware import wrap_tool_call
from langchain.messages import ToolMessage
from langchain.tools.tool_node import ToolCallRequest

@wrap_tool_call
def handle_tool_errors(
    request: ToolCallRequest,
    handler: Callable[[ToolCallRequest], ToolMessage],
) -> ToolMessage:
    """把工具异常转成模型能理解的提示,避免整轮对话中断。"""
    try:
        return handler(request)
    except Exception as e:
        return ToolMessage(
            content=f"记忆读写暂时不可用,请稍后重试。({e})",
            tool_call_id=request.tool_call["id"],
        )

中间件里取调用标识用 request.tool_call["id"],工具内部用 runtime.tool_call_id,两处别混。也不要静默吞掉异常,返回给模型的提示要能说明发生了什么,同时在服务端记日志,否则线上只会看到「记忆时灵时不灵」。

七、生产装配与两个验证实验

InMemoryStore 方便调试,进程重启数据就没了。生产换成数据库后端,首次部署跑一次 setup() 建表。常驻服务在进程启动时初始化一次并复用同一个实例,脚本类任务可以用 with 包起来自动关连接。

from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.store.postgres import PostgresStore

DB_URI = "postgresql://postgres:postgres@localhost:5432/postgres?sslmode=disable"

store = PostgresStore.from_conn_string(DB_URI)
store.setup()

agent = create_agent(
    "claude-sonnet-4-6",
    tools=[save_preference, load_preferences, bind_order],
    store=store,
    checkpointer=InMemorySaver(),
    state_schema=SessionState,
    context_schema=Context,
    middleware=[handle_tool_errors],
)

context_schema 建议用 dataclass 或字典。本地案例中把 Pydantic 模型对象直接传给 invoke 的 context 参数,部分版本会触发 Pydantic 序列化警告,官方示例用的是 dataclass,照它来更省心。除 PostgresStore 外,官方还列了 MongoDBStore、RedisStore 等后端,接口一致。

装配完做两个实验,比翻日志直观。以下代码与上面的装配处在同一个作用域内。

ctx = Context(user_id="u_123", tenant_id="t_42")
cfg_a = {
   "configurable": {
   "thread_id": "session-a"}}
cfg_b = {
   "configurable": {
   "thread_id": "session-b"}}

agent.invoke(
    {
   "messages": [{
   "role": "user", "content": "记住我喜欢蓝色"}]},
    config=cfg_a, context=ctx,
)

r1 = agent.invoke(
    {
   "messages": [{
   "role": "user", "content": "我有哪些偏好"}]},
    config=cfg_b, context=ctx,
)
print("换会话", r1["messages"][-1].content)

other = Context(user_id="u_999", tenant_id="t_42")
r2 = agent.invoke(
    {
   "messages": [{
   "role": "user", "content": "我有哪些偏好"}]},
    config=cfg_a, context=other,
)
print("换用户", r2["messages"][-1].content)

print(store.search(("t_42", "u_123", "preferences"), limit=50))

第一个实验里 session-b 的短期记忆是空的,偏好仍应被读出来,说明 store 装配正确。第二个实验换成另一个用户,不应读到 u_123 的偏好,说明 namespace 隔离生效。最后一行直接查 Store,用来核对写入位置与条目数,把「模型说了什么」和「实际存了什么」分开验证。

现象 优先检查
工具里断言失败 create_agent 没传 store,或传了另一个实例
模型从不调用读写工具 docstring 过于含糊,或工具没注册进 tools
写入脏数据、类别乱填 没用 args_schema 或 TypedDict 约束入参
Command 抛 ValueError 漏了 ToolMessage,或 tool_call_id 不匹配
换用户读到别人偏好 namespace 前段没带 tenant_id 与 user_id
写入成功但读不到 search 传了短前缀,或 limit 小于实际条目数

八、上线检查清单

把工具侧的细节逐项过一遍,能挡掉大部分记忆类线上问题。

  1. store 是同一个实例,工具、中间件、Agent 三处指向一致。
  2. runtime 签名与类型注解齐全,runtime 和 config 没被当成业务参数。
  3. 用户身份只从 context 取,namespace 前段带 tenant_id 和 user_id。
  4. 写入参数有 Pydantic 或 TypedDict 约束,docstring 写清调用时机。
  5. 返回 Command 必带 ToolMessage 且 tool_call_id 匹配,并行改 state 定义了 reducer。
  6. key 策略明确,覆盖写前先 get 补全字段,追加写有去重。
  7. 工具异常经 wrap_tool_call 降级,不中断整轮回答,服务端有日志。
  8. 生产换成数据库 Store 并跑过 setup(),换 thread 与换 user 两个实验都通过。

在这里插入图片描述

工具读写的价值在于把判断交给模型,代价是每次调用都要多付出一轮开销,还要防住模型写错、写重、写串。把注入、约束、返回、去重、兜底这五处规矩立住,长期记忆才算从示例走到可用。下一篇会进入记忆综合案例,把短期状态、长期偏好、消息摘要和工具容错放进同一个客服助手里看它们怎么配合。

目录
相关文章
|
17天前
|
Linux 开发工具 iOS开发
Codex保姆级教程(下载+安装+登录+使用,含所有版本,2026最新)
Codex是OpenAI推出的开源AI编程智能体,本地运行,可理解整个代码库,支持自然语言指令改代码、执行命令、跑测试、修Bug,兼容Win/macOS/Linux。(239字)
7221 56
|
4天前
|
JSON 前端开发 API
阿里云最新Qwen4-Max大模型介绍:模型定位、特征、能力、适用场景解析
2026 年 11 月 11 日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问 AI 平台 Token Plan,并同步接入千问办公、Qoder 等入口。该版本聚焦知识理解、世界感知、编程与 Agentic 四项升级,主打复杂编程、专业办公、前端设计与专业软件操作。预览期至 11 月 25 日 24:00,到期后模型标识下线;限时 2 折、新用户再享 5 折,最低 1 折可体验。
|
5天前
|
云安全 人工智能 安全
|
18天前
|
JavaScript API iOS开发
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(DSH)是DeepSeek于2026年开源的MIT协议AI Agent框架,支持插件化组装模型、工具、沙箱与UI,兼容主流大模型。本文提供免Node.js的桌面端安装包(Win/macOS),含详细图文教程及热门插件推荐。
5528 67
|
12天前
|
Linux 开发工具 iOS开发
2026最新codex下载安装保姆级使用教程(下载+安装+登录+使用,含所有历史版本)
本文详解OpenAI Codex国内快速上手指南:提供Win/macOS/Linux全平台免安装包、npm/Homebrew等多方式安装、账号/API Key双登录、简体中文切换,覆盖下载、安装、汉化、使用及高频避坑(如微软商店失败、npm超时等),10分钟即可跑通。
2796 9
|
5天前
|
人工智能 前端开发 API
阿里云Qwen4-Max 大模型详解:定位、特征、能力、适用场景与相对Qwen3-Max差异解析
2026年11月11日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问AI平台Token Plan并接入千问办公、Qoder等入口。该版本聚焦知识理解、世界感知、编程与Agentic四项升级,主打复杂编程、专业办公、前端设计与专业软件操作等真实任务。预览期为11月11日10:00至11月25日24:00,仅支持Token Plan调用,到期后模型标识下线;限时2折、新用户再享5折,最低1折可体验。
|
10天前
|
人工智能 安全 API
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(dsh)是DeepSeek AI于2026年开源的轻量级Agent运行框架,基于Cordis内核,践行“一切皆插件”理念。支持Web/桌面双端,开箱即用;内置多模型接入、丰富插件生态(超3.5万),适配编程、办公、创作等场景。(239字)
1812 1
|
2天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
1285 0
|
8天前
|
人工智能 iOS开发 开发者
2026年 Codex 下载地址更新:codexdown.cn 已更换为 codexdown.cc(附 Codex 客户端下载)
2026年Codex官方下载站已由codexdown.cn正式迁移至codexdown.cc,提供Windows/macOS最新客户端、历史版本、安装教程及配置指南,开发者可一站式获取稳定、安全、签名验证的AI编程工具资源。(239字)
1681 0

热门文章

最新文章