从零构建Agent框架：四大核心模块拆解与代码实现

为什么需要一个Agent框架？

当我们从零开始构建AI Agent时，通常会经历这样一个过程：先让Agent能调用大模型，再加上对话记忆，然后接入工具调用，最后跑通Reason-Action循环。

Reason-Action循环（也称ReAct模式）是Agent架构的核心范式，源自2022年谷歌与普林斯顿大学联合发表的论文《ReAct: Synergizing Reasoning and Acting in Language Models》。其核心思想是让大模型交替执行「推理」（Reasoning）和「行动」（Acting）两个步骤：模型先分析当前状态并决定下一步动作，执行动作后观察结果，再进入下一轮推理。这种循环让模型能够处理需要多步骤、多工具协作的复杂任务，而不是一次性生成答案。

但做到这一步后，你会发现一个严重的问题——所有代码都混在一起。

运行时逻辑、消息管理、工具管理耦合在同一个文件中，想扩展新工具就要改一大片代码，想换个任务场景更是无从下手。这正是我们需要将这些能力抽象成一个可复用框架的原因。

本文带大家梳理如何将已验证的Agent能力拆分为四个清晰模块，构建一个小型但完整的Agent框架。

Agent框架的四大核心模块

整个框架围绕四个抽象层展开，各司其职，互不干扰。

Tool Registry：工具注册中心

Tool Registry负责三件事：注册工具、生成工具规范（供大模型识别）、执行工具调用。

它的核心数据结构是一个字典，key是工具名称，value是工具的完整定义（ToolDefinition），包含名称、描述、参数列表和具体的执行函数（handler）。

上层的Reason-Action循环不需要关心每个工具内部怎么实现，下层的工具函数也不需要知道主循环的运行细节。这种解耦让新增工具变得极其简单——只需要写好函数，注册进去即可。

Message Store：消息管理器

Message Store负责保存对话历史、管理上下文记忆，并在每次append消息时自动执行裁剪，确保不会超出模型的上下文窗口。

大语言模型存在上下文窗口（Context Window）限制，即单次能处理的最大Token数量。GPT-4o约为128K Token，Claude 3.5 Sonnet约为200K Token。在长对话或多轮工具调用场景中，历史消息会持续累积，一旦超出限制，API调用将直接报错。常见的裁剪策略包括：滑动窗口（保留最近N条消息）、摘要压缩（将旧消息总结为摘要）、重要性过滤（优先保留工具调用结果）。将裁剪逻辑封装在Message Store中，使得策略升级对上层完全透明——主循环中只需要调用store.append(message)即可，裁剪策略的变更不会影响其他模块。

Agent Runtime：运行时引擎

Agent Runtime是整个框架的心脏，封装了完整的Reason-Action主循环：

• 组装每次与大模型交互的消息（系统提示词 + 历史消息 + 当前状态）
• 调用大模型获取回复
• 判断模型是否需要调用工具
• 如果需要，执行工具并将结果写回消息和状态
• 如果不需要，将模型回复作为最终结果返回
• 支持Hook接口，可在工具调用后执行自定义逻辑

Built-in Tools：内置工具集

框架提供了一个存放具体工具实现的模块，比如文件创建、文件读取等。这些工具通过装饰器模式注册，用户也可以轻松添加自己的工具。

Python装饰器模式：让工具定义更优雅

框架最巧妙的设计之一是@tool装饰器。传统方式下，定义一个工具需要手写JSON Schema格式的工具描述。OpenAI在Function Calling功能中要求开发者以JSON Schema格式描述工具的名称、用途和参数结构，大模型据此判断何时调用哪个工具、传入哪些参数。手写JSON Schema不仅冗长，还需要精确描述每个参数的类型、是否必填等元信息，极易出错且难以维护。而通过@tool装饰器，一个普通的Python函数可以瞬间变成Agent可识别的工具，彻底消除这一痛点。

@tool装饰器的实现原理

@tool装饰器本质上是一个高阶函数，它接收描述信息和参数描述作为输入，然后完成以下几步操作：

