👁 89 次阅读

LlamaIndex Agent 为何把 state_prompt 永久写入 ChatMemoryBuffer 历史？

来源链接：https://github.com/run-llama/llama_index/issues/23234 这是 run-llama/llama_index 仓库的 issue #23234。该 issue 当前状态为 open，创建于 2026-09-25，最后更新于 2026-10-01，无标签，反应合计 0，剔除机器人或无效留言后共有 6 条实质评论。状态结论以末条实质评论为准：issue 仍处于 open 状态，官方尚未合并修复，社区已提交 PR 但停留在讨论阶段。

现象描述

当 workflow agent 使用 initial_state / state_prompt 并搭配默认的 ChatMemoryBuffer 时，setup_agent 会就地修改存入内存的那个用户 ChatMessage。格式化后的 "Current state: … Current message: …" 字符串会成为内存中永久的用户轮次，导致后续 LLM 上下文、分析数据以及恢复的会话都永久带有 workflow 状态，同时丢失了干净的用户原话。根据 issue 讨论，这一问题的表现与运行期间的嵌套修复（formatted_input_with_state 及相关 issue）不同：这种污染会跨运行保留下来，一直留在 memory.get() 中。报告者在 llama-index-core==0.14.25、Python 3.13 环境下可以稳定复现。以下为 issue 中提供的最小复现代码：

import asyncio
from llama_index.core.agent.workflow import ReActAgent
from llama_index.core.llms.mock import MockLLM
from llama_index.core.memory import ChatMemoryBuffer

def ping(x: str) -> str:
    """Echo the input string."""
    return x

async def main() -> None:
    llm = MockLLM(max_tokens=32)
    memory = ChatMemoryBuffer.from_defaults(token_limit=5000)
    agent = ReActAgent(
        name="agent",
        llm=llm,
        tools=[ping],
        initial_state={"user_id": "u-42", "plan": "secret-plan"},
        streaming=False,
        timeout=60,
    )
    try:
        await agent.run(user_msg="What is 2+2?", memory=memory, max_iterations=1)
    except Exception:
        pass  # mutation happens in setup_agent before max-iterations

    content = memory.get()[0].content or ""
    print(repr(content))
    assert "secret-plan" in content  # permanently written into history

asyncio.run(main())

期望行为是内存保留用户原文 "What is 2+2?"，状态注入只影响临时的 LLM 提示。实际行为是存储的用户消息变成：

Current state:
{'user_id': 'u-42', 'plan': 'secret-plan'}

Current message:
What is 2+2?

背景原因

根据 issue 中给出的根因定位，在 BaseWorkflowAgent.setup_agent 中，block.text = self.state_prompt.format(...) 就地修改了 llm_input[-1]。而 ChatMemoryBuffer.get() 返回的是 store 中持有的同一批 ChatMessage 对象，因此这个修改会一直保留下来。报告者指出，使用 SQL Memory 时不会把被修改的对象写回，但 agent 默认使用的是 ChatMemoryBuffer，所以默认路径就会命中该问题。社区成员 usmanasifbutt 在 2026-09-25 的评论中确认了这一点，并给出了更精确的诊断：setup_agent 复制了列表，但修改的是与 ChatMemoryBuffer 共享的那个 TextBlock。也就是说，问题不在列表本身，而在列表元素所引用的可变对象被就地改写。

排查或量化方法

验证该问题只需要在 agent 运行后直接读取内存内容并与原始输入比对。issue 中给出的复现思路可以拆解为几个可操作的检查点：

构造一个带 initial_state 的 agent，同时传入一个 ChatMemoryBuffer 实例。
调用 agent.run(user_msg=..., memory=memory, ...)，注意即使 max_iterations=1 或抛异常也不影响写入，因为修改发生在 setup_agent 阶段、迭代开始之前。
读取 memory.get()[0].content，检查其中是否出现了 initial_state 中的字段值。
如果断言 "secret-plan" in content 通过，说明状态已永久写入内存历史。

这个检查方式的价值在于绕开了 LLM 输出的不确定性，直接观察内存对象的状态，因而能稳定区分「提示中临时注入状态」与「内存被持久污染」两种情形。

完整解决方案（含必要代码）

需要说明的是，截至末条实质评论，该 issue 仍为 open，官方尚未合入修复方案。社区侧的实际进展如下。 usmanasifbutt 于 2026-09-25 打开了 PR https://github.com/run-llama/llama_index/pull/23242。据该评论，该 PR 的做法是格式化最后一条用户消息的副本，而不是直接编辑原消息，因此内存保留原始文本。同样的改动也应用到了 AgentWorkflow.setup_agent 中的相同代码。该评论还特别提示了一个行为变化：在此之前，后续步骤向 LLM 展示的只是第一个状态（因为旧文本被存进了内存），而修改之后每一步都会看到当前状态。另一位参与者 chenhz01 于 2026-09-30 提供了一个 format_state_prompt 的片段，思路是从副本构建 LLM 提示，让内存保持干净，并称可作为就地编辑被移除前的 drop-in 方案。该评论中的代码片段因原始内容被截断，完整实现以 issue 原文为准。 usmanasifbutt 于 2026-10-01 回应确认是同一个根因，并表示其 PR #23242 与上述片段思路一致（构建副本、不修改存储的消息），且已直接接入 BaseWorkflowAgent 与 AgentWorkflow 两处的 setup_agent。该评论补充了一个额外处理点：它会沿着 llm_input 回溯查找最后一条 user-role 消息，而不是假设固定位置，因为在后续循环轮次中，最后一条消息是工具结果而非用户消息。从方案适用性看，需要关注以下对比：

