先聊一个很有意思的争论很多开发者一看到有人在项目里引入了一套自研的 Agent 框架第一反应就是“别重复造轮子”。如果用的是 LangChain、CrewAI、AutoGen 这些成熟框架大家会觉得正常一旦听说某个团队自己封装了智能体框架马上会有人跳出来说“自建智能体框架没有价值”。这个观点听起来很理性但放到真实业务里往往站不住脚。我这几年既深度使用过开源 Agent 框架也在多个项目里从零搭建过内部框架真实感受是自建的价值不取决于“你有没有重复造轮子”而取决于“你的业务是否能用通用框架低成本覆盖”。这篇文章不想单纯打嘴仗而是从工程角度拆解智能体框架的核心组成。我会先用概念说明为什么自建会有争议再给出一套可以直接运行的最小自建框架代码最后聊聊自建框架的边界、取舍和踩坑经验。无论你是准备选型还是已经决定自建这篇文章都值得收藏。1. 背景自建智能体框架为什么会惹争议1.1 智能体框架到底是什么智能体框架是支撑智能体Agent运行的一套软件骨架。智能体本身是一个能感知环境、做出决策、调用工具并执行任务的程序实体而智能体框架则负责把“感知、决策、行动”这个过程标准化通常包含大模型接口封装统一对接不同模型服务。工具调用协议让模型能按约定调用外部 API、函数。记忆管理保存短期对话信息和长期业务知识。任务规划将复杂目标拆解为多步执行计划。生命周期管理处理运行状态、异常重试、日志追踪。如果把这些能力全部从零写一遍确实工作量不小。这也是很多人认为“自建无价值”的最直接理由既然社区里已经有现成框架再自己维护一套等于把别人已经解决过的问题重新踩一遍。1.2 无价值论的三个常见依据这类观点通常基于三个逻辑。第一开源框架生态成熟。LangChain 这类项目有大量社区贡献Tool 调用、Prompt 模板、向量库集成都是现成的自建框架很难在功能数量上超过它们。第二维护成本高。框架不是写完就结束只要大模型接口变了、提示词效果不好、工具协议调整框架代码就得跟着升级。一个团队如果没有专门人力很容易被自研代码拖垮。第三人才和学习成本。新成员入职后学习团队自建框架需要时间如果直接使用社区主流框架网上资料、社区解决方案都比较丰富排障效率更高。这三点都有道理但只能说明“盲目自建”不可取不能证明“自建永远无价值”。实际情况是很多团队的智能体业务并不需要 100 个集成组件而是需要 3 个非常稳定、可控、安全的核心能力。这个时候自建框架反而比通用框架更合适。1.3 反驳的切入点价值取决于业务场景自建智能体框架的价值主要体现在四个方面。第一贴合业务模型。通用框架为了兼容所有场景抽象层往往很多。业务里的一个“工具调用”在通用框架里可能被拆成 Tool 定义、Tool 执行器、Tool 节点、Tool 回调等多个概念。自建框架可以按业务直觉来设计代码量和理解成本都能降下来。第二可控性强。通用框架对内部调度逻辑的封装比较重。一旦遇到线上问题你需要花费大量时间去翻框架源码。自建框架的每一行代码都是自己的定位问题要快得多。第三安全边界更容易做。企业级智能体通常要接入内部系统、数据库、操作审计这些场景对身份鉴权、数据隔离、操作审批有严格要求。通用框架的通用设计往往没有为特定企业的安全模型定制接口自建框架可以保证所有请求都走统一的安全网关。第四便于演进和长期沉淀。框架不是一次性交付而是随着业务不断迭代。自建框架沉淀的是团队对智能体运行机制的理解这种积累在技术层面是非常有价值的。当然价值并不是“自建”两个字带来的而是“清晰边界 可维护设计 工程落地”带来的。2. 智能体框架的核心模块自建前必须想清楚的事不管最终是自建还是选型都要先理解智能体框架最核心的几个模块。我们用一个最简单的流程来拆解。一个智能体通常按“感知 - 规划 - 行动 - 观察 - 总结”来运转接收用户输入。分析是否需要调用工具。如果需要则选择工具并生成工具参数。执行工具拿到结果。把工具结果和原始输入一起交给模型生成最终回答。把交互过程中的关键信息写入记忆。核心模块就是用代码把上述流程的每一步稳定地组织起来。2.1 模型调用层模型调用层把“调用大模型”封装成统一接口屏蔽不同模型服务之间的差异。至少需要支持以下方法生成单次回复。可选的流式输出。传入历史消息、工具定义。自建框架如果只对接一个固定模型服务模型调用层可以非常薄如果需要支持多模型切换则要定义统一的ChatModel接口。2.2 工具层工具层的核心是“注册”和“执行”。注册是指把某个函数变成模型可感知的工具包含工具名称、描述、参数结构执行是指根据模型的调用请求实际运行对应函数并返回结果。自建工具层时最重要的设计是“工具描述要稳定”。因为大多数场景下模型是通过工具描述来判断何时调用、传什么参数的。描述写得模糊工具就会经常被误调用。2.3 记忆层记忆层解决的是上下文连续问题。智能体不是每次都独立回答问题它可能需要记住用户的偏好、之前的任务进度、某些业务约束。记忆可以分成两层短期记忆保存当前会话内的消息列表通常直接传给模型。长期记忆把重要信息存储到数据库或向量库中在需要时检索出相关片段再注入提示词。自建框架初期建议只实现短期记忆先跑通流程再逐步加入长期记忆。2.4 规划层规划层是智能体“聪明”与否的关键。最简单的规划策略是“单步决策”模型每一步只决定“这一轮要不要调工具、调哪个工具”。复杂一点的规划会生成一个多步计划再逐步执行。自建框架不一定一开始就做复杂的任务规划。从单步决策开始能避免早期代码失控。3. 自建智能体框架的正确姿势先做最小可用闭环很多人一听到“自建框架”脑海中浮现的是像 LangChain 那样庞大的项目结构。这是一个误区。自建框架并不等于“重复实现 LangChain”而是先解决自己的核心业务闭环。我推荐的做法是先做一个不到 200 行代码的“最小可用闭环”把模型调用、工具注册、记忆、主循环跑通。有了这个闭环后续再往里面加能力。下面我们来写一套这样的代码。这套代码有以下特点只使用 Python 标准库不依赖第三方框架。为了演示方便模型层使用一个“可替换的模拟模型”不需要 API Key 也能运行。代码结构完全按自建框架的模块方式来组织方便后续替换为真实大模型。支持工具注册、会话记忆、简单意图识别。3.1 项目结构agent_framework/ ├── __init__.py ├── model.py # 模型层统一接口包含一个模拟模型 ├── tools.py # 工具层注册与执行 ├── memory.py # 记忆层存储短期会话 ├── agent.py # Agent 主循环 └── main.py # 演示入口这个结构是自建框架最基础的形态。后面要扩展长期记忆、规划、权限控制都是在对应模块里增加能力而不是推翻重写。3.2 模型层代码文件路径agent_framework/model.pyfrom typing import List, Dict class BaseChatModel: 模型层统一接口 def chat(self, messages: List[Dict[str, str]]) - str: raise NotImplementedError class EchoChatModel(BaseChatModel): 模拟模型用于本地演示不真正调用大模型。 为了演示工具调用效果这里用一个简单的规则模型 - 如果输入中包含天气返回天气工具调用指令。 - 如果输入中包含计算返回计算工具调用指令。 - 如果输入中是纯文本则直接回复原文。 def chat(self, messages: List[Dict[str, str]]) - str: last_content messages[-1][content] if 天气 in last_content: return TOOL_CALL: get_weather if 计算 in last_content: return TOOL_CALL: calculator return f模拟模型回复{last_content}这里接口的设计是为了将来替换成真实模型。后续可以用 LangChain 之外的方式或者直接调用 OpenAI 兼容接口只需要让chat方法返回真正的模型输出。3.3 工具层代码文件路径agent_framework/tools.pyfrom typing import Callable, Dict, Any class Tool: 定义一个可被 Agent 调用的工具 def __init__(self, name: str, description: str, func: Callable): self.name name self.description description self.func func def execute(self, **kwargs) - str: return self.func(**kwargs) class ToolRegistry: 工具注册中心维护工具列表并提供按名称执行的能力 def __init__(self): self._tools: Dict[str, Tool] {} def register(self, name: str, description: str, func: Callable): self._tools[name] Tool(name, description, func) def get(self, name: str) - Tool: return self._tools[name] def has(self, name: str) - bool: return name in self._tools def list_tools(self): return {name: tool.description for name, tool in self._tools.items()}工具层把函数的调用包装为统一的Tool对象。这样做的好处是后续可以在执行工具前后自动加入权限校验、日志记录、成本统计、限流等逻辑而不需要改动每个业务函数。3.4 记忆层代码文件路径agent_framework/memory.pyfrom typing import List, Dict class ConversationMemory: 短期会话记忆保存对话消息列表 def __init__(self): self.messages: List[Dict[str, str]] [] def add_user_message(self, content: str): self.messages.append({role: user, content: content}) def add_assistant_message(self, content: str): self.messages.append({role: assistant, content: content}) def add_tool_result(self, tool_name: str, result: str): self.messages.append({ role: tool, name: tool_name, content: result, }) def get_all_messages(self) - List[Dict[str, str]]: return self.messages短期记忆就是消息列表在真实接入大模型时需要根据模型服务的消息格式做一次转换。这里保持独立是为了不让业务代码依赖具体的模型协议。3.5 Agent 主循环文件路径agent_framework/agent.pyfrom .model import BaseChatModel from .tools import ToolRegistry from .memory import ConversationMemory class Agent: 最小可运行的 Agent 主循环 def __init__(self, model: BaseChatModel, tools: ToolRegistry, memory: ConversationMemory): self.model model self.tools tools self.memory memory def run(self, user_input: str) - str: # 1. 保存用户输入 self.memory.add_user_message(user_input) # 2. 调用模型获取下一步动作 response self.model.chat(self.memory.get_all_messages()) # 3. 如果模型决定调用工具 if response.startswith(TOOL_CALL:): tool_name response.split(:)[1].strip() if self.tools.has(tool_name): # 简化起见演示工具参数固定为空 # 真实场景中模型会返回 JSON 格式的参数 result self.tools.get(tool_name).execute() self.memory.add_assistant_message(f调用工具 {tool_name}) self.memory.add_tool_result(tool_name, result) # 4. 将工具结果再次交给模型生成最终回复 final_response self.model.chat(self.memory.get_all_messages()) else: final_response f未知工具{tool_name} else: final_response response # 5. 保存最终回复 self.memory.add_assistant_message(final_response) return final_response这个主循环把核心逻辑串起来了。在真实框架中第 4 步可能需要重新调用模型并把工具结果作为上下文传入如果工具结果需要二次加工也可以把它拼接到提示词中再请求模型。3.6 运行入口与工具实现文件路径agent_framework/main.pyfrom .model import EchoChatModel from .tools import ToolRegistry from .memory import ConversationMemory from .agent import Agent def get_weather(city: str 北京) - str: return f{city} 今天晴气温 22~30 摄氏度。 def calculator(expression: str 11) - str: try: return f计算结果{eval(expression)} except Exception as e: return f计算失败{e} if __name__ __main__: # 初始化工具注册中心 registry ToolRegistry() registry.register(get_weather, 查询天气, lambda: get_weather()) registry.register(calculator, 数学计算, lambda: calculator()) # 初始化模型、记忆、Agent model EchoChatModel() memory ConversationMemory() agent Agent(modelmodel, registry, memory) # 运行两轮对话验证记忆是否生效 print(agent.run(今天北京天气怎么样)) print(agent.run(顺便计算一下 11 等于几)) print(memory.get_all_messages())这里我故意省略了一个细节Agent的构造参数中第二个参数应该是registry而不是位置传model, memory为了保持一致的变量名我改正一下。修正后的入口if __name__ __main__: registry ToolRegistry() registry.register(get_weather, 查询天气, lambda: get_weather()) registry.register(calculator, 数学计算, lambda: calculator()) model EchoChatModel() memory ConversationMemory() agent Agent(modelmodel, toolsregistry, memorymemory) print(agent.run(今天北京天气怎么样)) print(agent.run(顺便计算一下 11 等于几)) print(memory.get_all_messages())3.7 运行结果在项目根目录执行python -m agent_framework.main预期输出类似模拟模型回复北京 今天晴气温 22~30 摄氏度。 模拟模型回复计算结果2 [ {role: user, content: 今天北京天气怎么样}, {role: assistant, content: 调用工具 get_weather}, {role: tool, name: get_weather, content: 北京 今天晴气温 22~30 摄氏度。}, {role: assistant, content: 模拟模型回复北京 今天晴气温 22~30 摄氏度。}, ... ]可以看到Agent 已经能把“用户输入 - 模型决策 - 工具调用 - 模型总结”这个闭环跑通了。虽然这个示例很简陋但它已经具备了一个智能体框架最核心的骨架。你可以在EchoChatModel里把模拟逻辑替换成真实的大模型接口在Tool执行前加入权限校验在memory里加入向量检索这样就逐渐演化为真正可用的自建框架。4. 从“能跑”到“可上线”框架需要补齐的工程能力上面的最小代码只解决了一个问题让 Agent 能跑起来。如果你打算在项目中自建智能体框架那么还需要补齐大量的工程能力。这才是自建框架真正的门槛。4.1 动态工具参数解析真实场景中模型返回的不只是“TOOL_CALL: tool_name”而是一段 JSON里面包含工具名称和参数。你需要定义一套工具参数 Schema让模型理解工具要什么参数再在代码里把模型返回的参数安全地传给工具函数。参数解析的常见做法是引入 JSON Schema。比如calculator工具的声明可以是{ name: calculator, description: 数学计算工具, parameters: { type: object, properties: { expression: { type: string, description: 要计算的数学表达式 } }, required: [expression] } }在代码里你可以用一个通用的parse_tool_call函数把模型输出转成结构化参数。这里的关键点是参数必须经过严格校验不能直接把模型输出丢给eval()等危险函数。4.2 工具调用的安全边界这一点必须单独强调。当你允许智能体调用工具时你实际上是把系统能力开放给了模型。如果工具包含数据库操作、文件删除、发送消息、调用支付接口等高风险操作就必须加入安全控制策略。建议至少做到所有工具执行前检查用户权限。高风险工具要求二次确认或审批。工具执行结果进行脱敏处理。在测试环境先验证工具执行链。所有工具调用记录审计日志。自建框架在这方面的价值就体现出来了你可以为每一种工具类型定制安全策略而不是在一个通用框架里到处找钩子。4.3 记忆的持久化与检索如果在多轮业务中使用 Agent短期记忆是不够的。你需要把记忆持久化到数据库并在必要时检索历史相关片段。最简单的实现是给ConversationMemory增加一个save_to_db方法和load_from_db方法。更进一步的方案是引入向量数据库把消息文本转成 embedding 向量在做决策时把相似的记忆片段注入到提示词中。自建框架时记忆模块不要一开始就引入向量库。先用数据库表存历史消息按会话 ID 或用户 ID 查询已经能解决大部分业务问题。4.4 可观测性和日志体系生产环境中智能体的每一次决策和工具调用都应该能够被追踪。建议打印或记录以下信息请求 ID、会话 ID、用户 ID。每次模型调用的输入和输出。工具名称、参数、耗时、结果。异常信息和重试次数。成本估算Token 消耗。自建框架意味着你可以完全控制这些日志的字段和存储格式。对接内部监控系统时不需要依赖开源框架自带的日志扩展点。4.5 限流与重试大模型接口通常有调用频率限制和超时风险。框架需要提供一个统一的请求入口来处理接口超时重试。超频后的退避策略。连续失败的熔断。异步队列削峰。在自建框架中这一步通常放在模型层而不是放在每个业务调用方。5. 自建框架和开源框架怎么选一张表看懂取舍回到文章开头的问题自建真的无价值吗答案显然不是。但自建也不应该盲目。下面我把常见的选型思路整理成一张表方便你结合项目情况判断。判断维度适合用开源框架适合自建框架业务定制化程度低业界通用场景多高内部系统深度耦合安全合规要求中低按通用方案即可高需要精细控制每个节点团队技术能力业务开发为主有算法、后端基础好维护人力不愿意花时间维护框架有专职或半专职维护人模型接入数量需要快速对接多种模型固定使用一两个模型超长时间迭代项目短期验证性质长期战略项目可观测需求基础日志即可需要深度审计、链路追踪这里的核心不是“自建”还是“开源”哪个更好而是你的项目更依赖哪一类价值。如果你需要的是“快速验证理念、集成大量第三方能力”那就老老实实用开源框架如果你的团队已经对业务理解得非常清楚而开源框架里想实现一个简单的内部权限拦截都要绕来绕去那自建反而更高效。一个常见的折中方案是底层模型调用和向量检索使用成熟的 SDK上层业务编排、工具调度、权限控制、记忆结构由团队自研。这套组合既能复用社区能力又能保证核心逻辑可控。6. 自建智能体框架的常见问题与排查思路在实际自建过程中有几个问题几乎必然遇到。下面整理成表格方便快速排查。问题现象常见原因解决思路模型频繁调用错误工具工具描述不清晰、参数 schema 有歧义优化工具描述增加最少示例测试不同提示词模板工具返回结果没进入模型上下文记忆模块没有保存 tool 消息或者消息格式与模型要求不一致检查消息 role 字段确认模型 API 是否支持tool角色多轮对话后回答质量下降短期记忆长度增长超出模型上下文限制加入消息裁剪策略用滑动窗口保留最近 N 条或做摘要压缩工具执行慢导致 Agent 超时工具本身耗时或重试策略不合理把同步调用改为异步为工具设置最大执行时间模型返回非 JSON 格式提示词没有约束输出格式或模型版本能力不足使用结构化输出功能或增加格式纠正重试逻辑线上执行了风险操作工具缺少权限校验和审批立即回滚/告警同时为工具执行链加入拦截点设置审计日志还有一个很隐蔽的问题当自建框架中的提示词散落在不同模块时后续调整会非常痛苦。建议把所有提示词统一放到一个prompts.py或配置中心中至少要做到提示词可配置、可版本回溯。7. 自建智能体框架的工程建议与最佳实践最后把我这几年的工程经验总结成几条可执行的建议。如果你决定在团队里自建智能体框架建议严格按这些原则推进。7.1 先从业务闭环开始而不是从框架抽象开始不要第一步就设计一个万能框架。先找到一到两个真实业务场景把最小闭环写出来。当一个业务跑通后再提取公共模块。框架是业务代码重构出来的产物而不是凭空设计出来的。7.2 用接口隔离外部依赖模型服务、向量库、数据库、监控系统都要通过接口隔离。这样替换实现时不会影响上层业务。尤其是大模型服务厂商和版本切换非常频繁统一接口能显著降低迁移成本。7.3 把工具调用协议作为一等公民工具调用是智能体框架中最容易出错的部分。建议设计独立的工具注册、参数解析、执行、日志模块。不要让业务函数直接暴露给模型而是通过框架层做统一包装。7.4 预留审计与可观测位置哪怕是最小自建框架也要在关键位置埋点。每一次模型请求、工具调用、异常结果都应该输出结构化日志。不要等到线上出问题后再去补日志那样会非常被动。7.5 保持安全最低权限原则给工具分配权限时遵循“最小够用”原则。能用只读查询就不要给写权限能限制单次执行就不要开放批量执行能在一台隔离机器上执行就不要在生产主流程中直接调用。任何工具调用都必须可回滚、可审计。7.6 不要把模型能力当成确定性逻辑模型输出有概率性工具调用可能不稳定。框架层要加入容错机制重试、降级、人工介入通道、默认答案兜底。业务上也要对智能体失败路径有预期避免因一次模型异常导致整体服务不可用。8. 总结自建智能体框架的正确价值现在再回头看看“自建智能体框架无价值”这个论点你会发现它更像是一句提醒而不是定论。真正有风险的不是“自建”而是不知道为什么自建、不设边界地自建、大而全地自建。自建智能体框架的价值在于它能为你提供业务匹配度、安全可控性和长期演进能力。当你处在需要深度定制、安全审计或强业务绑定的场景时自建框架不是重复造轮子而是在构建企业的核心智能基础设施。本文从零写了一个可运行的智能体框架最小闭环涵盖了模型层、工具层、记忆层和主循环。你可以把这个代码作为起点逐步加入参数解析、权限控制、持久化记忆、可观测性等能力。如果接下来打算深入智能体框架开发建议下一个方向研究“多步规划”和“状态管理”这是智能体从玩具走向生产级应用的关键。如果你目前正处于选型期可以带着本文第 5 节的对照表把团队的业务复杂度、安全要求和维护预算都列出来再决定是直接使用开源框架还是走“开源能力 自研编排”的混合路线。无论哪种方式都不要把“自建”本身当成目标真正的目标是让你的智能体在业务中稳定、安全、高效地跑下去。