1. 从速刷这个词说起hello-agent到底在刷什么第一次看到hello-agent 速刷心得这个标题我脑子里冒出来的第一个念头是这玩意儿能刷什么是刷题、刷任务还是刷某种流程后来把关键词铺开一看——Agent、ReAct、Agent Loop、MCP——基本就明白了这里的速刷指的是快速跑通一个 Agent 的最小闭环把从输入到工具调用再到结果返回的整条链路先打通一遍而不是一上来就啃框架源码。这个思路其实非常务实。现在 agent 相关的框架、协议、概念满天飞agent loop、ReAct、MCP、agent evals、skill 和 agent 的区别……新手很容易陷进先学哪个的纠结里。而速刷的核心逻辑是先让一个能跑的东西跑起来再回头补原理。这跟学 React 的时候先跑一个 create-react-app 再研究 SSR 数据预获取是一个道理先有体感再有体系。hello-agent 这个名字本身就带着最小可运行示例的味道类似编程语言里的 Hello World。它要解决的不是复杂业务而是让你亲眼看到一个 Agent 是怎么接收任务、怎么思考、怎么调用外部能力、怎么把结果拼回来的。适合谁来参考我觉得有三类人一是刚接触 agent 开发、想找个能跑通的起点的人二是写过一些 prompt 但没真正搭过 loop 的人三是想理解 MCP 这类协议到底在链路里扮演什么角色的人。下面我会按先跑通、再拆解、后避坑的顺序把这条速刷路径讲清楚。需要说明的是项目正文和关键词都是空的所以具体实现细节我会基于当前 agent 开发的常见实践来补全并明确标注哪些是通用做法、哪些是我个人的经验判断你照着调的时候按自己环境微调即可。2. 速刷之前先想明白Agent Loop 和 ReAct 到底谁在驱动谁很多人速刷失败不是代码写错了而是脑子里对谁驱动谁没概念。跑起来之后看到日志里一堆 thought、action、observation就懵了。所以这一节先把两个最核心的概念理清楚后面实操才不会晕。2.1 Agent Loop 是骨架ReAct 是其中一种走法Agent Loop 说白了就是一个循环观察当前状态 → 决定下一步做什么 → 执行 → 把执行结果并入状态 → 再观察。这个循环什么时候停通常是模型认为任务完成了或者达到了最大轮次限制。它是个框架性的东西不规定你怎么决定下一步。ReAct 则是这个循环里怎么决定下一步的一种具体范式全称是 Reasoning Acting。它的特点是让模型在每一步先输出一段推理Reasoning再输出一个动作Acting动作执行完拿到结果Observation然后进入下一轮。你可以把 Agent Loop 理解成发动机的曲轴在转ReAct 理解成这一圈里活塞具体怎么点火。我个人的类比是Agent Loop 像 while 循环的骨架ReAct 像循环体里那套先想后做的约定。你完全可以在 Agent Loop 里用别的策略比如纯 function calling、比如 plan-and-execute但 ReAct 是最容易上手、日志最直观的一种所以速刷阶段优先用它。2.2 为什么速刷阶段强烈建议用 ReAct原因有三个都是实操里踩出来的。第一可观测性强。ReAct 强制模型把推理写出来你在日志里能直接看到它为什么调这个工具出问题的时候一眼能定位是推理错了还是工具返回错了。纯 function calling 有时候模型直接吐一个工具调用你根本不知道它怎么想的。第二容错路径清晰。ReAct 的循环天然支持这一步没拿到想要的结果下一轮换个思路。比如第一次搜索关键词不对observation 回来是空的模型下一轮会自动调整关键词。这种自我修正能力在速刷阶段特别省心。第三和 MCP 的契合度高。MCPModel Context Protocol本质上是给模型提供标准化工具接口的协议ReAct 的 action 阶段正好就是选一个工具、填参数、调用两者拼在一起非常自然。你速刷的时候把 ReAct 跑通再接 MCP server链路是顺的。提示速刷阶段不要一上来就追求多工具、多轮复杂编排。先用一个工具比如一个简单的计算器或时间查询把 ReAct 循环跑通确认 thought/action/observation 三段日志都正常再往上加东西。2.3 一个容易混淆的点skill 和 agent 的区别热词里出现了skill 和 agent 的区别这个在速刷时也容易绕进去。简单说skill 是能力单元agent 是调度这些能力的主体。一个 agent 可以拥有多个 skillagent 负责决定什么时候用哪个 skillskill 负责具体怎么把这件事做好。放到 ReAct 里action 调用的那个工具本质上就是一个 skill 的入口。理解这一层你在设计 hello-agent 的时候就不会把工具实现和调度逻辑搅在一起。工具就老老实实做一件事、返回结构化结果调度逻辑交给 loop 和模型。职责分清后面加工具才不会越加越乱。3. 把 hello-agent 跑起来一条最小闭环的完整搭建路径这一节是速刷的主体。我会按环境准备 → 定义工具 → 写 loop → 接模型 → 跑通的顺序讲每一步都说清楚为什么这么做。再次强调具体代码基于常见实践补全你按自己的技术栈替换即可。3.1 环境准备里最容易被忽略的两件事大部分人环境准备就是装个依赖、配个 key然后发现跑不起来。我踩过的坑集中在两点。第一模型接口的超时和重试没配。Agent Loop 是多次调用模型的一次超时整个循环就断了。速刷阶段建议把单次请求超时设短一点比如 30 秒重试设 2 到 3 次并且重试要带退避。这样偶发的网络抖动不会让你误以为是逻辑 bug。第二日志级别要开到能看到完整请求和响应。很多人默认日志只打结果结果调试的时候完全不知道模型收到了什么、返回了什么。速刷阶段把请求体、响应体、每一轮的 thought/action/observation 都打出来虽然吵但定位问题快得多。依赖方面如果你用 Python通常就是模型 SDK 加一个 HTTP 客户端如果用 Node.js就是对应的 SDK。MCP 相关的部分速刷阶段可以先不接等 ReAct 跑通了再加避免一次引入太多变量。3.2 定义第一个工具越简单越好工具的定义要满足三个条件输入参数明确、输出结构化、无副作用。速刷阶段我建议就用一个当前时间查询或者简单计算器别用搜索类工具因为搜索结果不稳定会干扰你判断 loop 本身有没有问题。工具的描述description非常关键模型就是靠这个决定要不要调、怎么填参数。描述里要写清楚这个工具做什么、参数是什么类型、什么情况下该用。比如tools [ { name: get_current_time, description: 获取指定时区的当前时间。当用户询问现在几点、当前日期时使用。, parameters: { type: object, properties: { timezone: { type: string, description: 时区名称例如 Asia/Shanghai } }, required: [timezone] } } ]注意 description 里那句当用户询问现在几点、当前日期时使用这就是在给模型划使用边界。速刷阶段工具少边界写清楚模型基本不会乱调。3.3 写 loop控制流比模型调用更重要loop 的骨架其实很短但细节决定成败。核心结构是这样def run_agent(user_input, max_turns8): messages [{role: user, content: user_input}] for turn in range(max_turns): response call_model(messages, tools) messages.append(response) if response.has_tool_call: result execute_tool(response.tool_call) messages.append({ role: tool, content: str(result) }) else: return response.content return 达到最大轮次仍未完成看起来简单但有几个点必须注意。max_turns 一定要设。我见过没设上限的 loop模型陷入调工具 → 结果不满意 → 再调同一个工具的死循环烧了一堆 token。速刷阶段设 8 轮足够正常任务 2 到 4 轮就结束了。工具执行要包异常。工具报错不能直接抛出去把 loop 打断要把错误信息作为 observation 塞回 messages让模型知道这个工具失败了它下一轮可能会换个方式。这是 ReAct 容错的关键。消息历史要完整保留。每一轮的 assistant 消息含 thought 和 tool_call和 tool 消息都要按顺序 append不能只留最后一条。模型是靠完整历史来判断我已经做过什么的。3.4 接模型system prompt 里要写清楚规则system prompt 在 agent 里比在普通对话里重要得多因为它要约束模型的行为模式。速刷阶段至少要写清楚三件事你是一个可以使用工具的助手需要时调用工具不需要时直接回答。每次调用工具前先用一句话说明你的推理。如果工具返回结果不满足需求可以调整参数重试但不要重复无效调用。第三条特别有用能明显减少死循环。我实测下来加了这条之后模型在工具返回空结果时会更倾向于换关键词或换工具而不是原地重试。3.5 跑通验证看日志而不是看最终答案速刷成功的标志不是最终答案对了而是日志里能看到完整的 thought → action → observation 循环。哪怕最终答案不完美只要循环是通的速刷就算成功。因为答案质量可以靠调 prompt 和换模型优化但循环不通就是架构问题。验证清单我一般看这几项检查项期望表现常见异常thought 输出每轮有简短推理模型直接吐 tool_call 无推理action 参数参数类型和描述一致时区填成中国这种非标准值observation 回填工具结果完整进入历史只回填了部分字段循环终止正常任务 2-4 轮结束一直调到 max_turns异常处理工具报错后能继续报错直接中断这张表你速刷的时候可以对着看哪一项不对就针对性调。4. 接上 MCP 之后链路变长了坑也变多了ReAct 跑通之后很多人下一步就是接 MCP。MCP 的价值在于把工具接口标准化你不用为每个工具写一套适配代码只要接上对应的 MCP server工具就能被模型发现和调用。但链路一长问题就多。4.1 MCP 在链路里到底站在哪个位置先把位置摆正。MCP 是模型和工具之间的标准化协议层。没有 MCP 的时候你的工具是硬编码在代码里的模型通过你定义的 schema 调用有了 MCP工具由 MCP server 提供你的 agent 通过 MCP 客户端去发现工具列表、获取工具 schema、发起调用。所以链路变成了Agent Loop → 模型决策 → MCP 客户端 → MCP Server → 实际工具 → 结果原路返回。多出来的这一层好处是工具可以复用、可以动态发现代价是每一层都可能出问题。4.2 工具发现阶段的典型问题接 MCP 之后第一个坑往往在工具发现。你的 agent 启动时要去 MCP server 拉工具列表如果这一步失败模型就看不到任何工具表现就是它明明该调工具却直接回答了。排查顺序我一般是先确认 MCP server 本身起来了没再确认客户端连接配置对不对最后看工具列表有没有正确注入到模型的 tools 参数里。这三步任何一步断了现象都一样所以必须按顺序排。还有一个隐蔽的坑工具名冲突。如果你同时接了多个 MCP server不同 server 可能有同名工具模型调用时可能调错。速刷阶段建议只接一个 server或者给工具名加前缀区分。4.3 调用阶段的超时和错误传递MCP 调用比本地工具调用多了一层网络或进程通信超时概率更高。我的做法是给 MCP 调用单独设一个比本地工具更长的超时并且在超时后把工具调用超时作为 observation 返回给模型而不是直接抛异常。错误传递这块要注意MCP server 返回的错误格式可能和你的 loop 预期不一致。速刷阶段建议在客户端做一层归一化把各种错误都转成统一的{success: false, error: ...}结构再塞回 messages。这样模型看到的错误信息是一致的处理逻辑也统一。注意MCP 相关的配置项在不同实现里命名差异较大速刷时不要照抄网上的配置先看你用的客户端文档里字段叫什么再对应填。我见过直接抄配置导致连接一直失败的案例最后发现是字段名不一样。4.4 一个实用的调试技巧把 MCP 调用单独打日志链路长了之后出问题最难定位的是到底哪一层挂了。我的习惯是在 MCP 客户端入口和出口各打一条日志入口记录要调什么工具、什么参数出口记录返回了什么、耗时多少。这样一旦模型行为异常我能快速判断是模型决策错了还是 MCP 层返回错了。这个技巧在速刷阶段特别值因为你对整条链路还不熟靠猜很浪费时间。日志打全了问题基本自己就浮出来了。5. 速刷过程中最容易翻车的几个点前面讲的是怎么搭这一节讲怎么不翻车。这些都是我在实际跑 agent 时反复遇到的问题速刷阶段尤其容易撞上。5.1 模型不调工具直接编答案这是最高频的问题。表现是明明有工具可用模型却直接凭记忆回答甚至编造一个看起来合理的结果。原因通常是工具描述不够明确或者 system prompt 没强调涉及实时信息必须调工具。解决办法有两个。一是把工具描述写得更具体明确什么情况下必须用二是在 system prompt 里加一条硬规则比如涉及时间、计算、外部数据的问题必须先调用对应工具不得凭记忆回答。我实测下来第二条对减少编答案非常有效。5.2 参数填错但模型不自知模型调工具时参数填错比如时区填成北京时间而不是Asia/Shanghai工具返回错误但模型下一轮还是填同样的错值。这是因为错误信息没有足够明确地告诉它哪里错了。改进方法是在工具返回的错误里带上期望格式比如时区格式应为 Region/City例如 Asia/Shanghai你提供的是北京时间。模型看到这种带纠正提示的错误下一轮基本能改对。5.3 循环停不下来前面提过 max_turns 要设但还有一种情况是设了上限还是感觉没完没了。这通常是任务本身太模糊模型不知道该做到什么程度算完成。速刷阶段建议给的任务要具体比如查一下现在上海几点而不是帮我处理一下时间相关的事情。如果任务必须模糊那就在 system prompt 里定义完成标准比如当你已经能回答用户问题时直接给出答案并结束。5.4 上下文越滚越长导致后面变慢变贵Agent Loop 每一轮都把完整历史传给模型轮次多了之后 token 消耗是平方级增长的。速刷阶段任务短问题不明显但你要有这个意识。常见的优化是工具返回的超长结果做截断或摘要后再塞回历史只保留关键信息。我一般会在工具执行后加一步结果压缩比如搜索结果只保留前几条的标题和摘要完整内容不塞进上下文。这样既保留了决策所需信息又控制了长度。6. 速刷之后往哪走从能跑到好用速刷的目标是能跑但跑通之后你大概率会想让它好用。这里分享几个我实际用下来收益比较高的方向不是必须做但做了之后体验提升明显。6.1 加一层 agent evals别靠肉眼判断好坏Agent 的行为不像普通函数那样有确定输出靠肉眼看几次对话判断好不好很不靠谱。速刷之后建议搭一个最小的评测集准备 10 到 20 个典型任务每个任务有明确的期望行为比如应该调用时间工具、应该在 3 轮内结束每次改完 prompt 或换模型就跑一遍。这个评测集不用复杂一个脚本加一个结果表格就够。但它能帮你避免改了一处、坏了另一处的情况。我踩过的坑就是调完 prompt 觉得某类任务变好了结果另一类任务悄悄退化了没有评测根本发现不了。6.2 工具粒度别做太粗也别做太细工具设计有个度。太粗比如一个工具叫处理所有事情模型不知道怎么填参数太细比如把获取时间拆成获取小时获取分钟模型要调好几次才能完成一件事轮次暴涨。我的经验是一个工具对应一个完整的、有意义的动作。获取指定时区当前时间就是一个合适的粒度获取当前小时就太细了。速刷阶段工具少这个度好把握工具多了之后要定期回头看把高频一起出现的细工具合并。6.3 关于 agent 框架的选择先别急着上重框架热词里有 agent 框架、agent 架构这些很多人速刷完就想直接上框架。我的建议是先用裸 loop 跑一段时间把 ReAct、工具调用、错误处理这些基础打牢再去用框架。因为框架帮你封装了很多东西出问题的时候如果你不理解底层排查会很痛苦。等你对 loop 的每个环节都清楚了再上框架就是用框架提效而不是被框架牵着走。这个顺序反了学习成本会高很多。6.4 一个我常用的排查套路最后分享一个排查 agent 问题的通用套路速刷和后续都用得上把问题按模型决策层和工具执行层分开定位。具体做法是先看模型这一轮的 thought 和 action 是否合理。如果 thought 就错了那是 prompt 或模型能力问题如果 thought 对但 action 参数错那是工具描述问题如果 action 对但 observation 不对那是工具实现或 MCP 层问题。按这个顺序切基本三轮之内能定位到根因。这个套路的好处是它不依赖具体框架换任何 agent 实现都适用。我用了很久比漫无目的地看日志高效得多。速刷这件事说到底就是用一个最小闭环把概念串起来。跑通之后你会发现agent loop、ReAct、MCP 这些词不再是孤立的术语而是同一条链路上的不同环节。剩下的就是在这个骨架上不断加东西、调细节那部分就靠实际项目慢慢磨了。