Session 10: agent runtime — making the loop run reliably

前面几篇讨论了 Tool、Planning、Reflection、Workflow 和 Multi-Agent。这些内容主要回答:Agent 如何调用工具、安排步骤、检查结果,以及让多个 Agent 分工合作。

Originally in ChineseThis article was written in Chinese. The body below is the Chinese original; the English translation is not available yet.

当 Agent 真正进入应用环境,还会遇到一批更偏工程的问题:某个节点一直不返回怎么办?运行到一半进程崩溃怎么办?模型生成的代码能不能直接在主程序所在的机器执行?用户要求取消任务时,怎样停止正在运行的工作?这些问题很难只靠提示词解决,需要程序和运行环境提供相应能力。

这一层可以统称为 Agent Runtime。这里以 LangGraph 为主线,说明它能处理什么,以及哪些事情仍然需要应用程序或基础设施负责。

1. 先分清 Graph、State、Checkpointer 和 Runtime

继续使用 Research Agent 作为例子。用户输入一个研究主题,系统搜索资料、分析证据、必要时再次搜索,最后生成研究报告。

在 LangGraph 中,可以先这样理解各个概念:

  • Graph:描述节点之间的执行关系,以及条件分支和循环。
  • Node:执行一项具体工作,例如调用 LLM、搜索网页或生成报告。
  • State:在节点之间传递的工作流数据,例如研究主题、搜索结果、报告草稿和错误信息。
  • Checkpointer:把 Graph 的状态保存为检查点,支持中断后恢复、查看历史状态等能力。
  • Runtime 及外围基础设施:还包括任务调度、超时取消、权限、隔离、日志、资源限制等。LangGraph 能覆盖其中一部分,但不等于完整的操作系统级运行环境。

一个最小的图可以这样写:

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

class ResearchState(TypedDict):
    topic: str
    sources: list[str]
    report: str

def search(state: ResearchState):
    # 实际项目中接入搜索服务
    return {"sources": [f"关于 {state['topic']} 的资料 A"]}

def write_report(state: ResearchState):
    # 实际项目中在这里调用 LLM
    sources = "\n".join(state["sources"])
    return {"report": f"主题:{state['topic']}\n参考资料:\n{sources}"}

builder = StateGraph(ResearchState)
builder.add_node("search", search)
builder.add_node("write_report", write_report)
builder.add_edge(START, "search")
builder.add_edge("search", "write_report")
builder.add_edge("write_report", END)
graph = builder.compile()

result = graph.invoke({"topic": "Agent Runtime", "sources": [], "report": ""})
print(result["report"])

这段代码展示了流程和状态,但还没有提供持久化、超时、权限隔离等能力。Graph 能描述任务怎么走,并不意味着所有运行保障都会自动出现。

2. 持久化与恢复:任务中断后从哪里继续?

假设 Research Agent 已经完成网页搜索和资料分析,正在写报告时服务进程崩溃。如果状态只存在 Python 内存中,重启后就没有可靠的进度可以恢复。

LangGraph 的 checkpointer 可以保存图状态检查点。使用时需要给每次工作流实例一个 thread_id,以便之后找到相应状态。开发时可以使用内存检查点;需要跨进程、重启后保留进度时,应使用合适的持久化 checkpointer,例如数据库支持的实现。

python
from langgraph.checkpoint.memory import InMemorySaver

checkpointer = InMemorySaver()
graph = builder.compile(checkpointer=checkpointer)

config = {"configurable": {"thread_id": "research-001"}}
result = graph.invoke(
    {"topic": "Agent Runtime", "sources": [], "report": ""},
    config=config,
)

# 同一个 thread_id 用于读取或继续这条工作流的状态
snapshot = graph.get_state(config)
print(snapshot.values)

InMemorySaver 适合演示,不适合把它当作生产环境的持久化存储。进程退出后,内存内容也会消失。实际部署时要根据运行环境选择持久化实现,并明确检查点的保留策略。

这里还要区分两个概念:

  • Checkpointer 保存当前工作流执行过程中的 State,主要用于恢复某条运行线程。
  • 长期 Store 或业务数据库 保存跨任务需要复用的数据,例如用户偏好、研究资料索引、任务元数据。

检查点也不等于把每个外部副作用自动撤销或重放得毫无风险。比如某个节点已经发送邮件,随后进程崩溃;恢复时如果重新执行这个节点,可能再次发送。对写文件、发邮件、扣费、提交外部任务等操作,要设计幂等键、去重记录或事务机制。

3. 节点失败:重试、错误处理和业务补救

