9.22 那期的 GitHub 热榜，我翻了好几遍，越看越觉得这期特别有代表性。前五名里三个项目，本质上都在做同一件事：给 AI agent 造地基。放在一年前，热榜前排通常被"当天就能跑出惊艳 demo"的应用型项目占领，现在风向明显变了，大家开始认真对待让 agent 真正干活这件事了。

先说结论：如果你现在只盯着模型能力是不是又涨了一截，那你可能已经慢了半拍。模型确实还在进步，但真正卡住 agent 落地的，早就不是"谁家模型更聪明"，而是模型外围那套工程设施——编排、工具协议、记忆、观测、并发控制。这篇文章我会先拆解这波热榜信号和"地基"具体包括什么，再讲怎么从热榜里挑项目，最后给一条从 0 到 1 搭建 agent 的实操路径，以及一堆我实际踩过的坑。

1. 9.22 热榜上的信号：造工具的比用工具的还高调

1.1 三个"地基"项目身上共有的三个特征

我盯着这三个项目看了很久，发现它们身上有非常明显的共同画像。搞懂这个画像，比记住项目名更有用。

第一个特征，它们不解决"单次对话"，解决"持续任务"。普通聊天只需要一次模型调用，返回一段文本就结束；agent 要解决的是"给定一个目标，自己拆步骤、调工具、看结果、失败重试、最后给结论"这整个循环。所以你会发现这些项目动辄在做状态管理、循环控制、分支路由，本质上是在做一个可编程的运行时，而不是一个聊天接口。看 README 里的架构图，聊的是图、状态、节点、边，不是"一句话唤醒"。

第二个特征，模型中立。真正的地基项目不会绑定某一家模型。它们会尽量把模型抽象成接口：OpenAI 能接、开源模型能接、国产模型也能接。为什么？因为所有上生产的人都知道，模型要换、要降级、要多路备份，绑定死一家等于把地基盖在流沙上。

第三个特征，上来就谈生产环境。README 里不再是"给你看个炫酷 demo"，而是大段讲并发怎么扛、失败怎么恢复、调用怎么追踪、权限怎么隔离、观测怎么接入。这说明作者是拿它当基础设施写的，目标用户是一线开发者和架构师，不只是追新族。

1.2 从"秀 demo"到"铺管道"的拐点在哪

2023 年那波 agent 热潮把大家刺激得不轻，但冷静下来后发现，自治 agent 多跑几步就容易死循环——目标拆得稀碎、工具调用错乱、中间步骤一丢就不知道在干嘛。问题不在模型，而在模型外面那套脚手架。

我记得当时很多群里都在讨论 agent 为什么会迷路。最后得出的结论很一致：单次模型调用是概率性的，气质再好的概率也还是概率；而系统设计必须是确定性的，得靠代码保证流程可控、状态可恢复、失败可处理。当 agent 要连续调用多个工具、处理中间结果、在失败后重试、在并发下不串线，它就不再是 prompt 工程问题，而是一个分布式系统问题。分布式系统有的那堆烦恼，agent 基础设施一个不少。

所以热榜上开始密集出现编排框架、工具协议、记忆存储、可观测性组件。这些不是模型本身，而是让模型能安全、稳定、可追踪地干活的那层管道。9.22 这期热榜，不过是在把这个趋势放大给你看。

1.3 为什么地基型项目总能在热榜待得久

应用型项目引爆得快，冷却得也快。一个 App 类 repo 上了热榜，可能一周就被遗忘，因为大家玩完 demo 就散了。地基型项目不一样，star 增长看上去慢一点，但一旦形成生态会长尾很久，因为它是反复被依赖的。开发者追热榜不是追热闹，是要提前半年看到趋势。当热榜上同时出现好几个 agent 基建项目，说明行业已经从"要不要用 agent"进入了"怎么批量造 agent"的阶段。

这也是我在开头说"这个信号比模型刷榜重要"的原因。单点技术突破需要运气，基础设施密集出现需要的是真实需求，而需求是会持续发酵的。

2. AI agent "地基"到底包括哪几层

"给 AI agent 造地基"听起来像口号，落到代码上其实是四层问题。我按自己习惯的方式拆给你看。

2.1 编排层：决定 agent 是"单线话痨"还是"多角色团队"

编排层解决的是"agent 怎么把任务一步步做完"。最早大家写 agent 就是 while 循环里反复调模型，直到模型说"我做完了"。这当然能跑，但一旦要加分支、加人工确认、加并行子任务、加失败重试，while 循环就乱了。

