agent-">纯 Python 手搓 AI Agent：一份面向工程落地的选型指南

一、选型背景：为什么这个问题值得认真讨论

当团队准备把大模型能力接入真实业务时，很快就会遇到一个岔路口：是引入一套现成的 Agent 框架，还是用纯 Python 加上模型 API 自己实现一套调度逻辑？

这个问题之所以反复出现，是因为两类方案的门槛在快速变化。一方面，主流框架不断叠抽象层，工具调用、状态管理、多轮编排、记忆存储被封装成统一接口，上手快，但调用链变长、行为不易预测；另一方面，模型 API 本身的能力在增强，结构化输出、函数调用、流式响应等通用能力逐步标准化，使得“少一层框架”在技术上越来越可行。

需要明确的是，这不是一个“哪个更好”的问题，而是一个“哪个更适合当前需求、团队能力、系统规模和长期规划”的问题。本文的目标，是帮助读者建立一套可复用的判断框架：在什么条件下纯 Python 自研 Agent 是合理甚至更优的选择，在什么条件下应当引入框架或托管化能力，以及如何通过小范围验证降低选型风险。

二、需求拆解：先把问题问清楚

选型之前，先把自己的需求拆成可判断的维度。以下六组问题基本覆盖了 Agent 实现路径的主要决策面：

1. 业务目标：Agent 是用于内部效率工具、面向客户的生产链路，还是实验性探索？目标决定了可接受的上手速度与容错空间。
2. 系统规模：日均调用量、并发峰值、单次任务的步骤数、需要维护的会话数量，直接影响状态管理与调度复杂度。
3. 流程复杂度：是单轮问答加一次工具调用，还是多步骤规划、条件分支、人工介入、跨会话记忆？流程越复杂，编排抽象的收益越明显。
4. 团队能力：团队是否熟悉异步编程、错误重试、可观测性建设？是否有精力维护自研调度层？
5. 运维与合规：是否需要细粒度日志审计、权限隔离、数据脱敏？是否需要把调用链完全掌握在自己手里？
6. 成本结构：不仅是模型调用成本，还包括框架学习成本、调试成本、长期维护成本和迁移成本。

把这些问题的答案写下来，往往就能排除掉一半不适合的选项。

三、选型对象说明：两类实现路径的边界

路径 A：纯 Python 直连模型 API 的自研 Agent。 核心是用语言运行时直接组织提示词、工具调用、循环控制、状态保存与错误处理。调度逻辑、重试策略、上下文裁剪、工具注册全部由业务代码掌握。优点是链路短、行为可预测、调试直观；代价是通用能力需要自己补齐。

路径 B：基于框架或托管能力的 Agent 实现。 由框架提供编排抽象、状态图、记忆组件、工具适配层，或由云服务提供托管化的 Agent 运行能力。优点是起步快、通用模式开箱可用；代价是多一层抽象、排障路径变长、版本升级可能带来行为变化。

两类路径并非互斥。实践中常见的是“核心链路自研、外围能力借助托管服务”的混合形态，例如自研调度逻辑，但把对象存储、消息队列、日志服务、监控告警、身份认证等通用能力交给云平台。

四、核心评估维度

1. 功能覆盖度

先列出业务必需的能力清单：单轮与多轮对话、工具/函数调用、结构化输出解析、上下文长度管理、会话持久化、人工审核节点、失败重试与降级。逐项对照两条路径，标记“自研需多少工作量”“框架是否直接提供”。注意区分“框架宣称支持”和“在当前版本、当前模型下稳定可用”。

2. 可控性与可调试性

Agent 的故障往往不是抛异常，而是“行为不对”。链路越短，越容易定位是提示词、工具返回还是调度逻辑的问题。纯 Python 方案在这一点上有天然优势：一次调用就是一次函数调用，日志可以精确到每一步的输入输出。框架方案则需要理解其内部状态流转，排障成本随抽象层数上升。

3. 性能与稳定性

关注延迟构成（模型响应占大头，调度开销通常较小）、并发模型（同步还是异步、连接池是否复用）、超时与重试策略、限流与熔断。自研方案需要自己实现这些通用模式；框架方案要确认其默认策略是否与业务预期一致，避免“默认重试三次”在幂等性敏感场景下造成重复副作用。

4. 扩展性与演进空间

业务从单 Agent 走向多 Agent 协作、从单工具走向工具市场、从单租户走向多租户时，调度层的改造成本是多少？自研方案的优势是改造自由，劣势是每次演进都要自己设计；框架方案的优势是通用模式已有参考实现，劣势是可能被框架的抽象约束。

5. 安全与合规

需要重点确认：工具调用的权限边界（Agent 能否触发写操作）、提示词注入的防护、敏感数据的脱敏与隔离、调用日志的审计完整性、密钥管理方式。自研方案可以把这些控制点做在最短链路上，但需要自己实现；框架与托管方案要确认其权限模型和日志能力是否满足要求。

6. 成本结构

