1. 先搞清楚 ReAct 到底在循环什么ReAct 这个词拆开就是 Reasoning Acting推理加行动。很多刚接触 Agent 的朋友会把它想得很玄其实核心就一句话让大模型在“想”和“做”之间来回切换而不是一口气把答案吐完。你问它一个问题它先想一步“我该干嘛”然后真的去干调工具、查资料、读文件拿到结果后再想下一步直到任务完成。这个循环长这样思考下一步 → 执行动作 → 观察结果 → 更新判断 → 再决定下一步。听起来简单但它解决了一个很实际的问题——单轮问答里模型只能靠训练时记住的东西回答遇到需要实时信息、需要访问本地文件、需要多步试错的任务就抓瞎了。ReAct 把模型从“文本生成器”变成了“能操作环境的任务协调者”。适合谁学如果你刚接触 Agent想跑通第一个能调用工具的循环这篇就是给你写的。我会用 TaoToken 的统一 Key 做模型接入给你可复制的 settings.json 和 config.toml 骨架最后验证一次完整的工具调用链路。不需要你懂多深的框架原理跟着敲就行。先明确一个边界ReAct 不等于让模型自治。它能让模型更会使用工具但权限设计、风险控制、测试验证这些还是得人来兜底。工具调用错误、循环失控、成本上升都是真实存在的坑后面会讲怎么排查。2. 用 TaoToken 统一 Key 做前置准备为什么用 TaoToken 而不是直接对接各家模型因为 ReAct 循环里模型会被反复调用如果你同时试几个模型对比效果每家一个 Key、一套计费、一套接口格式管理起来很烦。TaoToken 提供统一 Key一个 Key 走通多个模型的调用对刚入门、想快速验证 ReAct 链路的人来说省事。你需要准备的东西一个 TaoToken 账号去官网注册https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content登录后在控制台创建 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite记下你的 Key形如sk-xxxx后面配置里要用API 的基础地址是https://taotoken.net/api注意这个地址不带任何查询参数配置时直接填这个就行。如果你用的是 OpenAI 兼容的 SDK把 base_url 指向它api_key 填你创建的 Key就能直接调。注意Key 只创建时完整显示一次创建完立刻复制保存。丢了就重新建一个别去猜。想先不写代码、直接在网页上跟模型对话验证 Key 是否可用可以打开模型对话页https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 发一句话看有没有正常回复。这一步能帮你排除掉“Key 本身有问题”这个变量后面排障会轻松很多。3. 可复制的 settings.json 与 config.toml 骨架下面给两份配置骨架。settings.json 适合用 JSON 配置的 Agent 框架或脚本config.toml 适合用 TOML 的工具链。你按自己实际用的框架挑一份改核心是把 base_url、api_key、model 三个字段填对。3.1 settings.json 骨架{ llm: { provider: openai-compatible, base_url: https://taotoken.net/api, api_key: sk-你的Key填这里, model: gpt-4o-mini, temperature: 0.2, max_tokens: 1024 }, agent: { max_steps: 6, stop_on_final: true, verbose: true }, tools: [ { name: get_current_time, description: 获取当前时间无需参数, type: builtin }, { name: calculator, description: 计算一个数学表达式参数为 expression 字符串, type: builtin } ] }几个参数说明一下。temperature设 0.2 是因为 ReAct 需要模型稳定地做决策太随机容易乱调工具。max_steps是循环上限防止模型反复搜索停不下来新手先设 6 步够用。verbose打开后每一步的思考、动作、观察都会打印出来方便你看循环到底走到哪了。3.2 config.toml 骨架[llm] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的Key填这里 model gpt-4o-mini temperature 0.2 max_tokens 1024 [agent] max_steps 6 stop_on_final true verbose true [[tools]] name get_current_time description 获取当前时间无需参数 type builtin [[tools]] name calculator description 计算一个数学表达式参数为 expression 字符串 type builtinTOML 里数组表用[[tools]]每多一个工具就多写一段。两份配置的字段含义完全一致只是语法不同。如果你用的框架要求别的字段名以框架文档为准但 base_url 和 api_key 这两个值是不变的。提示不要把 Key 硬编码后提交到 Git。本地测试可以真要上传仓库就用环境变量替换比如api_key ${TAOTOKEN_API_KEY}。4. 跑通一次工具调用链路并验证结果配置填好后写一个最小脚本把 ReAct 循环跑起来。下面用 Python 伪代码演示重点是让你看清“思考-行动-观察”是怎么串起来的实际框架里这些通常由 Agent 类封装好了。import json import requests BASE_URL https://taotoken.net/api API_KEY sk-你的Key填这里 def call_llm(messages): resp requests.post( f{BASE_URL}/v1/chat/completions, headers{ Authorization: fBearer {API_KEY}, Content-Type: application/json }, json{ model: gpt-4o-mini, messages: messages, temperature: 0.2 } ) return resp.json()[choices][0][message][content] def get_current_time(): import datetime return datetime.datetime.now().strftime(%Y-%m-%d %H:%M:%S) def calculator(expression): return str(eval(expression)) TOOLS { get_current_time: get_current_time, calculator: calculator } def react_loop(user_query, max_steps6): messages [ {role: system, content: 你是一个 ReAct Agent。每步先输出 Thought再输出 Action。Action 格式为 JSON{\tool\: \工具名\, \args\: {...}}。信息足够时输出 Final Answer。}, {role: user, content: user_query} ] for step in range(max_steps): output call_llm(messages) print(f--- Step {step1} ---) print(output) if Final Answer in output: return output # 解析 Action 并执行 try: action_str output.split(Action:)[-1].strip() action json.loads(action_str) tool_name action[tool] args action.get(args, {}) if tool_name get_current_time: observation get_current_time() elif tool_name calculator: observation calculator(args[expression]) else: observation f未知工具: {tool_name} except Exception as e: observation f解析或执行失败: {e} print(fObservation: {observation}) messages.append({role: assistant, content: output}) messages.append({role: user, content: fObservation: {observation}}) return 达到最大步数未得到最终答案 if __name__ __main__: result react_loop(现在几点另外帮我算一下 23 乘以 17 等于多少。) print( 最终结果 ) print(result)跑起来后你会看到类似这样的输出第一步模型思考“需要先获取时间”输出 Action 调用get_current_time脚本执行后把结果作为 Observation 塞回对话第二步模型看到时间后继续思考“还需要算乘法”调用calculator第三步拿到结果输出 Final Answer 把两个答案合在一起。这就是一个完整的 ReAct 循环。验证成功的标志是你能在日志里清楚看到 Thought、Action、Observation 交替出现且最终答案里包含了工具返回的真实数据而不是模型编的。如果模型直接跳过工具凭记忆回答说明系统提示词没约束好或者工具描述不够清晰。5. 本篇常见错误排查新手跑第一个 ReAct 循环大概率会撞上下面几个问题。我按出现频率排一下。报错一401 Unauthorized。九成是 Key 填错或没带Bearer前缀。检查Authorization头是不是Bearer sk-xxx格式Key 前后有没有多余空格。如果 Key 确认没问题去控制台看看这个 Key 是不是被禁用或删除了。报错二404 或 model not found。通常是 base_url 写错了。正确地址是https://taotoken.net/api如果你在代码里又拼了/v1要确认最终请求路径是https://taotoken.net/api/v1/chat/completions。不同 SDK 对 base_url 的处理不一样有的会自动补/v1有的不会对着实际请求日志看。报错三模型不调工具直接给答案。这是提示词问题。系统提示里要明确要求“必须先输出 Thought 和 Action信息足够才能输出 Final Answer”并且把工具的 name 和 description 写清楚。工具描述越具体模型选错的概率越低。工具数量也别一上来就堆十几个新手先放两三个。报错四循环停不下来。模型反复调同一个工具或者一直在搜索。两个办法一是设max_steps硬上限二是提示词里加终止条件比如“如果连续两次观察结果相同直接输出 Final Answer”。成本敏感的话把简单任务和复杂任务分开简单任务别开完整 ReAct。报错五Action 解析失败。模型输出的 JSON 格式不标准比如带了多余文字或用了单引号。解析前先做字符串清洗或者用更宽容的解析方式。也可以在提示词里给一个 Action 的示例格式让模型照着抄。排障顺序建议先用模型对话页确认 Key 能用再用 curl 直接打一次接口确认网络和鉴权没问题最后才排查 Agent 逻辑。这样能快速定位问题出在哪一层。6. 接下来怎么继续深入跑通第一个循环后你可以往几个方向加东西。一是加更多工具比如读本地文件、查数据库、调外部 API让 Agent 真正能操作环境。二是加状态管理把每步的 Thought、Action、Observation 存下来方便回溯和调试。三是加权限控制哪些工具只读、哪些能写、哪些需要人工确认这个在生产环境里必须有。如果你打算长期做编码类 Agent比如让模型读代码、改文件、跑测试再根据报错修正那 ReAct 循环会被高频调用这时候用 Coding Plan 会更划算具体可以看https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有针对不同框架的配置说明。Key 管理统一在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。最后说个我自己的体会ReAct 的难点从来不是循环本身而是工具描述和终止条件的设计。工具描述写得好模型选对的概率高一大截终止条件设得合理才不会烧钱烧到心疼。先把最小循环跑通再一步步加复杂度别一上来就搭多 Agent 编排那样出了问题你都不知道是哪一层的事。
