agent-">纯 Python 手搓 AI Agent：可行性与工程实践

一、问题的提出

在大模型应用开发领域，Agent（智能体）已经成为最热门的方向之一。围绕 Agent 的构建，业界涌现出大量框架与工具链，它们提供了抽象层、编排能力和开箱即用的组件。但随之而来的问题是：当一个开发者只是想实现一个边界清晰、逻辑可控的 Agent 时，引入一套完整的框架是否必要？

本文要讨论的核心命题是：不依赖任何重型 Agent 框架，仅用纯 Python 能否构建一个功能完整的 AI Agent？ 答案是肯定的。而且这个结论并非取巧，而是由 Agent 的本质决定的。

二、Agent 的本质：一个循环

拨开各种框架的封装，Agent 的核心机制可以用一句话概括：它是一个循环，把上下文喂给大模型，大模型做出决策，代码执行决策，执行结果再回喂给大模型，如此往复，直到任务完成。

这个循环被称为 Agent Loop。它包含四个基本动作：

1. 上下文投喂：将当前的任务描述、历史消息、工具定义等组装成消息列表，发送给大模型。
2. 模型决策：大模型基于上下文判断下一步动作——是调用某个工具，还是直接给出最终答案。
3. 执行动作：如果是工具调用，由外部代码实际执行该工具，拿到结果。
4. 结果回喂：将工具执行结果追加到消息列表中，进入下一轮循环。

当大模型判断不再需要调用工具、可以直接回复用户时，循环终止。如果循环轮数超过预设上限仍未结束，则强制中止，避免无限消耗。

这个过程没有任何神秘之处。它是确定性的控制流加上大模型的推理能力，而不是某种需要复杂编排引擎才能驱动的特殊机制。

三、最小实现：百行以内的 Agent

基于上述认知，一个最小可用的 Agent 用纯 Python 写出来不过百行。下面给出一个伪代码级别的骨架，它清晰地展示了 Agent Loop 的结构：

async def agent_loop(task, tools, max_rounds=20):
    messages = [{"role": "user", "content": task}]
    for _ in range(max_rounds):
        # 1. 将上下文与工具描述一起发给大模型
        reply = await llm.chat(messages, tools=tools.schema())
        # 2. 判断模型是否要调用工具
        if reply.tool_call:
            # 3. 执行工具，拿到结果
            result = await tools.run(reply.tool_call)
            # 4. 将模型决策与工具结果追加到上下文
            messages.append(reply)
            messages.append({"role": "tool", "content": result})
        else:
            # 模型直接给出答案，循环结束
            return reply.content
    return "超出最大轮数，任务中止"

这段代码虽然简短，却包含了 Agent 运行所需的全部要素：

• 消息列表：承载任务描述、历史对话、工具调用记录和工具返回结果，是大模型决策的唯一信息来源。
• 工具描述（schema）：告诉大模型有哪些工具可用、每个工具接受什么参数。这是模型能够正确选择工具的前提。
• 分支判断：区分”模型要调工具”和”模型给出最终答案”两种情形，前者继续循环，后者退出。
• 轮数上限：防止 Agent 陷入死循环或消耗过多资源，是工程上的必要保护。

四、Agent 运行时过程拆解

为了更直观地理解 Agent 的运行过程，我们可以把上面的循环展开为一条时间线：

第一轮：用户提交任务 → 消息列表只有任务描述 → 发给大模型 → 模型判断需要调用搜索工具 → 代码执行搜索 → 搜索结果追加进消息列表。

第二轮：消息列表 = 任务 + 模型决策 + 搜索结果 → 发给大模型 → 模型判断搜索结果不够，需要再查一次 → 代码执行搜索 → 新结果追加。

第三轮：消息列表进一步增长 → 发给大模型 → 模型判断信息已足够 → 直接生成最终回答 → 返回结果，循环结束。

在这个过程中，大模型始终扮演”大脑”的角色，每一轮都在参与决策。而 Python 代码扮演”手脚”的角色，负责执行模型指定的动作，并把执行结果如实反馈回去。整个系统的智能来自模型，控制流来自代码，二者职责边界清晰。

这就是 Agent 的最小结构：一个 while 循环套一次 LLM 调用，工具结果回喂上下文，模型说不用调工具了就结束。 所有 Agent 框架的内核，本质上都是这张图的不同实现版本。

五、为什么纯 Python 实现是可行的

理解了 Agent 的最小结构之后，”纯 Python 手搓 Agent 是否可行”这个问题就变成了一个几乎不言自明的结论。可行性建立在以下几个事实之上：