所以有了 LangGraph、AutoGen、CrewAI 这类框架。它们把 agent 流程定义成有状态的图：节点是要执行的逻辑，比如调模型、调工具、查数据库；边是控制流，成功走哪、失败走哪、需要人确认时挂起。打个比方，模型是演员，工具是道具组，编排层是导演。演员再会演，导演不喊卡，戏就拍不完。

给初学者一个判断标准：如果你只需要一问一答，编排层对你来说是过度设计；如果你的 agent 要连续做几件事、还要看中间结果调整下一步，那编排层就是刚需。

2.2 工具层：MCP 和函数调用把"会说话"变成"会动手"

模型只会输出文本，要让它操作外部世界，必须走工具。目前主要是两条路。

一条是函数调用。模型在输出里声明"我要调用某个函数，参数是什么"，平台拿到声明后帮你执行。这条路各家模型厂商都有自己的实现，OpenAI 铺得最早，现在主流模型基本都跟进了。

另一条是 MCP，也就是 Model Context Protocol。可以把它理解成工具界的 USB-C：以前每个 agent 和每个工具之间都要单独适配，有了统一协议之后，一个 MCP server 写一次，任何支持 MCP 的 agent 都能直接插上。这条赛道上已经出现大量 server 端 SDK 和工具网关，是基建里最热闹的方向之一。

个人感受是：函数调用解决"怎么调一个函数"，MCP 解决"怎么让所有 agent 都能调所有工具"。后者才是地基，因为它把工具做成了可插拔的标准件。

2.3 知识与记忆层：没有记忆的 agent 只有"七秒脑容量"

模型上下文窗口再大，也装不下企业的知识库，更记不住用户上周说过什么。所以 agent 得有外部记忆。

短期记忆靠 checkpointer 和会话状态保证：对话进行到一半挂了，重连还能接着聊。长期记忆靠向量库加 RAG：文档切片、向量化、存进 pgvector、Milvus 或 Chroma，用户提问时先检索、再让模型基于检索结果作答。

一批做 agent 记忆的项目，本质上是把人脑的工作记忆和长期记忆做了一个软件版拆分。工作记忆短小、昂贵、易失，长期记忆大、便宜、可检索。地基项目要做的，就是给模型配上这两种记忆。

2.4 观测与治理层：agent 再聪明，也得有人看着

微服务火的时候，大家发现没有监控的微服务就是定时炸弹。现在 agent 也一样，没有观测的 agent 就是黑箱。模型是概率输出，它可能在第五轮突然开始胡说，或者调用工具传错参数，没有追踪你连问题出现在哪一轮都定位不到。

观测层解决三件事：记录，也就是每一轮 prompt、模型回复、工具调用参数和结果；量化，也就是 token 成本、延迟、成功率；回放，把失败的那次交互完整 dump 出来，定位是哪一步出了错。Langfuse、Phoenix、LangSmith 这类项目干的就是这个。别小看这一层，后面我会专门讲，agent 上线前不接可观测性，等于闭眼开高速。

把四层整理成一张表，方便对照：

这四层没有哪一层是模型自己能搞定的，全是工程问题。所以"造地基"本质上是在补工程课。

3. 拆几个典型"地基"项目：看懂各自在补哪块短板

热榜上这类项目翻来覆去就几个方向，我挑代表讲讲。重点不是让你背项目名，而是学会看它解决的是哪一层的问题。

3.1 编排框架类：LangGraph 和它的同伴们

LangGraph 是 LangChain 生态里的编排框架，特点是能把 agent 流程画成一张可以落盘的图，状态、循环、分支都是代码对象，还支持 checkpointer，可以中途挂起、恢复。适合需要精细控制流程的团队。

AutoGen 偏多智能体对话，把多个角色放进一个对话场互相协作，研究员、写码的、审码的各司其职。适合模拟几个 agent 互相讨论、迭代输出的场景。

CrewAI 走"角色化团队"路线，更贴近业务人员的心智。我不关心底层图结构，只想定义谁做什么事。上手快，但精细控制能力相对弱。

三者没有绝对优劣，只有匹配度。我见过做金融研报解析的团队从 CrewAI 迁到 LangGraph，因为需要明确的分支容错；也见过运营团队用 CrewAI 两周就把周报 agent 跑起来。选哪个，取决于你对流程可控性的要求有多高。

