Session 22: deployment — the runtime architecture of an agent service

Agent 在本地跑通,只能说明基本功能可用。真正部署到生产环境,还需要考虑请求如何进入系统、任务执行多久、模型调用如何管理、多个用户如何共享资源,以及服务异常后怎样恢复。

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

传统 Web 应用通常是接收请求、执行业务逻辑、返回结果。Agent 的执行过程可能持续几十秒甚至几分钟,中间还会调用 LLM、访问外部 API、执行多个 Tool,甚至等待人工确认。如果仍然按照普通接口的思路处理所有任务,容易遇到请求超时、资源占用、重复执行和状态丢失等问题。

这一节主要记录 Agent 的部署架构、任务执行模式、并发控制、状态恢复,以及 LangGraph 在生产环境中的应用。

1. Agent 的整体部署架构

一个常见的生产架构可以拆成几个部分:

text
用户 / 前端
                      |
                      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 同步执行

流程比较简单:

text
客户端
  |
  | POST /agent/run
  v
API 服务
  |
  | 执行 Agent
  v
LLM / Tools / 数据库
  |
  | 任务完成
  v
返回最终结果

示例:

text
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 异步任务执行

如果任务需要多轮模型调用、长时间搜索、处理大量文档,或者可能等待人工确认,更适合考虑后台执行。

流程如下:

text
客户端
  |
  | POST /agent/tasks
  v
API 服务
  |
  | 创建任务并提交队列
  v
返回 task_id
  |
  |                    Worker
  |                       |
  |                       v
  |                 执行 Agent
  |                       |
  |                       v
  |                 保存执行结果
  |
  | GET /agent/tasks/{id}
  v
查询任务状态与结果

API 可以很快返回:

text
{
  "task_id": "task_123",
  "status": "queued"
}

客户端之后查询任务状态:

text
{
  "task_id": "task_123",
  "status": "running"
}

任务完成后再读取结果。

后台执行适合研究报告生成、批量文档处理、复杂数据分析以及需要人工审批的 Agent 任务。API 服务可以快速释放请求连接,Worker 则专门负责执行任务。

但引入队列后也会带来新的问题,例如重复投递、任务积压、失败重试和状态一致性。队列并不会自动保证 Agent 任务只执行一次,因此业务层仍然需要设计任务 ID、幂等策略和执行状态管理。

2.3 流式输出

还有一种情况:用户希望立即看到 Agent 的执行过程,但又不想等到任务完全结束。

例如 Research Agent 可以逐步显示:

text
正在分析研究主题
    ↓
正在搜索资料
    ↓
已找到 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 保存任务状态

可以为每个任务维护基本信息:

text
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 暴露接口,在服务内部调用图:

text
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、队列和运行治理能力,通常更容易控制开发成本,也更容易定位问题。

On this page