1. 从 12K Star 的 AI Agent 开源书说起ReAct 示例为什么值得本地跑一遍如果你最近在搜「AI Agent 开源书」「GitHub ReAct 示例」「LLM 工具调用链路怎么复现」大概率会刷到 bojieli/ai-agent-book 这个仓库。12K Star、Apache-2.0、10 章 88 个项目Python 占比 94.8%作者是李博杰。它最值钱的地方不是概念罗列而是把 Agent LLM 上下文 工具 这条线用可运行的代码从头穿到尾尤其是 ReAct 那一章把「思考-行动-观察」三拍循环拆成了能直接跑的骨架。但真到本地复现的时候很多人会卡在同一个地方示例代码里client OpenAI()默认走官方 endpoint你得有对应区域的 Key、有可用的网络出口、还得处理模型名映射。对只想验证 ReAct 循环逻辑的人来说这些前置成本太高了。我试过把这套示例的 endpoint 和 Key 统一改到 TaoToken用同一个 Key 跑通 ReAct 的工具调用链路改完只动了三行配置循环就能正常返回tool_calls并写回messages。这篇就按「本地复现 ReAct 章节」这个场景写给你可直接复制的 settings 配置片段、一次 curl 验证请求以及跑通后常见的几类报错排查。适合已经看过 LangChain、调过 Function Calling但想搞清楚底层数据怎么流动的人也适合在带 Agent 项目、需要做技术选型和架构验证的开发者。全程不需要你改示例的核心逻辑只改接入层。2. TaoToken 前置准备统一 Key 与 endpoint 的接入配置在动示例代码之前先把接入层的事情理清楚。TaoToken 在这里扮演的角色是统一的模型调用入口你拿到一个 Base URL 和一个 API Key就能在 OpenAI 兼容的客户端里调用不同模型不用为每个示例单独配一套凭证。对复现开源书里的 ReAct 示例来说这能省掉「示例 A 用这个 Key、示例 B 用那个 Key」的来回切换。先注册并登录控制台地址是 https://taotoken.net/console 。进去之后在 API Keys 页面创建一个 Key复制出来备用。这个 Key 就是后面所有配置里api_key字段的值。注意 Key 只在创建时完整显示一次建议先存到本地环境变量里别直接硬编码进示例代码。模型 ID 这块要留意开源书示例里写的是gpt-4这类名字你在 TaoToken 里要换成平台实际支持的模型 ID。具体有哪些可用模型可以在模型对话页面直接试地址是 https://taotoken.net/chat 选一个你熟悉的模型把它的 ID 记下来后面配置里model字段填这个。接入文档在 https://taotoken.net/doc 里面写了 OpenAI 兼容接口的 Base URL 格式和鉴权方式。核心就两点Base URL 填https://taotoken.net/api鉴权用Authorization: Bearer 你的Key。这两点和 OpenAI SDK 完全兼容所以示例代码里OpenAI(base_url..., api_key...)这样传参就行不用改任何调用逻辑。如果你后面要长期跑 Agent 项目、做多步编码任务可以看下 Coding Plan地址是 https://taotoken.net/coding-plan 。它更适合持续性的编码和 Agent 场景不是一次性验证。但本篇聚焦的是「跑通 ReAct 示例」用按量调用的 Key 就够了先把链路验证通再考虑长期方案。环境变量建议这样设Linux/macOS 下export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 下$env:TAOTOKEN_API_KEYsk-你的Key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api设完之后示例代码里用os.environ.get(TAOTOKEN_API_KEY)读取避免把 Key 写进仓库。这一步做完接入层就准备好了接下来改示例的 settings。3. 可复制配置把 ReAct 示例的 endpoint 与 Key 改到 TaoToken开源书第四章的工具调用示例核心骨架就是一个while True循环模型返回tool_calls就执行工具、把结果写回messages返回文本就结束。我们要改的只有客户端初始化那几行。原始代码是from openai import OpenAI client OpenAI()改成显式传入 Base URL 和 Keyimport os from openai import OpenAI client OpenAI( base_urlos.environ.get(TAOTOKEN_BASE_URL, https://taotoken.net/api), api_keyos.environ.get(TAOTOKEN_API_KEY), )然后client.chat.completions.create里的model参数从示例里的gpt-4换成你在 TaoToken 模型对话页面确认过的模型 ID。其余messages、tools、tool_choice这些参数完全不用动因为接口是 OpenAI 兼容的。如果你用的是带 settings 文件的示例项目比如有些章节会读settings.json或.env那就按下面这个结构写。JSON 版{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: 你的模型ID, timeout: 60 }TOML 版有些项目用config.toml[llm] base_url https://taotoken.net/api api_key sk-你的Key model 你的模型ID timeout 60.env 版TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_MODEL你的模型ID这里有个关键点Base URL 填https://taotoken.net/api不要在后面多加/v1或/chat/completionsOpenAI SDK 会自己拼路径。多加了反而会 404。Key 和 Model ID 三件套必须同时对上——Base URL 决定请求发到哪Key 决定鉴权Model ID 决定实际调用哪个模型。缺一个都会失败报错信息还不一样后面第五节会逐个对照。改完之后把示例里的get_weather换成你自己的工具函数比如查数据库、调内部 API工具描述写清楚参数含义ReAct 循环就能跑起来了。工具描述别写太啰嗦模型容易「想太多」也别太简略容易乱调。这个度在开源书里讲得比较细可以对着调。4. 验证请求一次 curl 确认 ReAct 循环能返回工具调用结果配置改完先别急着跑整个示例用一次 curl 验证接入层通不通。这一步能快速区分「是接入配置问题」还是「是示例逻辑问题」。curl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: 你的模型ID, messages: [ {role: user, content: 北京今天天气怎么样} ], tools: [ { type: function, function: { name: get_weather, description: 查询指定城市的天气情况, parameters: { type: object, properties: { city: {type: string, description: 城市名称} }, required: [city] } } } ] }如果接入正常返回的 JSON 里choices[0].message会带tool_calls字段里面包含function.name和function.arguments类似{ choices: [ { message: { role: assistant, tool_calls: [ { id: call_xxx, type: function, function: { name: get_weather, arguments: {\city\:\北京\} } } ] } } ] }看到tool_calls就说明模型正确识别了工具并生成了调用参数ReAct 循环的第一步「行动」是通的。接下来在示例代码里把这个tool_calls解析出来、执行get_weather、把结果以role: tool写回messages再发一次请求模型就会基于工具结果输出最终文本。这就是完整的「思考-行动-观察」闭环。跑通之后你会看到类似这样的输出第一轮返回tool_calls第二轮返回content文本比如「北京今天晴22°C」。整个过程不需要改示例的循环逻辑只改了客户端初始化和模型 ID。如果 curl 返回的是401说明 Key 有问题返回404多半是 Base URL 多写了路径返回model not found是模型 ID 不对。下一节逐个对照。5. 常见报错排查401、local proxy failed、reading choices、OAuth 对照跑 ReAct 示例时报错基本集中在接入层。下面按真实报错信息对照排查。401 Unauthorized / invalid api keyKey 没传对。检查三处——环境变量TAOTOKEN_API_KEY是否真的导出成功echo $TAOTOKEN_API_KEY看下、代码里读取的变量名是否一致、Key 有没有多余空格或换行。curl 里Authorization: Bearer后面跟的 Key 要完整。如果 Key 是在控制台刚创建的确认复制时没漏字符。404 Not Found / local proxy failedBase URL 写错了。常见的是写成https://taotoken.net/api/v1或https://taotoken.net/api/chat/completions。正确写法就是https://taotoken.net/apiSDK 会自己拼/chat/completions。另外「local proxy failed」这类报错通常是本地网络环境或代理配置干扰了请求检查下有没有多余的HTTP_PROXY/HTTPS_PROXY环境变量清掉再试。reading choices / KeyError: choices请求返回了但结构不对。多半是模型 ID 填错返回体里没有choices字段而是error。先看完整返回内容确认model字段是 TaoToken 支持的 ID。也有可能是tools参数格式不对比如parameters里少了type: object导致请求被拒。OAuth / authentication_error如果你用的是某些 CLI 工具或带 OAuth 流程的客户端报 OAuth 相关错误说明它没走 API Key 鉴权而是尝试了别的认证方式。这种情况要在该工具的配置里显式指定 API Key 模式把 Base URL 和 Key 填进去。比如 Claude Code 这类工具配置里要写全 Base URL、Key、Model ID 三件套缺一个都会回退到默认认证流程。模型返回空 tool_calls 或直接输出文本接入是通的但模型没调工具。检查工具描述是否清晰、tool_choice是否设成了auto或指定了函数。有些模型指令遵循弱你让它调工具它能分析半天就是不调换个指令遵循强的模型 ID 再试。排查顺序建议先 curl 验证接入层再跑示例验证逻辑层。接入层通了示例逻辑基本不会有大问题。6. 跑通之后把 ReAct 示例改成你自己的工具链路ReAct 循环跑通只是起点。开源书里 88 个项目真正有价值的是把示例里的get_weather换成你自己的数据源。比如你有个运维工具要查告警就把工具函数改成调告警接口工具描述写清楚「查询指定时间范围内的告警列表」参数里加上service和time_range。模型会在 Thought 阶段判断要不要调、调几次Observation 阶段拿到结果再决定下一步。这里有个实用技巧工具返回结果太长时别直接塞进messages先做截断或摘要否则上下文窗口很快被撑满。开源书第四章讲上下文管理时提过滑动窗口和摘要压缩可以对着改。另外模型连续调同一个工具三次都没拿到想要的结果可以在循环里加个计数器超过阈值就打断让它基于已有信息输出避免死循环。如果你要把这套链路用到长期编码或 Agent 项目里按量 Key 之外可以看下 Coding Planhttps://taotoken.net/coding-plan 更适合持续性任务。接入文档在 https://taotoken.net/doc API Keys 在 https://taotoken.net/api-keys 模型对话验证在 https://taotoken.net/chat 。把示例的工具函数换成你自己的这个「改」的过程比跑通十个示例学到的东西多。
1. 从 12K Star 的 AI Agent 开源书说起ReAct 示例为什么值得本地跑一遍如果你最近在搜「AI Agent 开源书」「GitHub ReAct 示例」「LLM 工具调用链路怎么复现」大概率会刷到 bojieli/ai-agent-book 这个仓库。12K Star、Apache-2.0、10 章 88 个项目Python 占比 94.8%作者是李博杰。它最值钱的地方不是概念罗列而是把 Agent LLM 上下文 工具 这条线用可运行的代码从头穿到尾尤其是 ReAct 那一章把「思考-行动-观察」三拍循环拆成了能直接跑的骨架。但真到本地复现的时候很多人会卡在同一个地方示例代码里client OpenAI()默认走官方 endpoint你得有对应区域的 Key、有可用的网络出口、还得处理模型名映射。对只想验证 ReAct 循环逻辑的人来说这些前置成本太高了。我试过把这套示例的 endpoint 和 Key 统一改到 TaoToken用同一个 Key 跑通 ReAct 的工具调用链路改完只动了三行配置循环就能正常返回tool_calls并写回messages。这篇就按「本地复现 ReAct 章节」这个场景写给你可直接复制的 settings 配置片段、一次 curl 验证请求以及跑通后常见的几类报错排查。适合已经看过 LangChain、调过 Function Calling但想搞清楚底层数据怎么流动的人也适合在带 Agent 项目、需要做技术选型和架构验证的开发者。全程不需要你改示例的核心逻辑只改接入层。2. TaoToken 前置准备统一 Key 与 endpoint 的接入配置在动示例代码之前先把接入层的事情理清楚。TaoToken 在这里扮演的角色是统一的模型调用入口你拿到一个 Base URL 和一个 API Key就能在 OpenAI 兼容的客户端里调用不同模型不用为每个示例单独配一套凭证。对复现开源书里的 ReAct 示例来说这能省掉「示例 A 用这个 Key、示例 B 用那个 Key」的来回切换。先注册并登录控制台地址是 https://taotoken.net/console 。进去之后在 API Keys 页面创建一个 Key复制出来备用。这个 Key 就是后面所有配置里api_key字段的值。注意 Key 只在创建时完整显示一次建议先存到本地环境变量里别直接硬编码进示例代码。模型 ID 这块要留意开源书示例里写的是gpt-4这类名字你在 TaoToken 里要换成平台实际支持的模型 ID。具体有哪些可用模型可以在模型对话页面直接试地址是 https://taotoken.net/chat 选一个你熟悉的模型把它的 ID 记下来后面配置里model字段填这个。接入文档在 https://taotoken.net/doc 里面写了 OpenAI 兼容接口的 Base URL 格式和鉴权方式。核心就两点Base URL 填https://taotoken.net/api鉴权用Authorization: Bearer 你的Key。这两点和 OpenAI SDK 完全兼容所以示例代码里OpenAI(base_url..., api_key...)这样传参就行不用改任何调用逻辑。如果你后面要长期跑 Agent 项目、做多步编码任务可以看下 Coding Plan地址是 https://taotoken.net/coding-plan 。它更适合持续性的编码和 Agent 场景不是一次性验证。但本篇聚焦的是「跑通 ReAct 示例」用按量调用的 Key 就够了先把链路验证通再考虑长期方案。环境变量建议这样设Linux/macOS 下export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 下$env:TAOTOKEN_API_KEYsk-你的Key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api设完之后示例代码里用os.environ.get(TAOTOKEN_API_KEY)读取避免把 Key 写进仓库。这一步做完接入层就准备好了接下来改示例的 settings。3. 可复制配置把 ReAct 示例的 endpoint 与 Key 改到 TaoToken开源书第四章的工具调用示例核心骨架就是一个while True循环模型返回tool_calls就执行工具、把结果写回messages返回文本就结束。我们要改的只有客户端初始化那几行。原始代码是from openai import OpenAI client OpenAI()改成显式传入 Base URL 和 Keyimport os from openai import OpenAI client OpenAI( base_urlos.environ.get(TAOTOKEN_BASE_URL, https://taotoken.net/api), api_keyos.environ.get(TAOTOKEN_API_KEY), )然后client.chat.completions.create里的model参数从示例里的gpt-4换成你在 TaoToken 模型对话页面确认过的模型 ID。其余messages、tools、tool_choice这些参数完全不用动因为接口是 OpenAI 兼容的。如果你用的是带 settings 文件的示例项目比如有些章节会读settings.json或.env那就按下面这个结构写。JSON 版{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: 你的模型ID, timeout: 60 }TOML 版有些项目用config.toml[llm] base_url https://taotoken.net/api api_key sk-你的Key model 你的模型ID timeout 60.env 版TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_MODEL你的模型ID这里有个关键点Base URL 填https://taotoken.net/api不要在后面多加/v1或/chat/completionsOpenAI SDK 会自己拼路径。多加了反而会 404。Key 和 Model ID 三件套必须同时对上——Base URL 决定请求发到哪Key 决定鉴权Model ID 决定实际调用哪个模型。缺一个都会失败报错信息还不一样后面第五节会逐个对照。改完之后把示例里的get_weather换成你自己的工具函数比如查数据库、调内部 API工具描述写清楚参数含义ReAct 循环就能跑起来了。工具描述别写太啰嗦模型容易「想太多」也别太简略容易乱调。这个度在开源书里讲得比较细可以对着调。4. 验证请求一次 curl 确认 ReAct 循环能返回工具调用结果配置改完先别急着跑整个示例用一次 curl 验证接入层通不通。这一步能快速区分「是接入配置问题」还是「是示例逻辑问题」。curl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: 你的模型ID, messages: [ {role: user, content: 北京今天天气怎么样} ], tools: [ { type: function, function: { name: get_weather, description: 查询指定城市的天气情况, parameters: { type: object, properties: { city: {type: string, description: 城市名称} }, required: [city] } } } ] }如果接入正常返回的 JSON 里choices[0].message会带tool_calls字段里面包含function.name和function.arguments类似{ choices: [ { message: { role: assistant, tool_calls: [ { id: call_xxx, type: function, function: { name: get_weather, arguments: {\city\:\北京\} } } ] } } ] }看到tool_calls就说明模型正确识别了工具并生成了调用参数ReAct 循环的第一步「行动」是通的。接下来在示例代码里把这个tool_calls解析出来、执行get_weather、把结果以role: tool写回messages再发一次请求模型就会基于工具结果输出最终文本。这就是完整的「思考-行动-观察」闭环。跑通之后你会看到类似这样的输出第一轮返回tool_calls第二轮返回content文本比如「北京今天晴22°C」。整个过程不需要改示例的循环逻辑只改了客户端初始化和模型 ID。如果 curl 返回的是401说明 Key 有问题返回404多半是 Base URL 多写了路径返回model not found是模型 ID 不对。下一节逐个对照。5. 常见报错排查401、local proxy failed、reading choices、OAuth 对照跑 ReAct 示例时报错基本集中在接入层。下面按真实报错信息对照排查。401 Unauthorized / invalid api keyKey 没传对。检查三处——环境变量TAOTOKEN_API_KEY是否真的导出成功echo $TAOTOKEN_API_KEY看下、代码里读取的变量名是否一致、Key 有没有多余空格或换行。curl 里Authorization: Bearer后面跟的 Key 要完整。如果 Key 是在控制台刚创建的确认复制时没漏字符。404 Not Found / local proxy failedBase URL 写错了。常见的是写成https://taotoken.net/api/v1或https://taotoken.net/api/chat/completions。正确写法就是https://taotoken.net/apiSDK 会自己拼/chat/completions。另外「local proxy failed」这类报错通常是本地网络环境或代理配置干扰了请求检查下有没有多余的HTTP_PROXY/HTTPS_PROXY环境变量清掉再试。reading choices / KeyError: choices请求返回了但结构不对。多半是模型 ID 填错返回体里没有choices字段而是error。先看完整返回内容确认model字段是 TaoToken 支持的 ID。也有可能是tools参数格式不对比如parameters里少了type: object导致请求被拒。OAuth / authentication_error如果你用的是某些 CLI 工具或带 OAuth 流程的客户端报 OAuth 相关错误说明它没走 API Key 鉴权而是尝试了别的认证方式。这种情况要在该工具的配置里显式指定 API Key 模式把 Base URL 和 Key 填进去。比如 Claude Code 这类工具配置里要写全 Base URL、Key、Model ID 三件套缺一个都会回退到默认认证流程。模型返回空 tool_calls 或直接输出文本接入是通的但模型没调工具。检查工具描述是否清晰、tool_choice是否设成了auto或指定了函数。有些模型指令遵循弱你让它调工具它能分析半天就是不调换个指令遵循强的模型 ID 再试。排查顺序建议先 curl 验证接入层再跑示例验证逻辑层。接入层通了示例逻辑基本不会有大问题。6. 跑通之后把 ReAct 示例改成你自己的工具链路ReAct 循环跑通只是起点。开源书里 88 个项目真正有价值的是把示例里的get_weather换成你自己的数据源。比如你有个运维工具要查告警就把工具函数改成调告警接口工具描述写清楚「查询指定时间范围内的告警列表」参数里加上service和time_range。模型会在 Thought 阶段判断要不要调、调几次Observation 阶段拿到结果再决定下一步。这里有个实用技巧工具返回结果太长时别直接塞进messages先做截断或摘要否则上下文窗口很快被撑满。开源书第四章讲上下文管理时提过滑动窗口和摘要压缩可以对着改。另外模型连续调同一个工具三次都没拿到想要的结果可以在循环里加个计数器超过阈值就打断让它基于已有信息输出避免死循环。如果你要把这套链路用到长期编码或 Agent 项目里按量 Key 之外可以看下 Coding Planhttps://taotoken.net/coding-plan 更适合持续性任务。接入文档在 https://taotoken.net/doc API Keys 在 https://taotoken.net/api-keys 模型对话验证在 https://taotoken.net/chat 。把示例的工具函数换成你自己的这个「改」的过程比跑通十个示例学到的东西多。