搜索服务偶尔返回 503,可能只是暂时性故障,可以重试;如果 API Key 错误,重复调用通常没有意义;如果搜索结果为空,这也未必是程序异常,可能需要改写查询词或提示证据不足。

要区分三类情况:

  1. 暂时性技术错误:网络波动、服务端 5xx,适合有限次数重试,并采用退避等待。
  2. 不可重试的错误:参数错误、权限不足、认证失败,应尽早返回清晰错误。
  3. 业务结果不理想:没有找到足够证据。这通常不应该靠抛异常重试,而应由 Workflow 的条件分支决定下一步,例如改写查询、切换来源或请求人工介入。

较新版本的 LangGraph 支持节点级 retry policy;具体可用的参数与行为取决于所安装的版本。下面展示重试策略的基本形式:

python
from langgraph.types import RetryPolicy

builder.add_node(
    "search",
    search,
    retry_policy=RetryPolicy(max_attempts=3),
)

这里假设 search 会在真正的技术失败时抛出异常。若它只是返回空列表,LangGraph 会把这视为正常返回;是否再次搜索,应由图中的业务逻辑决定。

生产代码还需要考虑:重试是否会造成重复副作用、哪些异常值得重试、重试间隔多长,以及多次失败后如何记录原因。不要对所有异常无限重试。

4. 超时与取消:让任务能够停止

工具调用或 LLM 请求可能一直等待。通常至少要考虑三种限制:

  • 单次外部调用的超时,例如搜索 API 最多等待 20 秒。
  • 单个节点的运行时限,避免一个步骤长期占用执行资源。
  • 整个任务的总预算,例如最多运行 10 分钟、最多执行一定数量的模型和工具调用。

LangGraph 新版本提供节点级 timeout 能力,但官方文档注明,节点超时支持依赖版本,并且目前针对异步节点;同步阻塞代码不能简单地在同一个进程中被安全强制终止。对于阻塞 I/O,可以考虑异步客户端或在线程中执行;对于不可信、可能死循环的任意代码,应该使用独立进程或沙箱,而不是指望 Graph 超时机制替代操作系统级隔离。

概念示例:

python
import asyncio
from langgraph.graph import StateGraph, START, END

async def search_async(state: ResearchState):
    # 示例:实际代码应调用支持超时的异步搜索客户端
    await asyncio.sleep(0.1)
    return {"sources": [f"关于 {state['topic']} 的资料 A"]}

# 在支持节点级 timeout 的 LangGraph 版本中,
# 可在 add_node 时配置 timeout;请按当前安装版本核对 API。
# builder.add_node("search", search_async, timeout=20)

这段代码刻意把具体 timeout 配置留作版本相关示例,避免在不同版本之间误用参数。真正的系统应同时设置 HTTP 客户端超时、模型请求超时和任务级预算。

取消也需要区分“标记任务取消”和“实际停止底层工作”。如果只是把 State 里的 cancelled=True,但网络请求或子进程仍在运行,资源并不会自动释放。执行层需要把取消信号传给异步任务、HTTP 请求、线程或子进程,并检查任务是否真的结束。

5. 权限与执行隔离:不要让模型直接拥有机器权限

如果 Agent 只调用几个固定的搜索和数据库查询工具,程序可以在每个工具里检查参数与权限。如果 Agent 可以生成并执行任意 Python、Shell 命令,就需要更严格的隔离。

常见防护方式包括:

  • 工具白名单:只注册业务允许的工具,避免任意调用系统命令。
  • 最小权限:工具只拿到完成任务所需的凭证和数据权限。
  • 路径和参数校验:限制文件读写目录,校验 URL、SQL 和命令参数。
  • 人工审批:发送邮件、发布文章、删除数据等有外部影响的操作,可以先暂停等待用户批准。
  • 独立进程或沙箱:运行不可信代码时,限制文件系统、网络、CPU、内存和运行时长。

LangGraph 可以通过节点、条件路由和 interrupt 等机制组织审批流程,但它本身不会自动把任意 Python 代码放进安全沙箱。权限必须在真正执行操作的边界上验证,不能只写在 System Prompt 里。

一个审批流程的概念示例:

python
from langgraph.types import interrupt

def publish_article(state):
    approval = interrupt({
        "action": "publish_article",
        "title": state["title"],
        "message": "请确认是否发布这篇文章",
    })

    if not approval.get("approved"):
        return {"publish_status": "rejected"}

    # 只有收到明确批准后,才调用真正的发布 API
    publish_to_platform(state["draft"])
    return {"publish_status": "published"}

