先说结论自建智能体框架无价值这个观点我只同意一半。它合理的部分在于如果团队只是为了“不落伍”而自建框架那确实是重复造轮子但它不合理的地方在于它把“自建框架”和“用 LangChain 这类通用框架”搞成了选择题而真实世界里这个选择取决于你的业务场景、团队能力和工程约束。在这篇文章里我不会劝你“一定要自建框架”也不会劝你“一定要用现成框架”。我会先拆解“无价值论”的隐含假设然后说清楚智能体框架真正解决了什么问题再给出一个可以照抄的最小框架实现。最后你会得到一张判断清单什么情况下自建什么情况下别自建以及如果自建从哪里开始、做到什么程度最合理。如果你最近正在做 Agent 相关项目或者正为“要不要引入现成框架”纠结这篇文章可以给你一个比较务实的决策参考。1. 为什么会出现“自建智能体框架无价值”这种说法先看这个说法是怎么来的。AI Agent 在 2023 年到 2024 年经历了一轮爆发式增长。LangChain 这类框架迅速成为热点随后又有 LlamaIndex、AutoGen、Semantic Kernel 等一批新框架出现。几乎每个技术社区里都有人在讨论 Agent 框架也的确有大量团队在“造轮子”。于是自然出现了反对声音“通用框架已经很成熟了为什么要自己重写”“自建框架容易有 Bug还缺乏社区维护。”“大模型迭代这么快自建框架根本跟不上。”这些话单独看每一句都对。但把它们组合在一起就变成了一个很容易误导人的结论自建智能体框架无价值。问题出在哪里出在这几个论据背后的隐含假设上。第一个隐含假设是通用框架足够稳定且确实适合你的业务。但实际上很多通用框架变更很快API 经常变动有人甚至调侃“一个版本一个写法”。如果你的生产代码已经基于某个大版本做了一堆业务抽象框架升级可能反而不像一开始想象的那么轻松。第二个隐含假设是所有团队的 Agent 需求都是一样的都能用一套通用抽象覆盖。但实际做过的都懂不同业务的 Agent 逻辑差异非常大。比如搜索增强型 Agent、复杂决策型 Agent、多轮客服 Agent、代码生成型 Agent它们对工具管理、状态管理、记忆策略和错误恢复的要求完全不同。通用框架能给你 80% 的通用能力但剩下 20% 的业务逻辑恰恰可能是你产品的核心壁垒这部分就是要深度定制的。第三个隐含假设是团队有足够的时间去学习和消化框架的抽象设计。这往往被低估。LangChain 这类框架的抽象层级非常多从 Prompt、Model、OutputParser 到 Chain、Agent、Tool 再到 Memory、Callback你要写出符合架构预期的代码需要理解它的设计意图。如果你的目标就是快速跑通一个 POC这个学习成本是值得的如果你的目标是上线一个高稳定性的生产系统框架的层层抽象反而会变成排查问题和性能调优的拖累。所以我的判断是“无价值”这个结论过于绝对。更准确的说法应该是自建智能体框架不适合所有人但它对一部分团队和场景来说直接决定了项目能不能走通。2. 智能体框架到底解决了什么问题要讨论自建框架的价值得先回到一个根本问题为什么我们不能直接循环调用大模型 API 来做 Agent很多人第一次写 Agent 就是从几行大模型 API 调用开始的。你问模型一个问题它给你一个答案。这很简单但这并不是 Agent这只是 Chat。真正的 Agent 需要一个循环模型根据用户目标规划出下一步调用一个工具拿到工具结果后重新综合判断再决定下一步直到完成目标。这个循环看起来简单但把它稳定地跑起来会遇到一系列工程问题。2.1 状态管理问题Agent 是多步执行的每执行一步内部状态都会发生变化。当前已经执行到第几步、工具结果是什么、哪些历史信息已经确认、哪些还需要继续追问这些状态都必须被管理起来。没有框架时你需要在每次循环里手动把全部上下文塞给模型一旦循环次数变多上下文很快膨胀token 成本直线上升。2.2 工具编排问题让 Agent 调用外部工具不是把函数列表发给模型这么简单。你需要定义统一工具接口把参数校验、错误处理、超时控制、返回结果规范化和工具鉴权全部包进去。如果工具是 3 个还可以手动 if-else如果有 30 个甚至需要动态地根据用户意图筛选工具手动管理就完全不可控了。2.3 记忆管理问题Agent 需要记住用户对话历史、任务运行中的中间产物、甚至跨会话的长期偏好。这里涉及短期记忆、长期记忆、向量检索、对话摘要等复杂机制。没有框架层支持你很难做好记忆的存取和更新更不用说“遗忘”策略了。2.4 可观测性问题代理应用的排错比传统应用难得多。因为它不是一条直线执行路径每一步的提示词、模型响应、工具结果都可能影响最终输出。如果日志打得不规范出了问题根本无从判断是模型判断错了、工具返回错了还是 Prompt 写错了。下面用一个表格来展示“裸写”和“框架”的差别能力维度直接循环调 API自建最小框架通用大型框架状态管理手动拼上下文维护一个历史列表内置多种 Memory工具调用if-else 硬编码注册中心统一调度大量内置工具集成可观测性print 日志结构化日志集成追踪平台学习成本低中高业务定制性最高高依赖抽象设计生产稳定性最差可控取决于版本稳定性这张表是理解“自建框架价值”的核心。你会发现自建框架既不是最差的选项也不是最好的选项它处在“裸调用”和“大型通用框架”之间的位置。它要解决的核心问题是让 Agent 的多步执行过程变得可控、可观测、可维护而不是追求功能大而全。3. 自建框架 vs 通用框架不是对错问题是约束匹配问题很多讨论把问题简化成“自建对不对”。这不是对错问题这是约束匹配问题。你的团队、业务、阶段不同答案就不同。3.1 通用框架的优势与代价通用框架的最大优势是“开箱即用”。你想给 Agent 加一个联网搜索能力LangChain 这类框架里可能已经封装了对应工具你想接一个向量数据库它也有现成的封装。上手速度快生态广社区讨论多遇到问题更容易搜到答案。但通用框架的代价同样明显。首先是抽象泄漏问题。听起来越简单的框架层在运行到某些边界场景时越容易把底层细节暴露给你。你需要通读源码才能知道某个 Callback 在什么时候触发某个 OutputParser 为什么吞掉了异常。其次是版本兼容问题框架升级往往带来 Breaking Change如果团队没有专人跟进迟早会踩坑。第三是体积问题为了通用性引入的大量依赖会让系统变重排查问题链路变长。3.2 自建框架的优势与代价自建框架的核心优势只有一句话代码是你的边界是你的复杂度也是你的。你可以只保留业务必需的模块去掉一切不用的抽象。上线后排查问题时你可以直接打开自己的代码而不是在第三方框架的多层调用栈里挣扎。它的代价也很直接。第一工程量不小。即便一个最小框架也要处理工具注册、模型调用、上下文管理、异常处理、日志等一堆琐碎问题。第二持续维护成本。不是写完上线就完了模型 API 变化、工具协议调整、新需求加入都需要有人持续跟进。第三对团队有要求。它需要团队里至少有人理解智能体运行原理能把循环、记忆、工具调度这些概念设计成高质量的工程代码。3.3 什么时候应该自建满足下面任意一条就可以认真考虑自建你的 Agent 是核心业务不是辅助功能。比如你是做垂直领域智能客服的Agent 的编排逻辑就是产品灵魂把所有逻辑建立在第三方框架的抽象上风险很高。你的领域规则非常特殊。比如金融风控、医疗问诊、私有化部署等场景对权限、审计、合规有严格要求通用框架的黑盒行为无法满足审计需求。你只需要一个极小的 Agent 能力。比如只是“大模型 两个工具 一次循环”这种规模用通用框架纯属杀鸡用牛刀。你的团队有意愿也有能力维护框架代码。自建框架不是一锤子买卖如果你能像对待业务代码一样维护它这个成本就是可接受的。3.4 什么时候不应该自建反过来下面这些情况就不要自建你要验证一个想法两天内出 POC。你的 Agent 逻辑非常标准通用框架已经提供了成熟链路。团队没有人能长期维护框架代码离职后直接断档。你需要的 Agent 能力只是简单的“调用大模型 一次工具调用”根本达不到框架级复杂度。判断是否自建真正看的是“业务核心”和“团队能力”不是哪个更高级。框架本身没有价值它服务的目标才是价值。4. 自建智能体框架的最小核心模块如果你决定自建不要想着一步到位。自建框架的姿势很重要很多人失败是因为一上来就想做一个完整平台结果做了一堆用不上的功能。一个最小可用的智能体框架只需要四个核心模块。4.1 工具注册中心工具注册中心解决的是“模型要调用工具代码怎么找到工具”的问题。它把工具函数和元数据工具名、描述、参数 schema统一管理起来。这样做的好处有三个工具列表可以动态生成随时加入新工具不需要改 Agent 主循环。模型看到的工具描述和代码中的实际执行函数分离可以独立调优描述。工具调用前后可以在统一入口做日志、鉴权、限流。4.2 Agent 主循环Agent 主循环是框架的心脏。它的任务是把“调用大模型”“解析模型决策”“执行工具”“把结果回传模型”这几件事串起来。最简单的主循环就是 ReAct 模式Thought模型思考→ Action模型决定调用什么工具→ Observation执行工具后得到观察结果→ 再回到 Thought。主循环必须做三件事限制最大步数避免模型陷入死循环捕获工具执行异常防止单个工具错误中断整个 Agent控制上下文长度避免多轮循环后 token 爆炸。4.3 上下文与记忆管理Agent 的记忆分为两层对话历史和运行中间态。对话历史要控制长度不能让无限增长塞满上下文运行中间态是当前任务里的状态比如用户需求、已确认的信息、待确认信息。最小实现里你可以用两个列表历史列表负责存对话状态字典负责存运行中间态。框架提供的价值是封装好“追加历史、裁剪历史、生成模型输入”这些操作业务代码只需要调用接口。4.4 日志与可观测性很多人自建框架会忘记日志这是大忌。Agent 应用的日志和普通应用不一样你需要按“一次完整执行”为单位记录用户输入是什么、模型每一步的输出是什么、每一步调用了哪个工具、传入参数是什么、工具返回结果是什么、花费多少 token、耗时多少。有了这些日志你才能在用户反馈“结果不对”时回放整个 Agent 推理过程判断问题出在规划、工具还是模型。5. 自建一个最小可运行的智能体框架下面我们用 Python 写一个最小可执行的智能体框架。这个框架麻雀虽小但具备工具注册中心、Agent 主循环、上下文管理三个核心能力。我会控制代码复杂度以便你直接复制到本地运行。5.1 环境准备建议使用 Python 3.10 或以上版本。需要安装 openai SDK用它调用 OpenAI 兼容协议的大模型接口。pip install openai如果你的大模型服务走的是 OpenAI 兼容格式比如很多国内模型服务商都提供兼容 endpoint可以通过环境变量配置不需要改代码。5.2 工具注册中心第一步先实现工具注册中心。文件路径agent_core.py# agent_core.py import json from typing import Any, Callable, Dict, List class ToolRegistry: 工具注册中心统一管理 Agent 可调用的工具。 def __init__(self) - None: self._tools: Dict[str, Callable] {} self._schemas: Dict[str, Dict[str, Any]] {} def register(self, name: str, description: str , **parameters: Any): 注册一个工具参数通过关键字参数描述。 def decorator(func: Callable) - Callable: self._tools[name] func self._schemas[name] { name: name, description: description, parameters: parameters, } return func return decorator def list_tools(self) - List[Dict[str, Any]]: 返回全部工具描述用于拼接到 Prompt 中。 return list(self._schemas.values()) def call(self, name: str, args: Dict[str, Any]) - str: 调用指定工具并把结果统一转为字符串。 if name not in self._tools: raise ValueError(f工具不存在: {name}) result self._tools[name](**args) if isinstance(result, (dict, list)): return json.dumps(result, ensure_asciiFalse) return str(result) registry ToolRegistry() registry.register( get_weather, 查询指定城市的当前天气, city{type: string, required: True, description: 城市名称}, ) def get_weather(city: str) - str: 模拟天气查询接口。 weather_map { 北京: 晴25℃, 上海: 多云28℃, 深圳: 小雨26℃, } return weather_map.get(city, f{city}暂无天气数据)这段代码的核心是register装饰器。你每写一个新工具只需要加上一个装饰器它就会自动进入工具列表。call方法会校验工具是否存在并把工具结果统一字符串化这样无论工具返回的是 dict 还是 list模型都可以直接读懂。5.3 简化 ReAct 主循环第二步实现 Agent 主循环。文件路径agent_loop.py# agent_loop.py import json from typing import Callable, Dict, List from agent_core import registry SYSTEM_PROMPT 你是一个智能助手可以调用工具完成用户请求。 可用工具如下 {tools} 请按以下 JSON 格式输出你的决策不要输出多余内容 {{ thought: 你的推理过程, action: 工具名称如果不需调用工具则为 none, action_input: {{参数名: 参数值}}, final_answer: 如果无需继续调用工具在这里写出最终回答否则为空字符串 }} class Agent: def __init__(self, model_func: Callable[[str], str], max_steps: int 5) - None: self.model_func model_func self.max_steps max_steps self.history: List[Dict[str, str]] [] def _build_prompt(self) - str: tools json.dumps(registry.list_tools(), ensure_asciiFalse, indent2) system_prompt SYSTEM_PROMPT.format(toolstools) messages [{role: system, content: system_prompt}] messages.extend(self.history) return json.dumps(messages, ensure_asciiFalse) def run(self, user_input: str) - str: self.history.append({role: user, content: user_input}) for step in range(1, self.max_steps 1): prompt self._build_prompt() response self.model_func(prompt) try: decision json.loads(response) except json.JSONDecodeError: return f第 {step} 步模型输出不是合法 JSON已终止。原始输出{response} thought decision.get(thought, ) action decision.get(action, none) action_input decision.get(action_input, {}) final_answer decision.get(final_answer, ) print(fStep {step}: thought{thought}) if action none: return final_answer if final_answer else 模型未给出有效答案 if action not in [t[name] for t in registry.list_tools()]: return f模型尝试调用不存在的工具: {action} try: tool_result registry.call(action, action_input) print(fStep {step}: tool{action}, result{tool_result}) self.history.append( { role: assistant, content: json.dumps(decision, ensure_asciiFalse), } ) self.history.append( { role: tool, content: f{action} {tool_result}, } ) except Exception as exc: error_msg f工具 {action} 调用失败: {exc} self.history.append({role: tool, content: error_msg}) return 达到最大执行步数未能完成请求。这个主循环已经具备生产雏形有最大步数限制、有工具存在性校验、有异常捕获。每一步模型输出都会被记录到历史列表中下次循环时模型能看到前一步的工具执行结果这就是 ReAct 模式中最关键的 Observation 回传机制。5.4 接入大模型并运行第三步把 Agent 和真实大模型连接起来。文件路径main.py# main.py import os from openai import OpenAI from agent_core import registry from agent_loop import Agent client OpenAI( api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL), ) def call_llm(prompt: str) - str: 将本地 prompt 转为 OpenAI 格式请求。 messages json.loads(prompt) response client.chat.completions.create( modelos.getenv(LLM_MODEL, qwen-plus), messagesmessages, temperature0.2, ) return response.choices[0].message.content if __name__ __main__: agent Agent(model_funccall_llm) question 北京今天天气怎么样 result agent.run(question) print(f最终回答: {result})这里需要注意示例中使用了json.loads(prompt)因为_build_prompt生成的是 JSON 数组格式的 messages。如果你的模型接口不支持这种格式可以根据实际接口调整。运行前配置环境变量export LLM_API_KEYyour_api_key export LLM_BASE_URLhttps://your-llm-endpoint/v1 export LLM_MODELyour_model5.5 新增工具当你需要加入新工具时不需要改动 Agent 主循环只需要在agent_core.py中追加一个注册函数。# agent_core.py 追加代码 registry.register( calculate_multiplication, 计算两个数字的乘法, a{type: number, required: True, description: 乘数}, b{type: number, required: True, description: 被乘数}, ) def calculate_multiplication(a: float, b: float) - float: 简单乘法计算。 return a * b这就是工具注册中心的价值Agent 能力扩展从“改主流程代码”变成了“加一个函数”。6. 运行结果与效果验证执行命令python main.py预期输出大致如下Step 1: thought用户想查询北京的天气我需要调用 get_weather 工具。 Step 1: toolget_weather, result北京晴25℃ 最终回答: 北京今天天气晴朗气温 25℃。判断运行成功有三条标准模型没有在第一步直接输出最终答案而是正确识别出需要调用工具。工具注册中心成功执行了get_weather并把结果回传给模型。模型在拿到工具结果后基于观察结果生成了最终回答。如果模型第一次输出就是最终回答说明 Prompt 中的工具描述没有生效或者模型没有理解工具调用的 JSON 格式。此时优先检查SYSTEM_PROMPT中的工具列表是否拼接正确以及模型温度是否过高导致输出格式不稳定。如果模型尝试调用不存在的工具检查工具注册名是否正确以及registry.list_tools()中是否能看到该工具。7. 自建智能体框架常见问题与排查思路自建框架的过程一定会遇到问题。下面这几个是最常见的我直接给出排查路径。问题现象可能原因排查方式解决方案模型输出不是合法 JSONPrompt 格式不清晰、模型温度过高打印模型原始响应检查输出前后缀降低 temperature在 Prompt 中更明确要求只输出 JSON增加 few-shot 示例模型总是直接回答不调用工具工具描述过于简略、模型不理解接口检查工具列表是否正确拼入 Prompt把工具名改为更直观的动词短语优化工具描述把“做什么、参数含义、返回什么”写清楚Agent 陷入循环达到最大步数工具结果没有给模型有效新信息打印每一步的 history观察模型是否重复决策在工具返回中补充更多信息提高 max_steps优化推理 Prompt工具结果太大上下文爆炸工具返回超长 list 或大文本查看日志中的 tool_result 长度对工具结果做截断只返回关键字段使用摘要工具调用失败但 Agent 不报错异常被吞掉模型误以为成功检查异常捕获分支的日志在异常消息中加入错误类型和堆栈让模型看到“调用失败”再决定重试还是放弃并发调用状态混乱多个请求共用了同一个 Agent 实例的 history检查代码中的实例生命周期每个请求创建独立 Agent 实例共享资源只放工具注册中心这里要特别提醒一个很多人踩过的坑不要把工具的真实报错直接拼到给模型的 Prompt 里。如果工具内部抛出了数据库连接串、内部表名这类敏感信息这些内容会被模型原样读到甚至可能被用户的后续问题诱导出来。更稳妥的做法是对工具异常做一层脱敏封装给模型一个“安全失败”的消息。8. 自建不是最终目的工程化建议与最佳实践当你决定自建时真正重要的事情并不是写一个能跑的循环。上面这个最小框架其实只是幼儿园水平。真正决定自建框架成败的是能不能把工程化做好。8.1 不要一次做太全很多人自建框架失败不是能力不够而是控制不住范围。一上来就想实现多智能体协作、记忆向量化、Flow 编排、可视化监控结果三个月后才把 demo 跑通。我建议按这样的顺序扩展第一阶段直接用大模型 API 工具函数不引入框架。第二阶段抽出工具注册中心加入最简 ReAct 循环。第三阶段加入结构化日志、上下文裁剪、工具结果缓存。第四阶段按需加入长期记忆、人机确认、多工具并行等高级能力。每个阶段都应该是可运行的。不要指望一步到位。8.2 工具接口必须 Schema 化工具注册中心的接口设计直接决定了框架好不好扩展。给每个工具定义清晰的参数 schema不只是为了拼 Prompt更是为了后续做参数校验、自动生成 API 文档、以及模型函数调用Function Calling格式转换。工具描述要反复调试因为这个描述直接影响了模型对工具的理解好的描述能让工具被选中的概率显著提升。8.3 日志先行排错不慌如果框架没有日志一旦线上出问题就只能靠猜。一个 Agent 执行至少应该记录五类信息用户原始输入、模型每一步输出、工具调用参数与结果、各步耗时与 token 消耗、最终回答。建议把这些结构化日志写入独立的文件或日志平台方便回溯整次执行链路。8.4 与大模型实现解耦自建框架时最容易犯的错误是把框架和某一家模型 API 强绑定。今天你用 A 模型写好了工具调用逻辑明天换成 B 模型可能输出格式完全不同。比较好的做法是在框架内部定义一个统一的model_func接口上面代码里的call_llm就是这种思路。这样更换模型时只需要改一个适配函数。8.5 安全边界不能省Agent 能调用工具就意味着它能触及你的系统能力。如果你给 Agent 注册了一个“删除数据库记录”的工具那就必须考虑工具级鉴权。最简单有效的做法是高危工具必须加人工确认所有工具调用的结果都要做数据脱敏框架日志中对账号、密码、token 等敏感字段打码。8.6 避免“自建一切”回到标题。自建框架有价值不代表你要自建一切。向量数据库、消息队列、API 网关这些基础设施如果已经有了成熟方案直接用即可。自建的范围应该严格限定在“业务核心编排层”也就是那些决定了你的 Agent 和别人的 Agent 不一样的部分。9. 结论回到开头的问题自建智能体框架有没有价值我的答案是有但价值不在框架本身而在框架帮你沉淀下来的业务理解和工程能力。如果你的 Agent 只是“模型一个工具”的玩具场景直接用大模型 API 或通用框架就够了自建纯属浪费如果你的 Agent 是业务核心涉及大量领域逻辑、工具编排和稳定性要求那么自建一个精简、可控、可观测的编排层可能比在通用框架的抽象里打转更高效。这篇文章里给出的最小框架代码量不大但已经把工具注册、Agent 主循环、上下文管理三个核心模块跑通了。你可以在此基础上按第二节的判断清单评估自己到底要不要自建。如果判断结果是“要”记得从第二阶段开始不要一上来就做平台。最后提醒一句无论自建还是用框架都要保证“换模型不换主流程”“加工具不改主循环”“日志永远完整”。这三点做到位你的智能体项目在工程上就站稳了一半。