Session 22:Agent Deployment——Agent 的部署与运行架构
Agent 在本地跑通,只能说明基本功能可用。真正部署到生产环境,还需要考虑请求如何进入系统、任务执行多久、模型调用如何管理、多个用户如何共享资源,以及服务异常后怎样恢复。
传统 Web 应用通常是接收请求、执行业务逻辑、返回结果。Agent 的执行过程可能持续几十秒甚至几分钟,中间还会调用 LLM、访问外部 API、执行多个 Tool,甚至等待人工确认。如果仍然按照普通接口的思路处理所有任务,容易遇到请求超时、资源占用、重复执行和状态丢失等问题。
这一节主要记录 Agent 的部署架构、任务执行模式、并发控制、状态恢复,以及 LangGraph 在生产环境中的应用。
1. Agent 的整体部署架构
一个常见的生产架构可以拆成几个部分:
用户 / 前端
|
v
API Gateway
|
v
Python API 服务
/ \
/ \
短任务直接执行 长任务进入队列
| |
v v
Agent Runtime Message Queue
| |
| v
| Agent Worker
| |
+--------+---------+
|
+--------+---------+
| | |
v v v
LLM Tools 数据服务
|
v
外部 API / 数据库
持久化:业务数据库 / Checkpoint 存储
监控:日志 / Tracing / Metrics
这是一种常见的架构组合,不要求所有系统一开始就部署这么多组件。小型 Agent 可以先使用一个 Python 服务完成 API 接入和任务执行,等任务量、执行时间和可用性要求提高后,再拆分 Worker、任务队列和独立的运行环境。
几个组件的职责需要明确:
| 组件 | 主要职责 |
|---|---|
| API 服务 | 接收请求、鉴权、参数校验、创建任务、返回结果或任务 ID |
| Agent Runtime | 执行 Agent 工作流、管理模型调用、Tool 调用和状态流转 |
| Worker | 在后台执行耗时任务,支持独立扩缩容 |
| Message Queue | 缓冲任务、分发工作、解耦请求接入和任务执行 |
| 业务数据库 | 保存用户、业务实体和最终业务结果 |
| Checkpoint 存储 | 保存 Agent 工作流的执行状态,支持恢复与中断续跑 |
| 监控系统 | 记录执行过程、调用耗时、Token 消耗、错误和任务结果 |
需要注意,Checkpoint 不等于业务数据库,也不等于任务队列。三者解决的是不同问题:队列负责分发任务,Checkpoint 保存图执行状态,业务数据库负责业务数据的持久化。
2. 同步执行与异步执行
Agent 部署时首先要确定:用户发起任务后,HTTP 请求应该一直等待 Agent 完成,还是先返回一个任务 ID?
2.1 同步执行
流程比较简单:
客户端
|
| POST /agent/run
v
API 服务
|
| 执行 Agent
v
LLM / Tools / 数据库
|
| 任务完成
v
返回最终结果
示例:
from fastapi import FastAPIapp = FastAPI()@app.post("/agent/run")async def run_agent(request: dict): result = await agent.ainvoke({ "topic": request["topic"] }) return {"result": result}
这段代码展示了同步 HTTP 接口等待 Agent 执行完成的基本方式。这里使用 await 并不意味着 Agent 运行在独立的后台任务中,只是异步等待执行结果。
同步执行适合耗时较短、结果需要立即返回、执行步骤相对可控的任务。例如,简单分类、问题改写、短文本总结。
它的优点是实现简单,不需要额外的任务队列,调用方也容易理解。但任务越长,请求就越容易受到客户端超时、反向代理超时和连接资源限制的影响。
即使 Python 使用异步框架,长任务仍然需要占用相关的运行资源。异步可以改善 I/O 等待期间的资源利用率,却不能消除模型调用时间,也不能让无限长的任务变得可控。
2.2 异步任务执行
如果任务需要多轮模型调用、长时间搜索、处理大量文档,或者可能等待人工确认,更适合考虑后台执行。
流程如下:
客户端
|
| POST /agent/tasks
v
API 服务
|
| 创建任务并提交队列
v
返回 task_id
|
| Worker
| |
| v
| 执行 Agent
| |
| v
| 保存执行结果
|
| GET /agent/tasks/{id}
v
查询任务状态与结果
API 可以很快返回:
{
"task_id": "task_123",
"status": "queued"
}
客户端之后查询任务状态:
{
"task_id": "task_123",
"status": "running"
}
任务完成后再读取结果。
后台执行适合研究报告生成、批量文档处理、复杂数据分析以及需要人工审批的 Agent 任务。API 服务可以快速释放请求连接,Worker 则专门负责执行任务。
但引入队列后也会带来新的问题,例如重复投递、任务积压、失败重试和状态一致性。队列并不会自动保证 Agent 任务只执行一次,因此业务层仍然需要设计任务 ID、幂等策略和执行状态管理。
2.3 流式输出
还有一种情况:用户希望立即看到 Agent 的执行过程,但又不想等到任务完全结束。
例如 Research Agent 可以逐步显示:
正在分析研究主题
↓
正在搜索资料
↓
已找到 8 篇相关资料
↓
正在检查证据覆盖情况
↓
正在生成研究报告
这里可以使用 SSE、WebSocket,或者框架提供的流式接口。
SSE 适合服务器持续向客户端推送任务状态和文本内容;WebSocket 适合需要双向实时通信的场景。两者都可以承载进度更新,但本身不负责任务持久化和故障恢复。
如果任务运行时间较长,比较稳妥的组合是:
- 后台 Worker 执行 Agent;
- 数据库或任务存储记录任务状态;
- SSE 或 WebSocket 向前端推送进度;
- 客户端断开后,可以重新连接并查询当前状态。
这样,浏览器断开连接不会必然导致后台任务被取消。
3. 为什么长任务需要独立 Worker
如果所有 Agent 任务都由 API 服务直接执行,任务量增加后,API 服务可能同时承担请求接入、模型调用、文档处理和后台执行等工作。
例如,用户同时提交 100 个研究任务,每个任务都需要调用多个外部 API 和模型。即使大部分时间花在等待网络响应,任务也会占用连接、状态对象、队列位置和其他运行资源。如果部分步骤涉及 CPU 密集型文档解析,还可能影响其他请求的响应。
将 Worker 独立出来,可以把接入和执行分开:
- API 服务主要负责快速接收请求和返回响应;
- Worker 负责执行 Agent 工作流;
- 任务队列负责缓冲流量并分发任务;
- Worker 可以按照任务积压和资源使用情况独立扩容。
对于不同类型的任务,也可以配置不同的 Worker。例如,轻量查询和长篇研究报告使用不同的队列,避免耗时较长的任务阻塞简单任务。
不过,Worker 并不是越多越好。Agent 的执行速度还受模型服务商的并发限制、Tool 的速率限制、数据库连接池和系统预算约束。如果无限增加 Worker,只会把排队问题转移到模型 API 或其他下游服务。
4. Agent 的并发控制
传统 Web 应用常常通过线程池、连接池和服务器实例数控制并发。Agent 也需要这些措施,但还需要额外控制模型调用、Tool 调用和任务执行预算。
4.1 限制同时运行的任务数
假设部署了 4 个 Worker,每个 Worker 最多同时执行 5 个任务,那么系统最多允许 20 个任务同时运行。这个数字只是任务并发上限,并不代表系统一定能稳定支撑 20 个任务。
如果每个任务平均会调用 6 次 LLM,理论上还需要考虑任务执行期间产生的模型请求量,以及这些请求是否会集中发生。
因此,需要区分:
- Agent 任务并发数;
- LLM 请求并发数;
- Tool 请求并发数;
- 数据库连接数;
- 每秒请求数和每分钟 Token 配额。
这些指标之间有关联,但不能直接互相替代。
4.2 控制模型 API 的并发
模型服务商通常会设置请求速率、Token 速率或其他使用限额。如果 Agent 任务并发增加,每个任务又会产生多次模型调用,就可能很快触发限流。
可以在 Model Client 层统一管理:
- 请求并发上限;
- 请求超时;
- 429 限流处理;
- 指数退避与抖动;
- 重试次数;
- 输入与输出 Token 预算;
- 备用模型或降级策略。
例如,多个 Worker 可以共用一个集中式限流器,而不是每个 Worker 都独立允许同样的并发量。否则,Worker 数量增加后,整体请求量可能超过服务商的限额。
4.3 区分 I/O 密集型与 CPU 密集型工作
Agent 的很多步骤是 I/O 密集型的,例如等待 LLM 返回、访问网页和调用数据库。这些步骤可以使用异步 I/O 提高资源利用率。
但文档解析、图像处理、复杂计算等任务可能是 CPU 密集型的。如果直接在事件循环中执行大量同步计算,就可能阻塞其他协程。
实际项目中可以把这类工作交给线程池、进程池或独立的计算 Worker,具体取决于任务性质和使用的库。
部署时不能仅仅因为使用了 FastAPI 和 async def,就认为所有任务都具备良好的并发能力。
5. Agent 状态持久化与故障恢复
Agent 运行到一半时,服务可能重启、Worker 进程可能崩溃,外部 API 也可能超时。如果任务状态只保存在进程内存中,进程退出后就可能丢失。
这也是为什么生产环境需要区分业务数据、任务状态和图执行状态。
5.1 保存任务状态
可以为每个任务维护基本信息:
task = { "task_id": "task_123", "status": "running", "user_id": "user_456", "created_at": "...", "started_at": "...", "finished_at": None, "error": None,}
任务状态可以包括:
queued:等待执行;running:正在执行;waiting_for_human:等待人工确认;completed:执行完成;failed:执行失败;cancelled:已取消。
实际项目还应定义状态转换规则。例如,已完成的任务不能被普通重试操作直接改回运行中;等待人工确认的任务需要能够恢复到正确的执行节点。
5.2 Checkpoint 保存什么
以 LangGraph 为例,Checkpoint 可以保存图执行过程中的状态,使工作流在适当的条件下恢复执行。使用持久化 Checkpointer 时,通常会结合 thread ID 等标识关联同一条执行轨迹。
对于需要跨请求恢复的任务,不能只使用纯内存 Checkpointer。生产环境需要选择适合部署形态的持久化后端,并考虑连接管理、保留期限和数据安全。
还要注意:Checkpoint 保存了 Agent 状态,不代表所有外部操作都能自动回滚。
假设 Agent 已经调用邮件服务成功发送邮件,但在保存下一次 Checkpoint 前进程崩溃。恢复后,如果工作流重新执行发送邮件节点,就可能发送第二封邮件。
因此,对于付款、发邮件、创建工单等有副作用的操作,需要结合幂等键、外部执行记录和状态查询来处理。Checkpoint 能帮助恢复工作流,但不能替代业务事务和幂等机制。
5.3 人工确认与恢复
如果 Agent 执行到需要人工确认的节点,可以暂停工作流,保存状态,并向用户或运营人员展示待确认事项。
人工确认完成后,再根据保存的状态继续执行。这种方式适合审批、报告发布、外部系统写入等场景。
部署时需要额外考虑:
- 谁可以查看和确认任务;
- 等待期间状态保存在哪里;
- 人工确认后如何重新调度任务;
- 等待超时后如何处理;
- 用户重复提交确认请求时如何避免重复执行。
这类流程更适合使用明确的任务状态和持久化机制管理,而不是让一个 HTTP 请求一直等待人工操作。
6. LangGraph Agent 的部署方式
LangGraph 主要负责工作流的状态管理、节点执行、分支、循环和中断等机制。它不意味着应用自动拥有完整的任务队列、服务治理和部署基础设施。
常见的部署方式有三种。
6.1 将 LangGraph 集成到自己的 Python 服务
适合早期项目和结构比较简单的应用。使用 FastAPI 暴露接口,在服务内部调用图:
from fastapi import FastAPIfrom langgraph.graph import StateGraphapp = FastAPI()# graph 是已经构建好的 LangGraph 编译结果@app.post("/research")async def research(request: dict): result = await graph.ainvoke({ "topic": request["topic"] }) return result
这是一个简化示例。生产代码还需要补充输入校验、鉴权、异常处理、任务超时和结果格式控制。
如果任务耗时短,这种方式很方便。等到任务需要后台执行时,可以把 graph.ainvoke() 的调用放进独立 Worker,API 服务只负责创建任务和返回 ID。
6.2 LangGraph 加任务队列
这种方式由自己的 API 服务、消息队列和 Worker 组成,Worker 负责执行 LangGraph。
适合希望自行控制基础设施、任务调度和运行成本的系统。队列、状态数据库、Checkpoint 存储和监控系统都需要单独配置与维护。
它的优势是架构灵活,能按任务类型扩容;代价是需要自己处理任务投递、重试、状态转换、重复执行和运维等问题。
6.3 使用 LangGraph Platform / Agent Server
LangGraph 生态也提供面向部署与运行的服务化方案,可以协助处理图的运行、持久化、流式交互以及相关 API 等能力,具体功能取决于所使用的产品版本和部署模式。
选择托管或自部署的 Agent Server,可以减少部分基础设施开发工作,但并不代表业务侧不再需要考虑权限、成本预算、业务数据一致性、外部 Tool 的幂等和任务结果的质量控制。
是否采用它,应该结合现有系统、部署环境、运维能力和成本来决定,而不是因为使用了 LangGraph 就必须选择某一种部署方式。
7. 生产环境中的超时、重试和取消
Agent 的执行链路比较长,超时应该按层次设置。
例如:
| 层次 | 需要考虑的限制 |
|---|---|
| HTTP 请求 | 客户端、网关和 API 服务的请求超时 |
| 单次 LLM 调用 | 网络超时、服务商响应时间 |
| 单次 Tool 调用 | 外部 API 超时和连接超时 |
| 单个节点 | 节点执行时间和异常处理 |
| 整个 Agent 任务 | 总执行时长、调用次数、费用预算 |
| 后台队列 | 排队时间、任务过期时间和重试策略 |
不能只设置一个 HTTP 超时,就认为整个 Agent 已经具备超时控制能力。一个任务可能已经在后台执行,而前端连接早已断开;也可能某个 Tool 一直阻塞,导致任务永远无法结束。
对于后台任务,还需要支持取消请求。取消操作要定义清楚:是停止后续步骤,还是尝试取消当前模型请求,还是终止整个任务。某些外部操作一旦提交,就无法真正撤销。
重试也需要分层处理。临时网络错误可以在有限次数内重试;业务参数错误需要修正;不可恢复的错误应进入失败状态或降级路径。对于具有副作用的节点,重试前必须确认是否已经执行成功。
8. 监控与日志
Agent 的故障不一定发生在 API 服务本身。可能是模型超时、Tool 返回异常、Checkpoint 保存失败、任务队列积压,也可能是某个分支不断循环。
因此,监控应该覆盖完整的任务链路。
建议至少记录:
- 任务 ID、用户或租户标识;
- 工作流节点、开始时间、结束时间和执行结果;
- 每次模型调用的模型名称、延迟、输入输出 Token 和错误类型;
- Tool 的名称、调用参数摘要、耗时和返回状态;
- 重试次数、循环次数、任务总耗时;
- 任务队列长度和等待时间;
- Checkpoint 保存、恢复和中断事件;
- 任务最终状态与失败原因。
日志中可能包含用户输入、内部资料或敏感数据,需要控制访问权限,并避免不加区分地记录完整提示词、密钥和个人信息。
通过 Trace 可以把一个任务的多次 LLM 调用和 Tool 调用关联起来。遇到任务特别慢或成本异常时,可以定位具体耗时节点,而不必只看到一个“Agent 请求失败”的错误。
9. 一个适合逐步演进的部署方案
对于从本地开发走向生产的 Research Agent,可以按以下顺序逐步搭建。
第一阶段:单服务运行。 使用 FastAPI 提供接口,直接调用 LangGraph,完成鉴权、输入校验、基础日志、错误处理和运行预算。先确保单次任务的执行链路可靠。
第二阶段:增加持久化。 使用业务数据库保存任务信息,配置持久化 Checkpointer,为长任务、人工确认和故障恢复打好基础。
第三阶段:拆分 Worker。 对长时间运行的任务引入队列和后台 Worker。API 服务快速返回任务 ID,客户端通过查询或流式接口获取进度和结果。
第四阶段:完善运行治理。 根据真实负载增加并发控制、模型限流、队列优先级、任务取消、成本监控和独立扩缩容。
第五阶段:按瓶颈继续拆分。 只有在实际出现资源竞争或独立扩容需求时,再考虑把文档解析、检索、模型调用或其他能力拆成独立服务。
这条路线的重点是逐步增加复杂度。过早引入大量基础设施,会让开发者把时间花在维护系统上;一直维持单进程执行,又可能在长任务和高并发场景下遇到明显限制。
10. 小结
Agent 部署需要重点考虑任务执行时间、运行状态、并发控制、故障恢复和运行监控。短任务可以由 API 服务直接执行;长任务更适合后台 Worker;需要及时反馈进度的任务,可以结合流式输出和持久化状态。
LangGraph 提供工作流执行与状态管理能力,但生产系统仍然需要根据业务情况配置任务队列、数据库、Checkpoint 存储、超时、重试、幂等和监控。
架构不必一开始就很复杂。先明确任务执行模式和状态管理方式,再根据实际瓶颈增加 Worker、队列和运行治理能力,通常更容易控制开发成本,也更容易定位问题。