这只是流程结构示例。实际使用 interrupt 时,需要编译图时配置 checkpointer,并按 LangGraph 的恢复方式重新调用工作流;恢复后还要验证审批数据。更重要的是,发布 API 本身仍应有鉴权、输入校验和幂等处理。

6. 日志与追踪:还原一次 Agent 到底做了什么

多 Agent 执行时,用户可能只看到最后的报告,却不知道中间发生了什么:调用了哪个模型、搜索了哪些来源、哪次工具失败、花了多少时间和 Token、某个子 Agent 为什么没有返回结果。

建议每次任务至少记录:

  • run_id、thread_id 和任务标识。
  • 节点名称、开始和结束时间、执行状态。
  • LLM 模型名称、请求耗时、Token 用量和异常摘要。
  • 工具名称、经过脱敏的参数、结果状态和耗时。
  • 重试次数、失败原因、最终恢复方式。

LangGraph 可以和 LangSmith 等追踪工具配合,观察图中的节点执行和模型调用。也可以把应用日志发送到已有的日志与指标平台。注意不要无差别记录 API Key、用户隐私、完整敏感文档或其他秘密信息;日志也需要脱敏和访问控制。

7. 并发调度:多个节点同时运行时会发生什么?

Multi-Agent 经常会让多个研究任务并行执行。例如分别研究三个方案,再把结果交给汇总节点。LangGraph 可以通过图中的并行分支表达这类流程,并在后续节点汇总结果。

不过并发会带来一些熟悉的工程问题:

  • 并发数量过大,可能耗尽模型 API 配额或搜索服务限额。
  • 多个节点同时更新同一份 State,需要定义明确的合并规则。
  • 一个分支失败时,其他分支可能已经完成,恢复时要避免不必要的重复工作。
  • 外部副作用不能假设会因为图恢复而自动只执行一次。

并行执行不等于无限制执行。应设置并发上限、超时、重试预算和错误汇总规则。对需要累积多个节点结果的 State 字段,应按 LangGraph 的 reducer 机制定义合并方式,避免多个并行节点写入同一个字段时发生更新冲突。

8. 把这些能力组合起来

一个面向实际使用的 Research Agent,可以按下面的思路组织:

  1. Graph 定义搜索、分析、证据检查和报告生成流程。
  2. State 保存主题、资料、分析结果、错误和报告草稿。
  3. Checkpointer 保存工作流进度,支持中断和恢复。
  4. 节点级重试与超时处理暂时性技术问题。
  5. Workflow 分支处理证据不足等业务问题。
  6. 对发布、删除等有外部影响的操作使用审批节点。
  7. 对不可信代码使用独立沙箱;不要把它直接运行在主服务进程中。
  8. 通过日志与追踪记录模型调用、工具执行、成本和错误。
  9. 对外部写操作使用幂等键或去重机制,避免恢复执行时产生重复副作用。

这些能力可以逐步增加,不需要在第一个 Demo 里一次全部实现。学习时先用内存 State 跑通 Graph,再加入 checkpointer,然后逐步加入失败处理、审批、监控和安全隔离。

9. 业界方案简单看

  • LangGraph:适合定义 Agent 工作流、状态流转、条件分支、检查点与人工介入。部分节点级超时和错误处理能力与版本有关,使用前应查看对应版本的官方文档。
  • LangSmith:可用于 LangGraph/LLM 应用的追踪、调试和评估,帮助还原执行过程。
  • Docker 或专用代码沙箱:适合隔离运行 Agent 生成或用户提交的代码;容器配置仍需认真限制权限、网络、文件系统和资源。
  • 任务队列与 Worker:长时间任务或大量并发任务,可以由队列把工作分配给独立 Worker,减少 Web 请求进程被长任务占用的问题。
  • 数据库与可观测性平台:分别用于持久化业务数据、任务元数据、日志、指标和告警。

选择方案时先看真正需要什么。如果只是一个短流程的内部工具,LangGraph 加上基本日志和 API 超时可能已经足够;如果需要执行不可信代码、运行很长时间或承载大量并发,就必须进一步建设沙箱、队列、持久化存储和监控能力。

小结

Agent Runtime 关注的是执行过程能否被管理:任务能否按预期运行、失败后能否恢复、权限是否受控、资源是否有限,以及出了问题能否查清原因。

LangGraph 能把工作流和状态管理讲得很清楚,也提供检查点、恢复和部分容错能力;但它并不自动替代沙箱、操作系统权限、任务队列和完整的可观测性平台。真正的工程实现,需要把图编排与外围运行基础设施配合起来。

On this page