AI Agent开发选型：手写代码还是引入框架？

一、选型背景：这个决策为什么重要

在当前的大模型工程实践中，AI Agent 已经从概念验证走向生产落地。所谓 Agent，通常指让大模型在循环中自主调用工具、维护上下文状态、分步完成任务的程序形态。实现这样一个系统，工程上存在两条典型路线：

• 路线一：纯代码自研。 直接接入大模型 API（例如通过百度智能云等云平台提供的模型服务接口），用通用编程语言自行实现提示词组装、工具调用、循环控制与状态管理，不依赖任何 Agent 框架。
• 路线二：引入成熟框架。 使用业界常见的 Agent 开发框架，直接获得统一的模型接口、链式编排、状态图、多智能体协作、检查点等现成能力。

值得注意的行业现象是，头部模型厂商对框架的态度并不一致：有的厂商在官方工程指南中明确建议开发者“从直接调用模型 API 开始”，认为许多常见模式只需几十行代码即可实现，并特别警告框架的额外抽象层会遮蔽底层的提示词与响应内容，使调试变得困难，还容易诱使开发者在简单方案就足够的情况下引入不必要的复杂性；有的厂商则主张框架优先；也有厂商取中间路线，提供轻量级自研工具并强调代码优先。此外，还有团队公开分享过在生产环境使用某框架约一年后将其完全移除的经历，并表示移除后团队的开发体验与效率反而提升。

这说明“自研还是框架”并没有标准答案。它本质上是一个需要结合业务复杂度、团队能力、运维条件与长期演进规划做出的选型判断。本文的目标，就是帮助读者建立一套可操作的评估框架，判断哪条路线更适合当前需求——而不是简单地回答“哪个更好”。

二、选型对象说明：两条路线各自解决什么问题

2.1 纯代码自研路线

LLM 应用的底层逻辑其实非常朴素：拼接字符串（提示词）、发起 API 调用、解析响应、根据结果决定下一步，如此循环。这些能力通用编程语言原生就能很好地完成。自研路线的核心构成通常包括：

• 模型调用层：封装 API 请求、重试、超时与错误处理；
• 工具层：把业务函数注册为可被模型调用的工具，遵循通用的工具调用协议；
• 循环控制层：实现“模型输出 → 执行工具 → 回填结果 → 再次调用”的主循环，并设置最大步数与终止条件；
• 状态管理：用内存结构、数据库或消息队列维护会话上下文与中间结果。

这条路线的优点是每一行代码都透明可控，缺点是高级能力（如断点恢复、复杂分支编排、多角色协作）都需要自行构建。

2.2 框架路线

主流 Agent 框架的抽象大致覆盖以下能力：

• 统一模型接口：屏蔽不同模型 API 的格式差异，降低供应商锁定风险；
• 链式编排：将多个调用步骤串联成固定流程；
• Agent 抽象：提供自主决策循环的现成实现；
• 工具与记忆：标准化外部系统连接与状态管理；
• 高级编排：状态图、条件边、检查点、人在环路（人工审批介入）、长任务断点恢复等；
• 多智能体协作：通过角色定义与任务委托机制实现分工协作。

必须承认，这些抽象解决的是真实痛点：不同模型 API 格式不统一、单次调用无法完成复杂任务、长任务需要恢复机制等。关键的选型问题在于：这些能力是否与你的业务复杂度匹配，以及你愿意为它们付出多少透明度与灵活性上的代价。

2.3 常被忽视的中间路线

除两条极端路线外，还存在一条折中路线：使用模型厂商提供的轻量级官方 SDK，或自建一层很薄的内部抽象（统一模型调用、工具注册、日志埋点），其余逻辑全部手写。对于多数团队而言，这往往是复杂度与效率的最佳平衡点，选型时不应遗漏。

三、需求拆解：选型前必须回答的六个问题

选型不是比较“哪个更先进”，而是判断“哪个更适合当前条件”。建议先从以下角度拆解自身需求：