第一，控制流本身很简单。 Agent Loop 是一个带有终止条件的循环，加上一个二分支判断。这是任何一门编程语言的基础能力，Python 的异步语法足以优雅地表达它。

第二，大模型接口已经标准化。 主流的大模型服务都提供对话补全接口，接受消息列表和工具定义，返回结构化的决策结果。Python 中发起 HTTP 请求或使用官方 SDK 都是成熟方案，不需要框架介入。

第三，工具调用是纯代码逻辑。 工具就是普通的 Python 函数，接收参数、执行操作、返回结果。框架提供的”工具注册””参数校验”等能力，用几十行代码就能自行实现，且更容易按需定制。

第四，没有隐藏的魔法。 框架并没有实现什么代码无法表达的东西——它只是把循环、消息管理、工具调度等逻辑封装成了通用组件。当需求与框架预设一致时，框架能提升效率；当需求偏离预设时，框架的抽象反而成为负担。

六、手搓 Agent 的工程优势

选择纯 Python 实现 Agent，不仅仅是”可行”，在很多场景下它还是更优解。

完全可控。 每一行代码你都知道它在做什么。消息是如何拼接的、工具是如何被选择的、异常是如何被处理的，全部透明。当 Agent 行为不符合预期时，调试路径清晰，不需要穿透框架的层层抽象去定位问题。

定制自由。 想加入自定义的终止条件？在循环里加一个判断即可。想让某些工具只在特定轮次可用？修改工具 schema 的生成逻辑即可。想对模型输出做特殊解析？在追加消息前处理即可。定制逻辑想加就加，没有框架约束。

依赖精简。 不引入框架意味着更少的依赖、更小的攻击面、更低的版本冲突风险。对于一个需要长期维护的系统，这一点尤其重要。

能力可组合。 由于工具就是普通函数，Agent 的能力扩展变成了纯粹的编程问题：接上搜索工具，它就成了调研 Agent；接上数据库查询工具，它就成了数据分析 Agent；接上文件读写工具，它就成了代码处理 Agent。同一个循环内核，通过替换工具集就能覆盖不同场景。

七、需要正视的工程挑战

当然，手搓 Agent 并不意味着所有问题都迎刃而解。随着系统复杂度上升，以下问题需要认真处理：

上下文长度管理。 随着循环轮数增加，消息列表会不断膨胀，最终可能超出模型的上下文窗口。需要在合适时机对历史消息做摘要、截断或选择性保留。这是一个策略问题，框架通常提供默认方案，手搓则需要自行设计。

工具调用的健壮性。 模型可能给出格式错误的参数、调用不存在的工具、或传入越界值。需要有完善的参数校验、错误捕获和错误回喂机制，让模型能够根据错误信息自我修正。

并发与超时。 当多个工具可以并行执行时，如何调度；当某个工具执行超时，如何中断并反馈。这些都需要在循环之外补充工程逻辑。

可观测性。 没有框架提供的日志与追踪，需要自行埋点，记录每一轮的输入、决策、执行结果和耗时，以便分析 Agent 的行为模式。

这些挑战的存在，恰恰说明了为什么”纯 Python 实现”值得认真对待——它们是真实的工程问题，需要开发者理解并解决，而不是被框架隐藏起来。

八、适用场景判断

那么，什么时候应该手搓 Agent，什么时候应该使用框架？

适合手搓的场景：

• 任务边界清晰，循环逻辑不需要复杂编排；
• 需要深度定制消息处理、工具调度或终止条件；
• 对依赖体积、启动速度、可控性有较高要求；
• 团队希望完全掌握 Agent 运行细节，便于调试和优化。

适合使用框架的场景：

• 需要快速验证多 Agent 协作、复杂工作流编排等高级模式；
• 团队希望复用社区沉淀的最佳实践，减少重复造轮子；
• 对可观测性、持久化、分布式执行等有开箱即用的需求。

需要强调的是，这两条路径并不对立。理解 Agent 的最小结构，是判断何时该用框架、何时该自己动手的前提。很多团队在使用框架遇到瓶颈后，最终会回归到对核心循环的自行实现，正是因为看清了这层本质。

九、结语

Agent 没有那么神秘。它是循环、判断和消息追加的组合，是代码控制流与大模型推理能力的协作。用纯 Python 实现一个 Agent，百行代码足矣，而这一百行代码带来的透明性、可控性和定制自由度，是任何通用框架都难以替代的。

对于新手而言，从最小实现入手是理解 Agent 原理的最佳路径；对于需要构建定制系统的团队而言，基于核心循环自行扩展是最合适的方法。当你真正动手写一遍这个循环，就会明白：Agent 的门槛不在框架，而在对问题本身的理解。