Agent 随笔：循环、上下文与多工具协作

这段时间反复遇到一个现象：大家都会说 Agent、RAG、工作流和工具调用，但把它们放进一个持续运行的系统后，边界往往并不清楚。下面从几个容易混在一起的概念开始，把问题落回工程实现。

LangGraph 是什么样的东西

LangGraph 可以理解为面向有状态 Agent 的图执行框架。它不替模型做推理，而是把“当前状态、执行节点、下一步迁移、暂停与恢复”作为显式对象。节点可以调用模型，也可以是普通代码、检索器、工具或完整 Agent；边可以固定，也可以按状态条件跳转。

它特别适合有稳定阶段的流程：先分类、再检索、然后生成、最后验证或审批。图并不是让系统失去灵活性，而是在高风险处减少模型的自由度。一个节点内部仍可以是开放的 Agent loop，图负责规定它何时能被调用、输出如何被验证、何时必须转交人。

ReAct、Agent Harness 与 Agent Loop

ReAct 是一种行为模式：模型先形成推理，再调用工具，读取观察结果，继续推理。它描述的是一次连续任务里模型与工具交替的节奏。

Agent loop 是把这一节奏写成真正的控制循环，包含停止条件、重试、预算、状态更新和错误处理。它不一定使用 ReAct，但现代工具型 Agent 多数都近似这个形态。

Harness 则更大一层。它是 Agent 的运行环境：系统指令、技能、工具注册、文件系统、沙箱、权限、记忆、子 Agent、钩子、日志和评测都在其中。ReAct 是循环中的一段认知动作；loop 是任务推进机制；Harness 是让循环能安全而稳定运行的整套基础设施。

RAG 与文件系统不是替代关系

RAG 擅长从大量资料中按语义召回少量相关片段，再送入上下文。它适合“我不知道答案在哪份文档里”的问题。文件系统擅长保存原始材料、结构化状态、中间产物、日志、代码和版本历史。它适合“这个任务已经做到了哪里”“完整证据在哪里”“下次谁来接手”。

RAG 可以把文件系统、对象存储或知识库当作数据源，但不能替代它们。向量索引不适合保存唯一事实、审批记录或可执行计划；Agent 也不应每次通过检索猜测自己上轮是否已经部署。任务状态应存为明确字段，长文档和日志保留原件，检索只负责把相关内容带回当前工作集。

在 LangGraph 中实现一个可控循环

下面的形状把工具执行、验证和重试写成图的一部分。重点是：模型无法直接结束任务，必须经过验证节点。

from typing import TypedDict
from langgraph.graph import StateGraph, START, END

class State(TypedDict):
    messages: list
    evidence: list[str]
    attempts: int
    verified: bool

def act(state: State):
    result = agent_with_tools(state["messages"])
    return {"messages": state["messages"] + [result], "evidence": result.evidence}

def verify(state: State):
    return {"verified": check_claims(state["messages"], state["evidence"]),
            "attempts": state["attempts"] + 1}

def route(state: State):
    if state["verified"]: return END
    if state["attempts"] >= 3: return "human"
    return "act"

g = StateGraph(State)
g.add_node("act", act); g.add_node("verify", verify); g.add_node("human", request_review)
g.add_edge(START, "act"); g.add_edge("act", "verify")
g.add_conditional_edges("verify", route)
app = g.compile()

循环必须有上限和副作用边界。检索失败可以重试，创建工单、转账、删除数据则应先进入审批节点；所有写操作都需要幂等键，避免恢复后重复执行。

三天任务怎样管理上下文

三天三夜不是把同一聊天窗口撑到极限。应把任务拆成多个短周期，每个周期结束时写入交接包，再由新上下文读取。交接包包含目标、非目标、当前计划、已经完成的步骤、失败尝试、关键决策、工作区或分支、artifact 指针、剩余风险与下一步命令。

Agent 上下文通常包括：系统与安全约束、用户目标、当前计划、相关代码或文档片段、工具 schema、最近工具结果、外部事实、预算与权限状态。它既需要结构化也需要非结构化。任务 ID、阶段、重试数、审批、资源地址和证据索引用 JSON 或状态 schema；设计解释、用户需求、文档片段和最终叙述保留文本。把两类信息混在一长串聊天消息里，会让恢复、过滤与校验都变得困难。