3.2 工具与沙箱类：让 agent 真正"碰"外部世界

模型要执行代码，但不能让它直接跑在你的内网服务器上，否则一个 prompt 注入就能让你欲哭无泪。于是沙箱成了地基：把 agent 生成的代码放进隔离环境执行，返回结果。

典型代表有 smolagents 这类轻量框架，主打"让模型自己写代码完成任务"，代码执行和 Python 脚本结合很紧，适合数据分析类任务。还有专门做云端沙箱的项目，提供按需启动的隔离容器，给 agent 一个独立工作区。

这类项目解决的是很容易被忽略的问题：权限边界。Agent 有工具，不代表它可以为所欲为。沙箱就是给 agent 划出一块"能碰的地盘"。国内很多做 agent 中台的团队，到最后都会在这一层花大力气，因为安全边界不过关，业务部门根本不敢让 agent 碰真实系统。

3.3 记忆与 RAG 类：把"短期记忆"变成"长期记忆"

纯靠模型上下文，agent 的长期记忆是假的，上下文窗口用完，前面的事就忘了。RAG 类项目解决的是怎么把企业文档变成模型可检索的知识。

这个方向的隐藏难点在切片策略和检索质量。很多人以为 RAG 就是"文档丢进向量库完事"，实际上 PDF 怎么切、标题层级怎么保留、表格怎么处理、检索回来怎么重排，都直接影响回答质量。所以热榜上的记忆类项目，很多都在把切分、向量化、检索、重排这些步骤工程化和调优。

顺嘴提一句：别一上来就自建向量数据库。数据量只有几万条的话，用现有关系库加个向量插件就行；等量级上去了再考虑独立向量库。地基不是越重越好，是越合适越好。

3.4 Java 一侧也在动：Spring AI 带来的信号

如果你是个 Java 工程师，可能会觉得上面这些 Python 项目离自己很远。实际上这波造地基已经跨到 Java 生态了，Spring AI 就很典型。

Spring AI 提供类似 LangChain 的抽象：模型接入、prompt 模板、结构化输出、agent 支持，以及跟 Spring Boot 一脉相承的工程化能力。它的意义不在于跟 LangChain 比谁功能多，而在于：当主流企业级框架开始提供 agent 基建，说明 agent 不只是创业公司和 Python 极客的玩具了，它要进企业的存量系统。身边搜"spring ai agent"的人已经不少，说明这趋势正在被验证。

做技术选型时，越接近现有技术栈越容易被接纳。全团队都是 Java，强行上一套 Python agent 编排，光运维就够喝一壶。所以地基不是 Python 的专利，谁的技术栈里都要有对应的地基。

4. 热榜不等于适合你：挑项目的五个过滤条件

每次热榜出来，大家第一反应是"star 好多，牛逼"，然后收藏夹就告急。但热榜只能说明很多人关注，不能说明适合你的业务。我自己挑项目有一套固定流程，拆开讲。

4.1 先看"活性"，再看 star

star 是存量，活性才是增量。一个 5 万 star 却一年不更新的项目，不如一个 5000 star 但每周都有 commit 和 release 的项目值得跟。

我会重点看几件事：最近一次 commit 时间、最近 release 时间、issue 关闭速度、新增贡献者数量。特别要去看 issue 里那些 bug 反馈是不是有人回复。有人回，说明作者真在维护；全是机器人自动 close，说明这项目已经半只脚进棺材了。

4.2 license 决定你能否商用

很多人在收藏那一步就忽略了 license。MIT、Apache-2.0 这类宽松协议，商用基本没问题；GPL 有传染性，代码要闭源分发就得认真掂量；还有些项目用的是 source-available 协议，比如部分项目改用的 Elastic License、BSL、SSPL，代码能看到，但商用限制很明确，云厂商尤其要注意。

判断方法很简单：进仓库点开 LICENSE 文件，看不懂就搜协议对比。这花不了五分钟，但能避免将来法务找上门。我见过不止一个团队，模型都调通了才发现协议不允许商用，白白返工。

4.3 文档和 examples 的数量级暴露成熟度

文档是最好的过滤器。README 只有一张架构图没有快速开始的项目，大概率还处于作者自己懂、别人用不起来的阶段；有 quickstart、有教程、有大量 examples 的项目，说明作者把"让别人用起来"当成了目标。

