Session 28:Agent Architecture Design——如何设计一个可维护的 Agent 系统

开发一个简单的 Agent,可能只需要几行代码:接收用户输入,调用 LLM,根据模型返回的 Tool Call 执行工具,再把结果交给模型,直到任务完成

一、Agent 系统的架构,应该从哪里开始

开发一个简单的 Agent,可能只需要几行代码:接收用户输入,调用 LLM,根据模型返回的 Tool Call 执行工具,再把结果交给模型,直到任务完成。

但当业务逐渐复杂,代码很容易变成一个大循环:模型调用、工具执行、上下文拼接、状态更新、异常处理、循环判断全部混在一起。刚开始开发很快,后续增加新工具、修改流程、切换模型或排查故障时,就会越来越困难。

以 Research Agent 为例,完整任务可能包含:

  1. 接收研究主题,确定任务目标。
  2. 制定搜索策略,选择搜索工具。
  3. 搜集网页、数据库或知识库中的资料。
  4. 分析证据,判断现有资料是否充分。
  5. 证据不足时生成新的查询,继续搜索。
  6. 证据充分后生成报告,并检查引用和内容完整性。

这个流程涉及模型、工具、状态、流程控制、存储和业务规则。它们之间存在联系,但职责并不相同。如果全部放在一个 Agent 类中,任何一个模块发生变化,都可能影响整个系统。

我倾向于先从后端工程的角度划分职责,再决定哪些部分需要 Agent 自主决策,哪些部分由程序控制。LangGraph 可以承担流程编排工作,但它不应该成为所有业务逻辑的容器。

二、先划分系统的核心模块

一个相对清晰的 Agent 系统,可以拆成以下几层。

应用层 Application

接收请求、身份认证、返回结果、任务管理

业务与流程层

任务规则、Workflow、LangGraph、状态流转

模型服务层

模型调用、Prompt、结构化输出、模型路由

工具服务层

搜索、RAG、数据库、外部 API

基础设施层

Checkpoint、数据库、日志、Trace、缓存、队列

这只是逻辑分层,不代表每一层都必须部署成独立服务。初期完全可以将它们放在一个 Python 项目中,通过模块和接口划分职责。

1. 应用层:负责接入,不负责 Agent 推理

应用层通常是 FastAPI 等 Web 框架,负责接收请求、校验用户身份、创建任务、调用业务入口并返回结果。

例如,用户提交研究主题后,应用层可以创建一个 research_task_id,然后调用研究服务。

应用层不需要知道模型如何选择搜索工具,也不应该直接处理每一轮 LLM 消息。否则,随着 Agent 流程复杂化,API 路由代码也会越来越难维护。

如果任务可能执行数分钟,应用层还需要考虑异步任务、进度查询、取消任务和结果获取等功能。

2. 业务层:放置稳定的业务规则

业务层负责定义研究任务的约束,例如:

  • 每个任务最多搜索多少轮。
  • 哪些来源可以作为正式证据。
  • 报告必须包含哪些章节。
  • 引用必须能关联到真实来源。
  • 哪些条件下需要人工确认。
  • 哪些情况可以结束任务,哪些情况应该返回失败状态。

其中,一些判断可以交给 LLM。例如,判断不同来源的证据是否足以支持某个结论;另一些判断应该由程序完成,例如最大搜索轮数、预算上限和必填字段检查。

这些规则不应全部埋在 Prompt 里。Prompt 可以告诉模型应该如何判断,程序则负责执行不可绕过的约束。

3. 流程层:负责组织节点与执行顺序

流程层决定任务如何推进。它可以是普通 Python 函数,也可以是显式 Workflow,或者使用 LangGraph 实现。

例如:

text
接收研究任务
    ↓
制定搜索策略
    ↓
搜索资料
    ↓
分析证据
    ↓
检查证据是否充分
    ├── 不充分 → 生成新查询 → 再次搜索
    ├── 需要确认 → 等待人工处理
    └── 充分 → 生成报告
                    ↓
                检查报告
                    ↓
                  返回结果