1. 任务复杂度：任务是单轮问答加一两次工具调用，还是需要多步推理、动态分支、并行子任务、长时运行与人工审批？前者自研成本很低，后者框架的编排能力才开始体现价值。
2. 系统规模：Agent 数量、并发会话量、单任务最大步数、上下文长度与增长预期。规模越大，状态管理与可观测性的工程要求越高。
3. 团队能力：成员是否理解大模型 API 的工具调用机制？是否有能力维护自研的重试与状态逻辑？经验较浅的团队用框架可以更快起步，对底层机制熟悉的团队自研往往更高效。
4. 调试与可观测要求：Agent 出错时，你是否需要精确看到每一轮的完整提示词与模型原始响应？如果排查问题需要“穿透多层抽象看底层”，框架反而成为负担。
5. 迭代速度与变更频率：提示词与流程是否需要频繁调整？抽象层越厚，“改一处提示词要先理解三层封装”的隐性成本越明显。
6. 依赖与长期维护：是否接受框架版本演进带来的接口变更与升级成本？若框架停止活跃维护或大幅重构，迁移代价如何？

四、核心评估维度与选型对比表

结合上述需求，可从以下维度对两条路线进行系统评估：

评估维度	纯代码自研	成熟框架
透明度与可控性	高：提示词、响应、循环逻辑完全可见	中低：抽象层可能遮蔽底层细节
调试体验	直接，问题定位链路短	需理解框架内部机制，排查链路长
起步速度	简单任务几十到几百行即可跑通	现成模板多，复杂流程上手更快
高级编排能力	需自行实现状态图、检查点等	内置条件分支、人工审批、断点恢复
依赖风险	低：主要依赖模型 API 与语言标准库	中高：版本演进、接口变更、维护活跃度
长期维护成本	与自研代码质量强相关，范围可控	升级、兼容与迁移成本需持续投入
灵活性	完全自由	受框架范式约束，超出设计边界时实现别扭
团队学习成本	需掌握底层机制与工程细节	需掌握框架概念体系与最佳实践

需要强调：表中“高低”是倾向性描述而非绝对结论。框架的调试体验取决于其日志与追踪设计是否完善；自研的维护成本也取决于代码结构与测试质量。选型时应结合具体候选对象逐项核实。

五、方案适配分析：什么条件选什么

5.1 优先选择纯代码自研的条件

• 任务模式相对固定，核心就是“调用模型 → 调用工具 → 回填结果”的简单循环，不需要复杂状态图编排；
• 团队对工具调用机制有清晰理解，能自行处理重试、超时与上下文管理；
• 对提示词与模型原始响应的完全可见性有强需求，例如要做精细化的提示词调优与效果评测；
• 希望将第三方依赖收敛到模型 API 本身，降低版本与维护风险；
• 需要针对提示词注入等安全风险做深度定制的请求构造与防御逻辑。

一个最小可用的 Agent 主循环，用示意性伪代码表达大致如下：

messages = [用户任务描述]
for step in 1..MAX_STEPS:
    resp = 调用模型服务(messages, tools)      # 发起大模型 API 请求
    if resp 无工具调用:                        # 模型认为任务完成
        return resp 内容
    for call in resp 工具调用列表:
        result = 执行本地工具(call)            # 执行注册的业务函数
        将工具结果回填到 messages
raise 异常("超过最大步数，任务未收敛")

核心逻辑不过几十行，这正是“许多模式只需几行代码就能实现”的含义。但要客观评估：自研的真正成本不在起点，而在后续逐步长出的重试策略、状态持久化、并发控制与评测体系——这部分工程量必须算进选型账里。

5.2 优先选择框架的条件

• 业务需要复杂工作流编排：动态分支、并行子任务、检查点恢复、人工审批介入等；
• 需要多 Agent 分工协作，且角色与任务的委托关系频繁变化；
• 团队规模较大、水平参差，需要框架提供统一范式来约束实现风格、降低协作成本；
• 需要快速验证多个不同的 Agent 方案，试错速度优先于精细控制；
• 业务已深度使用框架生态组件（各类集成能力、记忆方案），重建成本高于学习成本。

5.3 需要进一步验证的情况