我最看重的是 examples 目录。一个框架自己吹得再好，examples 里全跑不通也是白搭。优先选那种 examples 多且立即可运行的项目，这类项目通常已经替你踩了不少坑。

4.4 30 分钟快速验证法

收藏和真正采用之间，隔着一套快速验证流程。我的做法是：

1. git clone 下来，先看 README 里的 quickstart，照着把最小示例跑通。
2. 把默认模型换成我自己要用的模型，确认接口可替换。
3. 加一个自定义工具进去，确认扩展路径走得通。
4. 看日志和追踪，确认失败时可观测。
5. 最后再决定要不要把它放进架构图。

这套流程走完，半小时到一小时，你对项目的理解远超刷十遍 README。热榜项目不是拿来供奉的，是拿来跑通的。

5. 基于 FastAPI + LangChain + LangGraph 从 0 到 1 搭一个能下地干活的 agent

聊完怎么挑，说点动手的。这条路线也是最近热词里反复出现的组合：FastAPI 做服务层，LangChain 做模型和工具抽象，LangGraph 做流程编排。为啥选这组？因为它能覆盖从"能跑"到"能扛"的两个阶段，每一层都可替换。

5.1 为什么是这套组合

FastAPI 解决入口问题：HTTP 接口、并发、参数校验、部署，Python 生态里最省心。LangChain 解决多样性问题：模型、向量库、工具，各家实现都能接进来。LangGraph 解决流程问题：把"调模型、调工具、看结果、再调模型"的循环变成有状态、可恢复的图。

提醒一句别人没说透的点：这三层是解耦的。你完全可以用 FastAPI 加 LangGraph 加裸 OpenAI SDK，不用 LangChain；也可以用 FastAPI 加 LangChain 而不用 LangGraph。想清楚每一块的职责，你才知道优化时该动哪块，而不是一锅端。

顺便说一句，如果你完全不想写代码，用扣子这类低代码平台，或者 Dify 这类开源平台也能搭 agent。那是一条更快的路，但本文讲代码路线，是因为热榜上的地基项目大多落在代码层，理解代码路线才能看懂它们。

5.2 最小骨架代码

先看一个能跑的最小版本。这个 agent 只有一个工具：查服务器时间。模型发现需要时间信息时，会主动调用工具，拿结果再组织回答。

from typing import TypedDict from fastapi import FastAPI from langchain_openai import ChatOpenAI from langchain_core.tools import tool from langgraph.graph import StateGraph, START, END app = FastAPI() # 1. 定义 agent 的全局状态 class AgentState(TypedDict): messages: list # 2. 定义一个工具 @tool def get_server_time() -> str: """返回服务器当前时间，例如 2025-09-22T14:30:00。""" from datetime import datetime return datetime.now().isoformat() # 3. 模型绑定工具 model = ChatOpenAI(model="gpt-4o-mini", temperature=0).bind_tools([get_server_time]) # 4. 模型节点：调用模型 def call_model(state: AgentState) -> AgentState: reply = model.invoke(state["messages"]) return {"messages": state["messages"] + [reply]} # 5. 工具节点：执行模型要求的工具调用 def call_tools(state: AgentState) -> AgentState: last_message = state["messages"][-1] for tool_call in last_message.tool_calls: result = get_server_time.invoke(tool_call["args"]) state["messages"].append({ "role": "tool", "content": str(result), "tool_call_id": tool_call["id"], }) return state # 6. 路由：模型还想调工具就走工具节点，否则结束 def should_continue(state: AgentState): last_message = state["messages"][-1] return "tools" if last_message.tool_calls else END # 7. 把节点和边拼成图 builder = StateGraph(AgentState) builder.add_node("model", call_model) builder.add_node("tools", call_tools) builder.add_edge(START, "model") builder.add_conditional_edges("model", should_continue, ["tools", END]) builder.add_edge("tools", "model") graph = builder.compile() @app.post("/chat") async def chat(text: str): result = await graph.ainvoke({"messages": [{"role": "user", "content": text}]}) return {"reply": result["messages"][-1].content}

这段代码的骨架就是 LangGraph 最核心的东西：状态在节点间流动，模型节点和工具节点通过条件边来回切换，直到模型认为任务完成。后面加工具、加"生成总结"节点，都是在这个骨架上做文章。不同版本 API 有差异，跑之前以官方文档为准，但核心思想不变。

5.3 怎么给它加记忆、加更多工具