流程层不应该承担所有具体实现。搜索节点调用搜索服务,报告节点调用报告生成服务,证据检查节点调用相应的分析逻辑。这样,修改搜索服务时,不需要重写整张图。

4. 模型层与工具层:隔离外部能力

模型层封装不同供应商的 API、模型参数、Prompt 组装和结构化输出。工具层封装具体能力,例如网页搜索、向量检索、数据库查询和文件读取。

两层都属于外部能力的接入层,但不能混为一谈。LLM 负责理解、生成和部分决策;Tool 负责执行具体操作并返回结果。

将这两层独立出来,切换模型、调整搜索供应商或更换向量数据库时,影响范围就会小得多。

三、哪些事情应该由 LLM 决定,哪些事情应该由程序决定

这是 Agent 架构中非常重要的一条边界。

LLM 擅长处理语义不明确、需要综合上下文或需要一定推理的任务;程序更适合处理确定的业务规则、状态约束、权限和资源限制。

以 Research Agent 为例:

任务 更适合的执行者 原因
理解研究主题 LLM 需要语义理解
生成搜索关键词 LLM 需要根据主题组织查询
选择允许使用的搜索工具 LLM 或程序共同完成 模型可提出选择,程序必须执行权限校验
执行搜索请求 程序 需要调用外部服务
判断证据是否支持某个结论 LLM 辅助、规则校验 涉及语义分析,但结果仍需验证
限制最大搜索轮数 程序 必须可预测、可强制执行
检查必填字段和引用格式 程序 适合确定性校验
判断是否允许删除或修改数据 程序和授权流程 不能仅依赖模型自我约束

如果把所有决策都交给 LLM,系统的行为会比较难预测;如果把所有步骤都写成固定代码,又可能失去 Agent 处理开放任务的灵活性。

实际设计时,可以让模型负责提出下一步建议,再由程序检查这个建议是否符合当前状态和执行约束。

例如,模型提出继续搜索,程序可以检查剩余搜索轮数、预算和查询是否重复。通过校验后才允许执行下一轮。

四、Workflow 与 Agent 应该如何选择

架构设计时,需要先判断业务流程有多大程度的确定性。

固定流程优先使用 Workflow

如果任务的执行步骤基本确定,只有每一步使用的工具或具体参数会变化,普通 Workflow 通常更容易维护。

例如:

text
解析教材
  → 提取知识点
  → 生成练习题
  → 校验题目
  → 保存题库

步骤顺序基本固定。每一步都可以调用 LLM,但没有必要让模型自主决定接下来应该执行什么。

Research Agent 也可以拆出一个固定流程:先搜索,再分析证据,再检查充分性,最后生成报告。只有在证据不足时,模型才负责生成下一轮搜索查询。外层循环和退出条件仍由程序控制。

开放任务才需要更多自主决策

如果用户提出的任务差异很大,执行路径很难事先确定,或者模型需要根据执行结果动态选择工具,那么可以赋予 Agent 更多决策权。

例如,研究一个技术问题时,模型可能需要先查官方文档,再查论文,然后比较不同实现方案,最后针对存在争议的结论继续寻找证据。

即使如此,也不意味着整个系统都应该交给模型自主运行。通常更稳妥的设计是:用固定流程管理任务生命周期,在少数需要灵活判断的节点中引入 Agent 决策。

这样既能控制成本和风险,也便于测试与排查问题。

五、为什么要把 State 与业务数据分开

LangGraph 的 State 用于描述当前图执行需要的数据,例如研究主题、搜索轮数、证据引用和当前任务阶段。

但系统还有很多业务数据,例如用户信息、任务元数据、完整网页正文、报告历史和权限配置。这些数据不应该因为使用 LangGraph 就全部放进 State。

例如:

text
from typing import TypedDictclass ResearchState(TypedDict):    topic: str    search_round: int    search_queries: list[str]    evidence_ids: list[str]    evidence_sufficient: bool    report_id: str | None

这里的 evidence_ids 用来引用外部保存的证据,report_id 用来关联已经保存的报告。完整文档和报告内容可以保存在业务数据库或文档存储中。

需要明确三种不同的数据:

  • Graph State:当前流程推进所需的数据。
  • Checkpoint:Graph State 在执行过程中的持久化快照,用于恢复。
  • 业务数据库:长期保存任务、用户、文档、报告等业务实体。

三者可能有部分重叠,但职责不同。把它们混成一个大对象,容易造成 State 膨胀、持久化成本增加,以及业务数据生命周期难以管理。

此外,LangGraph 的 Checkpointer 通常按照 super-step 保存状态;它并不自动保证外部数据库操作和图状态之间的事务一致性。比如报告已经写入数据库,但对应 Checkpoint 尚未保存,进程就崩溃了。恢复后可能再次生成或保存报告,因此需要使用业务操作记录、唯一约束或幂等机制来避免重复。

六、如何设计模型和工具的可替换接口

如果所有业务节点都直接调用某个模型供应商的 SDK,那么未来更换模型时,可能需要修改很多代码。可以在模型层定义统一的调用接口,把业务逻辑与供应商细节隔离开。

下面是一个简化的 Python 示例:

text
from typing import Protocol, Anyclass ModelClient(Protocol):    def invoke(        self,        messages: list[dict[str, Any]],    ) -> dict[str, Any]:        ...class ResearchPlanner:    def __init__(self, model: ModelClient):        self.model = model    def create_search_query(        self,        topic: str,    ) -> str:        messages = [            {                "role": "system",                "content": (                    "根据研究主题生成一个有效的搜索查询。"                ),            },            {                "role": "user",                "content": topic,            },        ]        result = self.model.invoke(messages)        return result["content"]

ResearchPlanner 只依赖 ModelClient 接口,不关心底层究竟使用哪家模型服务。

实际项目中,模型返回值通常还要区分普通文本、结构化结果和工具调用。接口应根据业务需求设计,不能为了统一而把所有差异都隐藏掉。

工具层也可以采用类似方式。例如定义 SearchService 接口,分别实现网页搜索、企业内部搜索和测试用的 Mock Search。这样既方便更换供应商,也方便自动化测试。

不过,接口抽象需要适度。只有当存在替换需求、多个实现、测试隔离或清晰的模块边界时,才值得增加抽象层。每个函数都包一层接口,并不一定能改善架构。

七、如何组织 Python 项目

对于 Research Agent 这样的项目,我会采用以下目录结构作为起点:

text
research_agent/
├── app/
│   ├── api/
│   │   └── research.py
│   └── main.py
│
├── domain/
│   ├── models.py
│   ├── rules.py
│   └── exceptions.py
│
├── services/
│   ├── research_service.py
│   ├── evidence_service.py
│   └── report_service.py
│
├── agent/
│   ├── state.py
│   ├── prompts/
│   ├── nodes.py
│   ├── graph.py
│   └── routing.py
│
├── models/
│   ├── base.py
│   └── providers/
│
├── tools/
│   ├── search.py
│   ├── retrieval.py
│   └── database.py
│
├── infrastructure/
│   ├── persistence.py
│   ├── checkpoint.py
│   ├── logging.py
│   └── cache.py
│
└── tests/
    ├── unit/
    ├── graph/
    └── integration/

这里的目录划分不是固定标准。小项目可以更简单,大项目则可能需要进一步拆分任务调度、权限控制和外部服务适配器。

更重要的是模块之间的依赖方向:

  • API 调用业务服务。
  • 业务服务组织业务规则和 Agent 流程。
  • Agent 节点调用模型服务与工具服务。
  • 基础设施提供存储、Checkpoint 和日志等实现。
  • 业务规则尽量不直接依赖某个具体的模型供应商或数据库 SDK。