维度	现状（就地修改）	PR #23242 方向
内存中的用户消息	被替换为 `Current state: … Current message: …`	保留原始用户文本
状态注入范围	跨运行持久留在内存	仅影响临时 LLM 提示
后续步骤看到的状态	只看到第一个状态（旧文本已存入内存）	每一步都看到当前状态
消息定位方式	假设固定位置 `llm_input[-1]`	回溯查找最后一条 user-role 消息
合并状态	未合并，issue 仍 open	已提交 PR，等待处理
涉及代码路径	`BaseWorkflowAgent.setup_agent`	`BaseWorkflowAgent` 与 `AgentWorkflow` 两处

维护者 michaelkillgta 于 2026-09-25 回复称，usmanasifbutt 的复现与共享 TextBlock 诊断与其观察到的一致，同意按 copy-on-write 方向推进并补充回归测试，并表示不会就这一问题另开竞争性 PR。2026-09-28 该维护者再次回复，表示将此问题留给 PR #23242 处理。据 issue 讨论，官方侧尚未确认修复版本，也未将代码合并进主干。

常见错误排查

断言在 max_iterations=1 下仍通过：这不是误报。修改发生在 setup_agent 阶段，早于迭代计数生效，所以限制迭代数或让 run 抛异常都无法阻止污染。
改用 SQL Memory 后问题消失，误以为修复了：据 issue 讨论，SQL Memory 不把被修改的对象写回，因此看不到症状，但 agent 默认使用 ChatMemoryBuffer，默认路径仍然命中。这是掩盖而非修复。
把该问题与运行期间的嵌套问题混为一谈：报告者明确区分了两者。formatted_input_with_state 及相关 issue 处理的是运行期间的嵌套，而此处的问题是污染跨运行保留在 memory.get() 中。
只修 BaseWorkflowAgent 而漏掉 AgentWorkflow：据 PR 评论，两处都有相同代码，需同时改动。
只假设最后一条消息是用户消息：据 2026-10-01 的评论，在后续循环轮次中最后一条消息是工具结果，固定按位置取 llm_input[-1] 会取错对象，需要回溯查找 user-role 消息。

实践建议

在使用带 initial_state / state_prompt 的 agent 时，运行结束后检查 memory.get() 中用户轮次的内容，确认没有被状态前缀替换。
对依赖干净用户原话的链路（分析统计、会话恢复、审计）保持额外警惕，因为一旦被就地修改，这些下游拿到的都是被污染的数据。
在官方合并修复前，可参考 issue 中给出的副本构建思路，或关注 PR #23242 的进展；引用时注意这属于社区结论，而非官方已确认修复。
如果现有代码依赖「后续步骤只看到第一个状态」的旧行为，在切换到副本方案前需要评估这一步语义变化，据 PR 评论，新方案会让每一步都看到当前状态。
提交相关修复时，按维护者意见需要同时补充回归测试。

FAQ

问：这个 issue 现在的状态是什么？ 答：状态为 open，无标签，关闭时间为无，关闭原因为无，反应合计 0，最后更新于 2026-10-01。末条实质评论仍在讨论 PR #23242，官方尚未合入修复。 问：根因具体在哪一行？ 答：据 issue 描述，在 BaseWorkflowAgent.setup_agent 中，block.text = self.state_prompt.format(...) 就地修改了 llm_input[-1]；而 ChatMemoryBuffer.get() 返回的是 store 中持有的同一批对象，因此修改被持久化。 问：为什么换成 SQL Memory 就看不到问题？ 答：据 issue 讨论，SQL Memory 不会把被修改的对象写回。但 agent 默认使用 ChatMemoryBuffer，所以这只是一种规避，并没有修复根因。 问：PR #23242 改了什么？ 答：据该 PR 相关评论，它格式化最后一条用户消息的副本而非就地编辑，内存因此保留原始文本；AgentWorkflow.setup_agent 中的相同代码也一并修改。它还会回溯 llm_input 查找最后一条 user-role 消息，而不是假设固定位置。 问：应用这个方向后行为上有什么变化？ 答：据 PR 评论，旧实现下后续步骤只看到第一个状态（旧文本被存进了内存），新实现下每一步都会看到当前状态。这一语义差异需要在升级前评估。