成本不止是模型调用费用。自研的隐性成本包括：调度层开发工时、可观测性建设、长期维护与人员交接；框架的隐性成本包括：学习曲线、版本升级适配、抽象层带来的调试时间。小规模场景下自研的绝对成本可能更低，大规模长周期场景则要把维护成本摊进去算。

7. 团队能力匹配度

如果团队缺少异步编程、分布式状态管理经验，自研多步骤 Agent 的状态一致性会成为长期负担；如果团队工程能力强、追求链路透明，自研反而能减少“黑盒”带来的沟通成本。

五、选型对比表

评估维度	纯 Python 自研	框架/托管方案
上手速度	较慢，需自建通用能力	较快，通用模式开箱可用
链路可控性	高，行为可精确预测	中，受抽象层影响
调试与排障	直观，日志可精确到步骤	需理解框架内部流转
复杂流程编排	需自行设计与维护	有现成抽象可参考
性能开销	调度开销低，需自管并发	存在抽象层开销
安全控制点	可做在最短链路，需自实现	依赖其权限与日志模型
长期维护成本	与团队能力强相关	与框架版本演进强相关
演进自由度	高	受抽象约束
适用规模	中小规模、流程明确时优势明显	流程复杂、快速起步时优势明显

六、方案适配分析：什么条件下优先选哪条路

优先考虑纯 Python 自研的条件：

• 流程相对明确，步骤数可控，工具数量有限；
• 团队工程能力强，重视链路透明与排障效率；
• 对权限边界、日志审计、数据隔离有细粒度要求，希望控制点集中在最短链路；
• 系统规模处于中小阶段，或增长路径清晰、可渐进式重构；
• 希望避免框架版本升级带来的行为漂移。

优先考虑框架或托管能力的条件：

• 业务需要快速验证，上线时间优先于架构洁癖；
• 流程包含多分支、多角色协作、人工介入等复杂编排；
• 团队缺少分布式状态管理经验，需要现成模式降低风险；
• 需要与云上通用能力（对象存储、消息队列、日志服务、监控告警、身份认证）快速组合。

需要进一步验证的条件： 两类方案在边界场景下都可能翻车，例如高并发下的状态一致性、长会话的上下文裁剪策略、工具调用失败的降级路径。这些必须通过实测确认。

七、决策路径

1. 列出业务必需能力清单与流程步骤图；
2. 评估步骤数与分支复杂度，判断编排抽象的必要性；
3. 评估团队在异步、状态管理、可观测性上的能力缺口；
4. 估算两条路径的开发工时与首年维护成本；
5. 选一条路径做最小可行原型，覆盖最复杂的那个流程分支；
6. 用真实流量特征做小范围试运行，观察失败率、延迟分布与排障耗时；
7. 根据实测数据做最终决策，并保留回退方案。

八、验证方法与示意代码

验证阶段重点观察四个指标：任务成功率、平均步骤数、单步延迟分布、故障定位耗时。以下是一个通用的自研调度骨架示意（伪代码级，仅表达结构）：

def run_agent(task, tools, max_steps=8):
    history = []
    for step in range(max_steps):
        resp = call_model(prompt=build_prompt(task, history), tools=tools)
        if resp.is_final:
            return resp.answer
        result = execute_tool(resp.tool_name, resp.tool_args)  # 含超时与幂等校验
        history.append({"tool": resp.tool_name, "result": result})
        log_step(step, resp, result)  # 每步落日志，便于排障
    return fallback(task)

这段骨架刻意保持扁平：一次循环、一次工具执行、每步落日志。它的价值不在于功能多，而在于任何一步出问题都能从日志直接定位。框架方案验证时，应重点检查其内部状态是否可导出、失败重试是否可控、工具调用是否幂等。

九、落地注意事项

• 权限边界：把“能读”和“能写”的工具分开注册，写操作强制人工确认或二次校验；
• 幂等设计：重试策略必须与工具副作用匹配，避免重复下单、重复发信；
• 上下文管理：提前设计裁剪与摘要策略，不要等超长上下文报错再补；
• 可观测性：每步输入输出、耗时、工具结果都要落日志，指标接入监控告警；
• 密钥与数据：密钥不落代码库，敏感字段在进入提示词前脱敏；
• 渐进演进：先单 Agent 单工具跑通，再扩步骤、扩工具、扩并发，每步都保留回退路径；
• 成本监控：按任务维度统计调用次数与 token 消耗，避免循环失控导致成本异常。

十、总结

纯 Python 手搓 AI Agent 在真实工程中完全可行，且在流程明确、团队工程能力强、对链路透明和权限控制有较高要求的场景下，往往是更优选择。它的代价是通用能力需要自建；框架与托管方案的收益是起步快、复杂编排有现成模式，代价是抽象层带来的调试成本与版本演进风险。选型的关键不是站队，而是把业务目标、流程复杂度、团队能力、运维约束拆成可判断的维度，用最小原型和真实流量特征去验证。条件变化时，混合形态——核心链路自研、通用能力借助云上托管服务——通常是最务实的落地路径。