Session 10: agent runtime — making the loop run reliably
前面几篇讨论了 Tool、Planning、Reflection、Workflow 和 Multi-Agent。这些内容主要回答:Agent 如何调用工具、安排步骤、检查结果,以及让多个 Agent 分工合作。
当 Agent 真正进入应用环境,还会遇到一批更偏工程的问题:某个节点一直不返回怎么办?运行到一半进程崩溃怎么办?模型生成的代码能不能直接在主程序所在的机器执行?用户要求取消任务时,怎样停止正在运行的工作?这些问题很难只靠提示词解决,需要程序和运行环境提供相应能力。
这一层可以统称为 Agent Runtime。这里以 LangGraph 为主线,说明它能处理什么,以及哪些事情仍然需要应用程序或基础设施负责。
1. 先分清 Graph、State、Checkpointer 和 Runtime
继续使用 Research Agent 作为例子。用户输入一个研究主题,系统搜索资料、分析证据、必要时再次搜索,最后生成研究报告。
在 LangGraph 中,可以先这样理解各个概念:
- Graph:描述节点之间的执行关系,以及条件分支和循环。
- Node:执行一项具体工作,例如调用 LLM、搜索网页或生成报告。
- State:在节点之间传递的工作流数据,例如研究主题、搜索结果、报告草稿和错误信息。
- Checkpointer:把 Graph 的状态保存为检查点,支持中断后恢复、查看历史状态等能力。
- Runtime 及外围基础设施:还包括任务调度、超时取消、权限、隔离、日志、资源限制等。LangGraph 能覆盖其中一部分,但不等于完整的操作系统级运行环境。
一个最小的图可以这样写:
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,例如数据库支持的实现。
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 错误,重复调用通常没有意义;如果搜索结果为空,这也未必是程序异常,可能需要改写查询词或提示证据不足。
要区分三类情况:
- 暂时性技术错误:网络波动、服务端 5xx,适合有限次数重试,并采用退避等待。
- 不可重试的错误:参数错误、权限不足、认证失败,应尽早返回清晰错误。
- 业务结果不理想:没有找到足够证据。这通常不应该靠抛异常重试,而应由 Workflow 的条件分支决定下一步,例如改写查询、切换来源或请求人工介入。
较新版本的 LangGraph 支持节点级 retry policy;具体可用的参数与行为取决于所安装的版本。下面展示重试策略的基本形式:
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 超时机制替代操作系统级隔离。
概念示例:
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 里。
一个审批流程的概念示例:
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,可以按下面的思路组织:
- Graph 定义搜索、分析、证据检查和报告生成流程。
- State 保存主题、资料、分析结果、错误和报告草稿。
- Checkpointer 保存工作流进度,支持中断和恢复。
- 节点级重试与超时处理暂时性技术问题。
- Workflow 分支处理证据不足等业务问题。
- 对发布、删除等有外部影响的操作使用审批节点。
- 对不可信代码使用独立沙箱;不要把它直接运行在主服务进程中。
- 通过日志与追踪记录模型调用、工具执行、成本和错误。
- 对外部写操作使用幂等键或去重机制,避免恢复执行时产生重复副作用。
这些能力可以逐步增加,不需要在第一个 Demo 里一次全部实现。学习时先用内存 State 跑通 Graph,再加入 checkpointer,然后逐步加入失败处理、审批、监控和安全隔离。
9. 业界方案简单看
- LangGraph:适合定义 Agent 工作流、状态流转、条件分支、检查点与人工介入。部分节点级超时和错误处理能力与版本有关,使用前应查看对应版本的官方文档。
- LangSmith:可用于 LangGraph/LLM 应用的追踪、调试和评估,帮助还原执行过程。
- Docker 或专用代码沙箱:适合隔离运行 Agent 生成或用户提交的代码;容器配置仍需认真限制权限、网络、文件系统和资源。
- 任务队列与 Worker:长时间任务或大量并发任务,可以由队列把工作分配给独立 Worker,减少 Web 请求进程被长任务占用的问题。
- 数据库与可观测性平台:分别用于持久化业务数据、任务元数据、日志、指标和告警。
选择方案时先看真正需要什么。如果只是一个短流程的内部工具,LangGraph 加上基本日志和 API 超时可能已经足够;如果需要执行不可信代码、运行很长时间或承载大量并发,就必须进一步建设沙箱、队列、持久化存储和监控能力。
小结
Agent Runtime 关注的是执行过程能否被管理:任务能否按预期运行、失败后能否恢复、权限是否受控、资源是否有限,以及出了问题能否查清原因。
LangGraph 能把工作流和状态管理讲得很清楚,也提供检查点、恢复和部分容错能力;但它并不自动替代沙箱、操作系统权限、任务队列和完整的可观测性平台。真正的工程实现,需要把图编排与外围运行基础设施配合起来。