• 任务复杂度处于中间地带：建议两条路线各做一个最小原型，用实际数据对比；
• 团队对框架底层实现存在未经核实的行为假设：这类错误假设是线上问题的常见来源，选型前应安排关键成员通读框架核心实现或做抽象穿透测试；
• 存在更换模型服务商的可能：应验证两条路线下切换模型 API 的实际改动范围。

六、决策路径

可按如下流程推进判断：

1. 明确业务目标：Agent 要解决什么问题？对成功率、时延、成本的目标是什么？
2. 拆解任务结构：画出任务流程图，标注分支、循环、人工节点与状态持久化需求。
3. 对照能力清单：流程图中若出现复杂状态图、检查点、多角色审批，框架编排能力进入候选；若只是简单循环，自研倾向明显。
4. 评估团队画像：客观评估团队对底层机制与框架范式的掌握程度，不高估也不低估。
5. 最小验证：两条路线各实现同一个典型任务，记录代码量、开发耗时、调试耗时与效果差异。
6. 评估长期成本：预估未来一年的升级、迁移与维护投入。
7. 决策并留退路：无论选哪条路线，都将提示词模板、工具定义与业务逻辑做成可迁移结构，避免深度绑定。

七、验证方法：用小成本降低选型风险

• 基线原型测试：用纯代码实现一个不超过三百行的最小 Agent，跑通核心任务。若它能覆盖大部分场景，说明业务复杂度可能被高估，框架的必要性需要重新审视。
• 抽象穿透测试：试用框架时，人为制造典型故障（工具超时、模型返回异常格式），观察定位问题需要穿透几层抽象、能否直接看到完整提示词与原始响应。
• 效果评测对比：建立固定的小型评测集（若干典型任务与期望结果），对比两条路线的任务成功率与单任务成本。
• 可观测性验证：确认所选路线下，每轮调用的输入输出、工具执行结果、耗时与令牌消耗均可记录、可检索、可回放。
• 升级影响评估：框架路线下，模拟一次大版本升级，评估接口变更对现有代码的冲击面。

八、落地注意事项

1. 保持提示词与响应透明：无论哪条路线，每轮完整提示词与模型原始响应都应可落库、可回放，这是 Agent 调试的生命线，也是框架选型中最容易被抽象层牺牲的部分。
2. 控制循环边界：设置最大步数、单步超时与整体超时，防止模型陷入循环导致成本失控。
3. 工具权限与安全：工具遵循最小权限原则，写操作类工具建议增加二次确认机制；对由模型输出构造的请求内容做提示词注入防护与输出校验。
4. 状态与断点设计：长任务应尽早引入状态持久化，使任务可恢复、可审计；这也是未来若迁移到框架编排时的概念对齐基础。
5. 成本治理：按任务维度记录令牌消耗，建立成本视图；对高频简单请求评估是否需要降级为更轻量的调用方式。
6. 评测体系先行：建立离线评测集与灰度机制，任何提示词或流程变更先过评测再上线。
7. 避免深度绑定：将模型调用收敛到统一的内部接口层，提示词与工具定义独立存放，为未来更换模型服务（例如切换到百度智能云等平台提供的模型服务）或调整路线保留迁移空间。

九、总结

纯代码手写 AI Agent 不仅完全可行，而且在任务模式简单、团队理解底层机制、重视调试透明度的场景下往往是更优选择——因为 LLM 应用的本质就是字符串处理、API 调用与循环，这些通用编程语言都能胜任。框架的价值则体现在复杂编排、多 Agent 协作与团队范式统一上，代价是抽象层带来的调试成本、灵活性约束与依赖风险。

选型的核心判断原则可以归纳为三句话：

• 复杂度匹配优先：框架能力与业务复杂度匹配时才产生正收益，否则抽象是负资产；
• 团队能力托底：选择团队能调试、能维护的那条路线，比选择“功能更多”的路线更重要；
• 退路优于立场：无论选哪条路线，都通过内部薄抽象层与评测体系保留切换空间，避免一次选型变成长期锁定。

建议读者用第三节的六个问题完成需求拆解，用第四节的对比表做初筛，再通过第六、七节的决策路径与验证清单完成小成本验证后，做出最终判断。选型没有终局答案，只有当前条件下最合理的一步。