上面的骨架把 messages 全放内存里，进程一重启就没了。生产环境起码做两层：短期记忆用 LangGraph 的 checkpointer 把状态持久化到数据库；长期知识用向量库做 RAG，用户提问时先检索相关知识塞进 prompt，再进 agent 流程。

加工具也很简单，再写一个@tool函数，加到bind_tools列表里就行。但工具一多，命名和描述质量就非常关键，因为模型靠 description 判断什么时候该用哪个工具。描述写得不清楚，模型就会乱选。工具描述就是给模型看的 API 文档，值得像写正式文档一样认真对待。

5.4 上线前：并发那第一道坎

本地能跑通只是起点。上之前先想并发。FastAPI 本身是异步的，但模型调用是同步阻塞的，直接用会有坑。两种常见做法：一是把 agent 执行放到 worker 队列里，接口只负责收任务、返回任务 ID，agent 在 worker 里慢慢跑，前端轮询结果；二是用异步模型调用配合连接池，但注意大模型推理耗时本身就长，单请求占着连接会很快耗尽连接池。

"AI agent 怎么扛并发"这个问题没有银弹，核心只有一条：把耗时的 agent 执行和轻量的 HTTP 接口拆开。接口层管收单，worker 层管干活，中间用队列缓冲和限流。这个套路很朴素，但绝大多数并发问题都是因为没做这一层拆分造成的。

6. 造地基时最容易踩的坑

最后集中说说我在实操里吃过的亏。这些是文档一般不写、跑了才知道的东西。

6.1 并发问题往往不是模型的问题

很多人以为 agent 扛不住并发是模型推理慢，其实大多数场景是外围管道先崩：连接数上限、状态读写的锁、轮询把数据库打满。我见过一个内部 agent，模型调用很快，一并发就报错，最后定位是向量存储的连接数没配，和模型一点关系都没有。

所以排查并发时按这个顺序走：入口路由有没有限流和队列、状态存储有没有锁和索引、工具调用有没有超时设置、模型服务本身有没有配额。从管道入手，多数时候能让问题现形。

6.2 上下文会爆炸，token 账单也会爆炸

Agent 每多跑一轮，消息列表就膨胀一点。工具返回一大段 JSON 粘进上下文，下一轮还得再带一遍。几十轮下来，光上下文可能就是几千 token。如果每个请求都无脑传历史消息，账单会涨得莫名其妙。

解决思路是分级：只保留系统提示词、最近几轮消息和必要的历史摘要，长历史存外部记忆，需要时再检索回来。在 agent 循环里加一个"上下文整理"节点，能把成本直接砍掉一大截。我一般会在循环里加清理步骤，超过阈值就压缩历史。

6.3 工具调用不是每次都成功

模型会幻觉，工具调用也会幻觉。它可能生成不存在的参数名，把必填参数漏掉，或者某一步返回异常数据还是坚持继续往下跑。所以每个工具节点都要做校验、超时、错误重试，把工具层的失败显式暴露给模型，让它有机会换条路完成任务。

别假设模型看到报错就知道怎么改。很多时候它看到报错会继续硬试同一个错误参数。这种情况下你需要在工具节点里做熔断：同一种错误连续出现几次就停止调用，把控制权交给人工或预设的兜底流程。

6.4 没有观测就别上线

这是我认为最重要的一条。Agent 逻辑是循环的、状态是累积的，出了错不能靠看代码定位，必须靠 trace：完整记录每一次模型调用的输入输出、每一个工具调用的参数和结果、每一轮路由走向。

我踩过的坑是早期觉得"先跑起来再说"，观测只打了 print。结果线上 agent 回答出问题，用户说错，我却只能看到最终答案，完全不知道是哪一轮开始错的。后来把 trace 接齐，问题定位从猜变成查，效率完全不一样。所以我的建议很直接：agent 上线前，观测先于功能。

最后分享一个我现在养成的小习惯：每周翻热榜的时候，不再问"这个项目好不好"，而是先问"它补的是哪层地基，我现在的系统缺不缺这层"。缺，就认真跑一遍评估流程；不缺，再火也先收藏放着。热榜是给需求发信号的，9.22 这期信号足够明确：AI agent 的竞争，已经从模型的嘴皮子，转移到了地基的深浅。你的系统能扛多少并发、能找回多远的记忆、能在出事后多少分钟内定位问题，这些才是接下来真正拉开差距的地方。