多工具的顺序性与准确性

工具调用不是“模型选中了就一定正确”。先用任务计划或图明确依赖：必须先读取订单，再计算退款，再提交审批；能并行的检索才并行。每个工具的输入与输出应有严格 schema、资源作用域和权限层级；结果带 request_id、版本和时间戳，汇聚器按显式顺序合并，而不是按返回先后拼接。

results = await gather_named([fetch_profile(user_id), fetch_orders(user_id)])
profile, orders = results["profile"], results["orders"]
assert profile.user_id == user_id
assert all(order.user_id == user_id for order in orders)
answer = compose(profile, sorted(orders, key=lambda item: item.created_at))

防止误调用还需要三道线：路由前的意图分类与 allowlist，调用前的参数校验和权限检查，调用后的事实校验与独立评估。模型只负责提出候选行动；系统负责保证候选行动合法、结果可追溯，并且不会因为一次自信的误判改变外部世界。

交接包应该怎样落盘

长任务最怕的不是上下文窗口到头，而是任务状态只存在于模型的临时叙述里。一个可恢复的交接包需要同时有面向机器的字段和面向人的短说明。机器字段负责恢复状态与防重复执行；文字负责保留做出某个取舍的原因。

{
  "run_id": "migration-20260823-03",
  "phase": "validate_backfill",
  "goal": "迁移订单索引，不改变读路径行为",
  "worktree": "agent/migration-index",
  "commit": "7c1b0d2",
  "completed": ["schema 已创建", "回填脚本已在 staging 验证"],
  "next_actions": ["运行 1% 流量对比", "检查延迟与缺失率"],
  "blocked_by": null,
  "idempotency_keys": ["backfill:2026-08-23"],
  "artifacts": [".agent/evidence/staging-compare.json"]
}

每一次上下文重置前，Harness 应验证交接包完整：目标、完成条件、当前提交、下一步、风险和 artifact 缺一不可。下一轮先读取交接包和 Git diff，再决定是否需要检索旧日志。这样即使模型、会话甚至执行机器发生变化，任务仍有连续的事实链。

工具结果的“顺序”有两层含义

第一层是因果顺序：有依赖的操作不能颠倒。先创建资源再写入、先拿到用户权限再读取数据、先验证预览再发布，都应该由图边、事务或工作流引擎表达，不能只期待模型记住。第二层是展示顺序：多个并行读取工具完成时间不同，但最终回答需要按时间、优先级或用户指定顺序组织。此时以业务排序字段为准，绝不能以异步返回的先后为准。

对会产生副作用的工具还应使用幂等键、乐观版本号与补偿动作。比如发送通知时，把 task_id + recipient + template_version 作为去重键；更新同一资源时携带 expected_version，版本不一致就重新读取；批量操作失败时记录已完成项，以便精确重试而不是整批再跑。工具本身返回的应是结构化事实而非自然语言评价，便于之后的节点验证。

准确不是单一模型分数

“答案准确”至少包含四层：检索到的材料是否相关，工具返回的数据是否属于正确对象，推理是否忠实于证据，最终动作是否符合权限与业务规则。四层需要不同检查。检索看召回与引用覆盖；数据看 schema、主键和版本；推理看断言能否逐项追溯；动作看策略引擎、审批和执行日志。

因此一个成熟 Agent 的最终回复最好附带内部可读的证据图：哪些结论来自哪项工具调用，哪些未能确认，哪些动作没有执行。用户界面可以保持简洁，但系统必须知道“我为什么这样说”。这也是 Agent 从聊天体验走向可靠软件的分水岭。

把这些边界设计清楚后，Agent 才能既保留模型在探索上的优势，又把关键动作放进可验证、可恢复、可审计的工程轨道。

真正值得自动化的不是“让模型替人拍板”，而是让每一次判断都留下输入、证据、约束与结果。这样即使需要人接管，也不是从一段模糊对话重新猜起，而是接过一份状态清楚、边界明确的工程任务。