1. 自动推导工具名称：如果没有显式指定，直接使用函数名（如create_text_file）
2. 自动提取描述信息：如果没有传入描述，则读取函数的docstring（三引号包裹的文档字符串）
3. 构建ToolDefinition对象：将名称、描述、参数列表和函数本身封装为标准结构
4. 挂载到函数对象上：通过setattr给函数对象添加__tool_definition__属性

Python装饰器利用了语言的元编程能力：通过setattr在函数对象上挂载__tool_definition__属性，使函数在运行时携带自描述信息。这与Java的注解（Annotation）机制高度相似——Java通过反射（Reflection）在运行时读取注解信息，Python则通过检查对象属性实现同等效果。这种「数据即代码」的设计让工具的定义与实现始终保持同步，消除了文档与代码脱节的风险。

在Tool Registry的标准化方法中，只需检查函数是否具有__tool_definition__属性，就能判断它是否被@tool装饰过，并自动完成注册。

批量注册工具的便利性

框架还支持从整个模块批量注册工具。只需将一个Python模块（文件）传入，框架会自动扫描其中所有被@tool装饰的函数，逐一转化为ToolDefinition并注册。这意味着你可以将所有工具函数集中放在一个文件中，一行代码完成全部注册。

通用化的Agent状态管理

在早期版本中，Agent的状态（state）往往包含大量业务定制字段，比如特定的文件路径、文件内容等。这导致换一个任务场景时，状态结构就要重写。

框架将状态拆分为两部分：

• 通用状态：上一次工具调用的名称、上一次工具调用的结果、是否完成、循环次数、任务目标——这些是所有Agent任务都需要的
• 扩展上下文（extra context）：业务定制化的状态放在一个可扩展的字典中，不同任务可以自由添加字段

这种设计让框架的state不再绑定特定业务，真正实现了通用化。

主入口的简洁性

经过模块化拆分后，程序的主入口变得极其简洁：

1. 读取API Key（从环境变量获取）
2. 创建Agent Runtime和Message Store
3. 进入交互循环：获取用户输入 → 添加到消息存储 → 调用runtime.run() → 输出结果

整个主文件不超过几十行，所有框架逻辑都封装在内部模块中。

总结：从小型框架到主流架构的设计共性

这个小型Agent框架虽然代码量不大，但体现了几个重要的工程思想：

• 关注点分离：工具管理、消息管理、运行时逻辑各自独立，互不侵入
• 开闭原则：新增工具不需要修改主循环代码，只需注册即可
• 装饰器模式：通过元编程降低工具定义的心智负担
• 通用化抽象：状态管理不绑定具体业务，通过扩展字段支持定制需求

理解这些设计思路，不仅有助于你构建自己的Agent框架，也能帮助你更好地理解主流框架的内部架构。LangChain的AgentExecutor与本文的Agent Runtime在设计上高度相似，同样封装了工具注册、消息管理和Reason-Action循环；AutoGen（微软出品）则更侧重多Agent协作场景，支持多个Agent之间的消息传递与角色分工；CrewAI在此基础上进一步抽象了「角色」和「任务」的概念。理解本文构建的小型框架，相当于掌握了这些主流框架的「最小可行版本」，能够更清晰地看穿其复杂API背后的本质设计——它们的核心思想是一致的，只是在规模和功能丰富度上有所不同。

核心要点

• 将Agent能力拆分为四大模块：Tool Registry（工具注册）、Message Store（消息管理）、Agent Runtime（运行时引擎）和Built-in Tools（内置工具），实现关注点分离
• 通过@tool装饰器模式，可以将普通Python函数自动转化为Agent可识别的工具，避免手写JSON Schema格式的工具定义
• 状态管理分为通用状态和扩展上下文两部分，通用字段（如循环次数、任务目标）固定不变，业务定制字段放入extra context自由扩展
• 框架支持从模块批量注册工具，自动扫描所有被@tool装饰的函数并完成注册，极大简化了工具管理流程
• 模块化拆分后新增工具无需修改Reason-Action主循环代码，体现了开闭原则的工程思想