如果后续决定把 LangGraph 换成其他编排方案,理想情况下主要修改流程层,而不需要重新编写所有搜索、证据处理和报告生成逻辑。

当然,LangGraph 的 State、节点和 Checkpoint 本身会带来一定框架耦合,不能保证完全无成本迁移。合理目标是控制耦合范围,而不是追求完全没有框架依赖。

八、可观测性、测试和错误处理应该从一开始设计

Agent 系统运行起来之后,常见的问题包括模型调用失败、工具超时、循环失控、状态丢失和报告质量下降。这些问题不能全部依赖人工查看最终输出。

架构设计时就应该考虑如何记录和定位问题。

每个任务至少应该有稳定的 task_id 或 run_id,能够关联模型调用、工具执行、节点运行、状态变化和异常。对重要的执行结果,还应记录模型版本、Prompt 版本、工具版本以及相关配置。

错误处理也需要分层:

  • 模型调用超时或临时限流,可以由模型服务层实施有限重试。
  • Tool 执行失败,由工具层区分可重试错误与不可重试错误。
  • 证据不足,由业务流程决定是否继续搜索、请求人工介入或结束任务。
  • 状态不合法,由程序校验并拒绝进入后续节点。
  • 达到最大轮数或预算上限,由流程层终止任务或进入降级分支。

测试方面,可以分别测试业务规则、节点逻辑、图的分支和完整任务。对 LLM 的开放式输出,通常不适合要求每次文本完全相同;更合理的做法是检查结构、关键事实、来源引用和任务约束。

这些能力并非项目上线后才需要补充的外围功能。它们会直接影响系统是否容易修改、能否稳定运行,以及故障发生后能否快速定位原因。

九、Agent 架构设计中容易出现的几个问题

  1. 过度依赖框架。 把业务规则、数据处理和外部接口全部写进 LangGraph 节点,导致换框架或调整流程时牵一发动全身。节点应该负责流程中的一个职责,具体业务处理可以交给独立服务。

  2. 过度追求自主性。 每个步骤都让模型自己决定下一步,增加了不确定性、调用成本和测试难度。固定的业务流程应该由程序控制,需要语义判断的环节再交给模型。

  3. State 过于庞大。 将所有历史消息、网页正文、工具返回值和业务数据全部保存到图状态,增加了上下文和 Checkpoint 的负担。应当只保留流程真正需要的数据,并通过引用关联外部存储。

  4. 把安全限制写在 Prompt 中。 Prompt 可以约束模型行为,但不能代替程序的权限控制。工具执行前仍需要验证身份、权限、参数和资源范围。

  5. 缺少失败恢复设计。 认为有 Checkpoint 就能恢复一切,忽略外部副作用、重复操作和业务数据一致性。需要结合幂等、操作记录和恢复流程设计。

  6. 过度抽象。 项目刚开始就构建复杂的插件体系、通用 Agent 基类和多层工厂,增加了理解成本。先根据明确的变化点抽象,通常比提前设计一个适用于所有 Agent 的框架更实际。

十、总结

设计一个可维护的 Agent 系统,关键在于明确每个模块负责什么,以及模块之间如何协作。模型负责语义理解和部分决策,程序负责确定性规则、权限和资源约束,Workflow 或 LangGraph 负责组织执行流程,工具层负责连接外部能力,基础设施负责状态持久化、日志和监控。

对于 Research Agent,我更倾向于使用固定流程作为主干,把搜索查询生成、证据分析等环节交给 LLM,再由程序控制循环、预算、状态和结束条件。这样既保留了模型的灵活性,也能让整个系统更容易测试、调试和扩展。

架构不需要一开始就设计得非常复杂。先把职责分开,控制依赖方向,记录关键执行过程,再根据实际的性能、稳定性和业务需求逐步拆分,通常更适合持续演进的 Agent 项目。

希望这篇文章能对你有所帮助。关注我,持续分享更多实用、好用的 AI 干货。

本文目录