1. 从符号推理到 ReActAgent 到底解决了什么问题大模型智能体LLM Agent这个词在 2026 年已经不算新鲜但很多人第一次接触时还是会把它和「套了系统提示词的聊天机器人」混为一谈。我先把结论放前面Agent 的本质是让模型从「一问一答」变成「多步骤自主执行」而 ReAct 范式是这条路上第一个真正跑通的工程方案。理解它你才能看懂后面 Cursor、Claude Code、Manus 这些产品为什么长成现在这样。先看一个最直观的对比。普通 LLM 应用是这样的用户问「北京今天天气怎么样」模型回答「今天晴25 度」——如果模型知识截止到去年这个答案就是编的。Agent 则是用户说「帮我查下北京天气如果下雨就提醒我带伞」Agent 会先思考「我需要调用天气工具」然后执行工具调用拿到真实数据再判断「今天有雨」最后输出「今天北京有雨记得带伞」。区别在于普通应用是单次推理Agent 是「思考—行动—观察」的循环直到目标完成。这个循环不是凭空冒出来的。1995 年 Russell 和 Norvig 在《人工智能一种现代方法》里就把 Agent 分成四类简单反射型、基于模型型、基于目标型、基于效用型。今天的 LLM Agent 基本落在后两类——它有目标完成任务也有偏好选最优路径。但传统 Agent 的规则是人写死的遇到规则外的情况就傻眼LLM Agent 用模型的推理能力替代了人写规则灵活了但也带来了新问题模型会推理错会幻觉会陷入死循环。2022 年 10 月普林斯顿的 ReAct 论文就是来解决这个矛盾的。它发现纯推理Chain-of-Thought容易胡说因为模型只在脑子里想不去验证纯行动Act-only又容易盲目执行因为没有规划。ReAct 的做法是让两者交替每次行动前先想清楚为什么行动后观察结果再决定下一步。这个「Thought → Action → Observation」的循环后来成了几乎所有 Agent 框架的底层骨架。你可能会问这跟 Function Calling 有什么关系关系很大。ReAct 论文发表时工具调用还得靠提示词「骗」模型输出特定格式格式错误率很高。2023 年 6 月 OpenAI 推出 Function Calling模型原生支持结构化工具调用Agent 的可靠性从 60% 左右跳到 90% 以上。这不是渐进改进是质变——它让 Agent 从演示玩具变成了能上生产的东西。所以你现在看到的任何 Agent 产品底层基本都是「ReAct 循环 Function Calling 工具调用」这套组合。那为什么还要讲概念起源因为不理解演进脉络你调 Agent 时遇到问题就不知道往哪查。比如 Agent 反复调用同一个工具你得知道这是 ReAct 循环缺少「重复检测」比如 Agent 规划得乱七八糟你得知道该上 Plan-and-Execute 模式。这些设计决策都能在历史里找到答案。接下来我先讲怎么用 TaoToken 把模型通道准备好再给你一份能直接跑的最小 ReAct Agent 配置。2. TaoToken 前置准备统一 Key 与 API 通道怎么配在写 Agent 代码之前得先把模型接入这关过了。做 Agent 开发最烦的一件事是你调试时可能想换不同模型对比效果但每个厂商的 API 格式、鉴权方式、Base URL 都不一样代码里到处是 if-else。TaoToken 的价值就在这里——它提供统一的 API 通道你用一套 Key 和一套 Base URL 就能访问多个模型切换模型只改一个 Model ID 字符串。先说清楚它是什么TaoToken 是一个大模型 API 聚合接入服务官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。你注册后在控制台生成 API Key然后所有请求都走这个统一入口。对 Agent 开发来说这意味着你的工具调用链、ReAct 循环代码不用为每个模型改一遍。具体操作步骤。第一步打开控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登录后进入 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 点「创建新密钥」复制生成的 Key。这个 Key 只显示一次建议直接存到环境变量里别硬编码进代码。第二步确认你要用的模型 ID。TaoToken 的模型列表在文档页 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 能查到常见的有 claude-sonnet-4 系列、gpt-4.1 系列、deepseek 系列等。Agent 场景我建议优先选工具调用能力强的模型因为 ReAct 循环里工具调用格式错了整个流程就断了。第三步配置环境变量。Linux/macOS 下这样写export TAOTOKEN_API_KEYsk-你的密钥 export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的密钥 $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api这里有个坑要注意Base URL 结尾不要带/v1TaoToken 的入口就是https://taotoken.net/apiSDK 会自动拼接路径。我见过有人写成https://taotoken.net/api/v1然后报 404排查半天。第四步如果你用的是 Claude Code 这类终端工具它需要单独的配置文件。Claude Code 的配置在~/.claude/settings.json写入{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }注意这里三个要素必须齐全Base URL、API Key、Model ID。少任何一个都会报鉴权失败或模型不存在。如果你用 Cline 或 CC Switch 这类插件配置逻辑一样都是在设置里填这三项。Cline 的 MCP 配置如果涉及工具服务也要确保 Base URL 指向 TaoToken 而不是官方地址否则你的 Key 对不上。配完之后先别急着写 Agent用一条 curl 验证通道是否通curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复 OK 两个字母}], max_tokens: 20 }如果返回里有content: OK之类的正常响应说明通道没问题。如果报 401检查 Key 有没有复制全如果报 model not found检查 Model ID 拼写。这一步过了再往下写 Agent 代码就顺了。3. 可复制的最小 ReAct Agent 配置与工具调用链现在进入正题写一个能跑的最小 ReAct Agent。我不推荐一上来就用 LangChain 或 AutoGen那些框架抽象层太厚出问题你根本不知道是提示词错了还是框架 bug。自己实现一遍 ReAct 循环代码不到 150 行但你能彻底搞懂 Agent 在干什么。先定义工具。Agent 的能力边界由工具决定我们做两个最基础的一个查天气一个算数学。工具定义要符合 Function Calling 的 JSON Schema 格式import os import json from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL] ) # 工具1查天气模拟实现 def get_weather(city: str) - str: fake_data { 北京: 晴25°C湿度40%, 上海: 小雨22°C湿度85%, 深圳: 多云28°C湿度70% } return fake_data.get(city, f{city}暂无数据) # 工具2计算器 def calculate(expression: str) - str: try: result eval(expression, {__builtins__: {}}, {}) return str(result) except Exception as e: return f计算错误{e} # 工具注册表名字 - 函数 TOOL_REGISTRY { get_weather: get_weather, calculate: calculate } # 给 LLM 看的工具描述JSON Schema TOOLS_SCHEMA [ { type: function, function: { name: get_weather, description: 查询指定城市的实时天气, parameters: { type: object, properties: { city: {type: string, description: 城市名如北京} }, required: [city] } } }, { type: function, function: { name: calculate, description: 计算数学表达式支持加减乘除, parameters: { type: object, properties: { expression: {type: string, description: 数学表达式如 23*4} }, required: [expression] } } } ]注意TOOL_REGISTRY和TOOLS_SCHEMA是两套东西前者是实际执行的 Python 函数后者是给模型看的说明书。模型只认 Schema执行时你用名字去 Registry 里找函数。这个「描述与执行分离」的设计是 Function Calling 的核心也是 MCP 协议后来标准化的东西。接下来是 ReAct 提示模板。System Prompt 要明确告诉模型三件事你的角色、可用工具、输出格式。我实测下来这个模板比较稳REACT_SYSTEM_PROMPT 你是一个 ReAct 智能体通过「思考-行动-观察」循环完成任务。 可用工具 - get_weather(city): 查询城市天气 - calculate(expression): 计算数学表达式 工作规则 1. 每次行动前先输出你的思考Thought 2. 需要调用工具时使用 function calling 机制 3. 拿到工具结果后判断是否还需要继续调用 4. 任务完成时直接给出最终答案不要再调用工具 5. 如果连续两次调用同一个工具且参数相同说明陷入循环请换思路或直接回答 请严格按此流程工作。这个提示词里最关键的是第 5 条——防死循环。ReAct 论文没强调这点但生产环境里 Agent 反复调同一个工具是最常见的故障。提前在提示词里打预防针能省很多事。然后是核心循环def run_agent(user_query: str, max_iterations: int 8): messages [ {role: system, content: REACT_SYSTEM_PROMPT}, {role: user, content: user_query} ] for i in range(max_iterations): response client.chat.completions.create( modelclaude-sonnet-4-20250514, messagesmessages, toolsTOOLS_SCHEMA, tool_choiceauto ) msg response.choices[0].message messages.append(msg) # 没有工具调用 → 任务完成 if not msg.tool_calls: return msg.content # 有工具调用 → 逐个执行 for tool_call in msg.tool_calls: name tool_call.function.name args json.loads(tool_call.function.arguments) print(f[第{i1}轮] 调用 {name}({args})) if name in TOOL_REGISTRY: result TOOL_REGISTRY[name](**args) else: result f错误未知工具 {name} print(f[第{i1}轮] 结果{result}) messages.append({ role: tool, tool_call_id: tool_call.id, content: str(result) }) return 达到最大迭代次数任务未完成跑一下if __name__ __main__: answer run_agent(北京和上海哪个城市更适合今天出门先查天气再算下温差) print(最终答案, answer)预期输出会是这样[第1轮] 调用 get_weather({city: 北京}) [第1轮] 结果晴25°C湿度40% [第1轮] 调用 get_weather({city: 上海}) [第1轮] 结果小雨22°C湿度85% [第2轮] 调用 calculate({expression: 25-22}) [第2轮] 结果3 最终答案北京今天晴25°C上海小雨22°C。温差3°C。上海有雨北京更适合出门。这个 Demo 虽然简单但已经包含了 Agent 的全部核心要素工具定义、ReAct 提示、循环控制、结果回传。你把这个骨架换成真实工具数据库查询、API 调用、文件操作就是一个能用的 Agent 了。关于配置文件的补充如果你要把这个 Agent 部署成服务建议把模型配置抽到单独的config.toml[llm] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model claude-sonnet-4-20250514 max_iterations 8 temperature 0.3 [agent] name weather-calc-agent enable_reflection false这样切换模型只改model一行不用动代码。temperature建议设低一点0.2-0.4Agent 场景需要稳定输出不需要创意。4. 验证请求与成功结果从单次调用到多轮循环配置写完了怎么确认它真的在工作我分三层验证先验证模型通道再验证单次工具调用最后验证多轮 ReAct 循环。每层都有明确的成功标志出问题也能快速定位。第一层模型通道验证。用上一节的 curl 命令或者写个最小 Python 脚本from openai import OpenAI import os client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL] ) resp client.chat.completions.create( modelclaude-sonnet-4-20250514, messages[{role: user, content: 只回复通道正常}] ) print(resp.choices[0].message.content)成功标志输出「通道正常」。如果报AuthenticationError是 Key 问题如果报NotFoundError是 Base URL 或 Model ID 问题。这一步不过后面都别谈。第二层单次工具调用验证。把run_agent的输入改成「北京天气怎么样」观察日志。成功标志是看到[第1轮] 调用 get_weather({city: 北京})和对应的结果然后模型基于结果给出回答。如果模型直接回答「北京今天晴」而没有调用工具说明提示词里工具描述不够清晰或者模型没理解tool_choiceauto的含义。这时候可以把tool_choice临时改成{type: function, function: {name: get_weather}}强制调用确认工具链本身是通的。第三层多轮循环验证。用「北京和上海哪个更适合出门」这个查询成功标志是看到至少两轮工具调用两次 get_weather 一次 calculate最后模型综合所有观察结果给出结论。这里有个细节模型可能在第一轮就同时调用两个 get_weather并行工具调用也可能分两轮调用。两种都正常取决于模型实现。Claude 系列倾向于并行调用GPT 系列有时会串行。验证过程中我建议打开详细日志把每轮的messages打印出来。这样你能看到模型实际收到的上下文长什么样。很多 Agent 问题出在上下文管理上——比如工具结果太长把窗口撑爆或者tool_call_id对不上导致模型困惑。日志里一眼就能看出来。一个完整的成功日志应该长这样[第1轮] 调用 get_weather({city: 北京}) [第1轮] 结果晴25°C湿度40% [第1轮] 调用 get_weather({city: 上海}) [第1轮] 结果小雨22°C湿度85% [第2轮] 调用 calculate({expression: 25-22}) [第2轮] 结果3 最终答案北京晴25°C上海小雨22°C温差3°C。上海有雨建议选北京。如果你想让 Agent 更聪明一点可以在循环里加个「反思」环节当工具返回错误时让模型先分析错误原因再重试。这个改动很小就是在result里检测到「错误」关键词时往 messages 里插一条 system 消息提示模型「上一步失败了请分析原因后换一种方式」。我试过对工具调用失败率的降低挺明显。还有一点max_iterations别设太大。8 轮对大多数任务够了设成 20 轮只会让死循环的 Agent 烧更多 Token。配合提示词里的防循环规则8 轮是个平衡点。5. 本篇常见错误排查401、proxy failed、choices 为空怎么解Agent 开发踩坑是常态我把最常见的几类错误和排查路径列出来你对着日志查就行。错误一401 Unauthorized / invalid api key这是最高频的。原因通常有三个Key 没复制全前后有空格、环境变量没生效、Key 被禁用。排查步骤先echo $TAOTOKEN_API_KEY确认变量有值且无空格再用 curl 直接带 Key 请求排除 SDK 干扰如果 curl 也 401去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认 Key 状态。注意 Claude Code 这类工具读的是ANTHROPIC_API_KEY而不是TAOTOKEN_API_KEY变量名写错也会 401。错误二local proxy failed / connection refused这个报错通常出现在你本地配了代理但代理没启动或端口不对。Agent 请求走的是https://taotoken.net/api如果你的环境变量里有HTTP_PROXY或HTTPS_PROXY指向一个不存在的本地端口就会报这个。排查env | grep -i proxy看有没有残留代理配置有就 unset 掉。另外检查防火墙有没有拦 443 出站。错误三reading choices of undefined / choices 为空这个错误说明 API 返回了非预期结构。常见原因Base URL 写成了https://taotoken.net/api/v1多了一层导致请求打到了不存在的路径返回 HTML 错误页而不是 JSON。SDK 解析 HTML 时拿不到choices字段就报这个。解决Base URL 严格用https://taotoken.net/api让 SDK 自己拼/v1/chat/completions。另一个可能是 Model ID 不存在API 返回了错误对象同样没有choices。打印完整response对象就能看到真实错误信息。错误四OAuth / authentication failedClaude Code 场景Claude Code 首次启动会尝试 OAuth 登录官方账号如果你要用 TaoToken 通道得跳过 OAuth 直接配 API Key。在~/.claude/settings.json里写全三件套Base URL API Key Model ID然后启动时如果还弹 OAuth检查是不是有旧的凭据缓存。删掉~/.claude/下的凭据文件重新配。记住用第三方通道时不要走 OAuth 流程直接 API Key 鉴权。错误五Agent 死循环 / 反复调用同一工具这不是报错但比报错更烧钱。表现是日志里同一个工具同样参数出现三次以上。原因模型没意识到自己在重复或者工具一直返回空结果。解决在 System Prompt 里加防循环规则见第 3 节在代码里加重复检测——记录最近 N 次调用的(name, args)哈希重复就强制中断并让模型换思路。另外max_iterations是最后一道防线别省。错误六tool_call_id 不匹配多轮循环时如果你手动构造 messages 而tool_call_id和模型返回的对不上模型会报错或行为异常。解决永远用模型返回的tool_call.id原样回填不要自己生成。用 SDK 的 message 对象直接 append 最安全。排查通用心法先看 HTTP 状态码再看响应体最后看 messages 上下文。90% 的问题在前两步就能定位。剩下 10% 是上下文管理问题打印完整 messages 基本能看出来。6. 语义一致 CTA把 Agent 跑起来之后往哪走到这里你已经有了一个能跑的最小 ReAct Agent通道走 TaoToken 统一接入工具调用链完整错误排查也有章法了。接下来看你的方向如果你主要是在调试模型、对比不同模型在 Agent 场景下的工具调用表现可以直接用模型对话入口 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 快速试不用每次改代码。如果你要把 Agent 接入 Claude Code 做长期编码任务配置文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有 Claude Code 的完整接入步骤和 settings.json 示例。如果你打算做长期的 Agent 开发、跑多轮工具调用和复杂任务编排Coding Plan 更适合 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它的额度模型对高频 Agent 调用更友好。Key 管理和新建密钥还是去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。API 入口固定是 https://taotoken.net/api 记住这个地址所有 SDK 的 base_url 都填它。最后给个实用建议Agent 开发最容易被低估的是「工具描述的质量」。模型能不能正确调用工具八成取决于你的description写得清不清楚。我踩过的坑是工具描述写得太简略模型要么不调用要么传错参数。后来我把每个工具的描述都写成「这个工具做什么 什么时候用 参数含义 返回什么」调用准确率明显上来了。这个细节比换模型管用。
1. 从符号推理到 ReActAgent 到底解决了什么问题大模型智能体LLM Agent这个词在 2026 年已经不算新鲜但很多人第一次接触时还是会把它和「套了系统提示词的聊天机器人」混为一谈。我先把结论放前面Agent 的本质是让模型从「一问一答」变成「多步骤自主执行」而 ReAct 范式是这条路上第一个真正跑通的工程方案。理解它你才能看懂后面 Cursor、Claude Code、Manus 这些产品为什么长成现在这样。先看一个最直观的对比。普通 LLM 应用是这样的用户问「北京今天天气怎么样」模型回答「今天晴25 度」——如果模型知识截止到去年这个答案就是编的。Agent 则是用户说「帮我查下北京天气如果下雨就提醒我带伞」Agent 会先思考「我需要调用天气工具」然后执行工具调用拿到真实数据再判断「今天有雨」最后输出「今天北京有雨记得带伞」。区别在于普通应用是单次推理Agent 是「思考—行动—观察」的循环直到目标完成。这个循环不是凭空冒出来的。1995 年 Russell 和 Norvig 在《人工智能一种现代方法》里就把 Agent 分成四类简单反射型、基于模型型、基于目标型、基于效用型。今天的 LLM Agent 基本落在后两类——它有目标完成任务也有偏好选最优路径。但传统 Agent 的规则是人写死的遇到规则外的情况就傻眼LLM Agent 用模型的推理能力替代了人写规则灵活了但也带来了新问题模型会推理错会幻觉会陷入死循环。2022 年 10 月普林斯顿的 ReAct 论文就是来解决这个矛盾的。它发现纯推理Chain-of-Thought容易胡说因为模型只在脑子里想不去验证纯行动Act-only又容易盲目执行因为没有规划。ReAct 的做法是让两者交替每次行动前先想清楚为什么行动后观察结果再决定下一步。这个「Thought → Action → Observation」的循环后来成了几乎所有 Agent 框架的底层骨架。你可能会问这跟 Function Calling 有什么关系关系很大。ReAct 论文发表时工具调用还得靠提示词「骗」模型输出特定格式格式错误率很高。2023 年 6 月 OpenAI 推出 Function Calling模型原生支持结构化工具调用Agent 的可靠性从 60% 左右跳到 90% 以上。这不是渐进改进是质变——它让 Agent 从演示玩具变成了能上生产的东西。所以你现在看到的任何 Agent 产品底层基本都是「ReAct 循环 Function Calling 工具调用」这套组合。那为什么还要讲概念起源因为不理解演进脉络你调 Agent 时遇到问题就不知道往哪查。比如 Agent 反复调用同一个工具你得知道这是 ReAct 循环缺少「重复检测」比如 Agent 规划得乱七八糟你得知道该上 Plan-and-Execute 模式。这些设计决策都能在历史里找到答案。接下来我先讲怎么用 TaoToken 把模型通道准备好再给你一份能直接跑的最小 ReAct Agent 配置。2. TaoToken 前置准备统一 Key 与 API 通道怎么配在写 Agent 代码之前得先把模型接入这关过了。做 Agent 开发最烦的一件事是你调试时可能想换不同模型对比效果但每个厂商的 API 格式、鉴权方式、Base URL 都不一样代码里到处是 if-else。TaoToken 的价值就在这里——它提供统一的 API 通道你用一套 Key 和一套 Base URL 就能访问多个模型切换模型只改一个 Model ID 字符串。先说清楚它是什么TaoToken 是一个大模型 API 聚合接入服务官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。你注册后在控制台生成 API Key然后所有请求都走这个统一入口。对 Agent 开发来说这意味着你的工具调用链、ReAct 循环代码不用为每个模型改一遍。具体操作步骤。第一步打开控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登录后进入 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 点「创建新密钥」复制生成的 Key。这个 Key 只显示一次建议直接存到环境变量里别硬编码进代码。第二步确认你要用的模型 ID。TaoToken 的模型列表在文档页 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 能查到常见的有 claude-sonnet-4 系列、gpt-4.1 系列、deepseek 系列等。Agent 场景我建议优先选工具调用能力强的模型因为 ReAct 循环里工具调用格式错了整个流程就断了。第三步配置环境变量。Linux/macOS 下这样写export TAOTOKEN_API_KEYsk-你的密钥 export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的密钥 $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api这里有个坑要注意Base URL 结尾不要带/v1TaoToken 的入口就是https://taotoken.net/apiSDK 会自动拼接路径。我见过有人写成https://taotoken.net/api/v1然后报 404排查半天。第四步如果你用的是 Claude Code 这类终端工具它需要单独的配置文件。Claude Code 的配置在~/.claude/settings.json写入{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }注意这里三个要素必须齐全Base URL、API Key、Model ID。少任何一个都会报鉴权失败或模型不存在。如果你用 Cline 或 CC Switch 这类插件配置逻辑一样都是在设置里填这三项。Cline 的 MCP 配置如果涉及工具服务也要确保 Base URL 指向 TaoToken 而不是官方地址否则你的 Key 对不上。配完之后先别急着写 Agent用一条 curl 验证通道是否通curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复 OK 两个字母}], max_tokens: 20 }如果返回里有content: OK之类的正常响应说明通道没问题。如果报 401检查 Key 有没有复制全如果报 model not found检查 Model ID 拼写。这一步过了再往下写 Agent 代码就顺了。3. 可复制的最小 ReAct Agent 配置与工具调用链现在进入正题写一个能跑的最小 ReAct Agent。我不推荐一上来就用 LangChain 或 AutoGen那些框架抽象层太厚出问题你根本不知道是提示词错了还是框架 bug。自己实现一遍 ReAct 循环代码不到 150 行但你能彻底搞懂 Agent 在干什么。先定义工具。Agent 的能力边界由工具决定我们做两个最基础的一个查天气一个算数学。工具定义要符合 Function Calling 的 JSON Schema 格式import os import json from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL] ) # 工具1查天气模拟实现 def get_weather(city: str) - str: fake_data { 北京: 晴25°C湿度40%, 上海: 小雨22°C湿度85%, 深圳: 多云28°C湿度70% } return fake_data.get(city, f{city}暂无数据) # 工具2计算器 def calculate(expression: str) - str: try: result eval(expression, {__builtins__: {}}, {}) return str(result) except Exception as e: return f计算错误{e} # 工具注册表名字 - 函数 TOOL_REGISTRY { get_weather: get_weather, calculate: calculate } # 给 LLM 看的工具描述JSON Schema TOOLS_SCHEMA [ { type: function, function: { name: get_weather, description: 查询指定城市的实时天气, parameters: { type: object, properties: { city: {type: string, description: 城市名如北京} }, required: [city] } } }, { type: function, function: { name: calculate, description: 计算数学表达式支持加减乘除, parameters: { type: object, properties: { expression: {type: string, description: 数学表达式如 23*4} }, required: [expression] } } } ]注意TOOL_REGISTRY和TOOLS_SCHEMA是两套东西前者是实际执行的 Python 函数后者是给模型看的说明书。模型只认 Schema执行时你用名字去 Registry 里找函数。这个「描述与执行分离」的设计是 Function Calling 的核心也是 MCP 协议后来标准化的东西。接下来是 ReAct 提示模板。System Prompt 要明确告诉模型三件事你的角色、可用工具、输出格式。我实测下来这个模板比较稳REACT_SYSTEM_PROMPT 你是一个 ReAct 智能体通过「思考-行动-观察」循环完成任务。 可用工具 - get_weather(city): 查询城市天气 - calculate(expression): 计算数学表达式 工作规则 1. 每次行动前先输出你的思考Thought 2. 需要调用工具时使用 function calling 机制 3. 拿到工具结果后判断是否还需要继续调用 4. 任务完成时直接给出最终答案不要再调用工具 5. 如果连续两次调用同一个工具且参数相同说明陷入循环请换思路或直接回答 请严格按此流程工作。这个提示词里最关键的是第 5 条——防死循环。ReAct 论文没强调这点但生产环境里 Agent 反复调同一个工具是最常见的故障。提前在提示词里打预防针能省很多事。然后是核心循环def run_agent(user_query: str, max_iterations: int 8): messages [ {role: system, content: REACT_SYSTEM_PROMPT}, {role: user, content: user_query} ] for i in range(max_iterations): response client.chat.completions.create( modelclaude-sonnet-4-20250514, messagesmessages, toolsTOOLS_SCHEMA, tool_choiceauto ) msg response.choices[0].message messages.append(msg) # 没有工具调用 → 任务完成 if not msg.tool_calls: return msg.content # 有工具调用 → 逐个执行 for tool_call in msg.tool_calls: name tool_call.function.name args json.loads(tool_call.function.arguments) print(f[第{i1}轮] 调用 {name}({args})) if name in TOOL_REGISTRY: result TOOL_REGISTRY[name](**args) else: result f错误未知工具 {name} print(f[第{i1}轮] 结果{result}) messages.append({ role: tool, tool_call_id: tool_call.id, content: str(result) }) return 达到最大迭代次数任务未完成跑一下if __name__ __main__: answer run_agent(北京和上海哪个城市更适合今天出门先查天气再算下温差) print(最终答案, answer)预期输出会是这样[第1轮] 调用 get_weather({city: 北京}) [第1轮] 结果晴25°C湿度40% [第1轮] 调用 get_weather({city: 上海}) [第1轮] 结果小雨22°C湿度85% [第2轮] 调用 calculate({expression: 25-22}) [第2轮] 结果3 最终答案北京今天晴25°C上海小雨22°C。温差3°C。上海有雨北京更适合出门。这个 Demo 虽然简单但已经包含了 Agent 的全部核心要素工具定义、ReAct 提示、循环控制、结果回传。你把这个骨架换成真实工具数据库查询、API 调用、文件操作就是一个能用的 Agent 了。关于配置文件的补充如果你要把这个 Agent 部署成服务建议把模型配置抽到单独的config.toml[llm] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model claude-sonnet-4-20250514 max_iterations 8 temperature 0.3 [agent] name weather-calc-agent enable_reflection false这样切换模型只改model一行不用动代码。temperature建议设低一点0.2-0.4Agent 场景需要稳定输出不需要创意。4. 验证请求与成功结果从单次调用到多轮循环配置写完了怎么确认它真的在工作我分三层验证先验证模型通道再验证单次工具调用最后验证多轮 ReAct 循环。每层都有明确的成功标志出问题也能快速定位。第一层模型通道验证。用上一节的 curl 命令或者写个最小 Python 脚本from openai import OpenAI import os client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL] ) resp client.chat.completions.create( modelclaude-sonnet-4-20250514, messages[{role: user, content: 只回复通道正常}] ) print(resp.choices[0].message.content)成功标志输出「通道正常」。如果报AuthenticationError是 Key 问题如果报NotFoundError是 Base URL 或 Model ID 问题。这一步不过后面都别谈。第二层单次工具调用验证。把run_agent的输入改成「北京天气怎么样」观察日志。成功标志是看到[第1轮] 调用 get_weather({city: 北京})和对应的结果然后模型基于结果给出回答。如果模型直接回答「北京今天晴」而没有调用工具说明提示词里工具描述不够清晰或者模型没理解tool_choiceauto的含义。这时候可以把tool_choice临时改成{type: function, function: {name: get_weather}}强制调用确认工具链本身是通的。第三层多轮循环验证。用「北京和上海哪个更适合出门」这个查询成功标志是看到至少两轮工具调用两次 get_weather 一次 calculate最后模型综合所有观察结果给出结论。这里有个细节模型可能在第一轮就同时调用两个 get_weather并行工具调用也可能分两轮调用。两种都正常取决于模型实现。Claude 系列倾向于并行调用GPT 系列有时会串行。验证过程中我建议打开详细日志把每轮的messages打印出来。这样你能看到模型实际收到的上下文长什么样。很多 Agent 问题出在上下文管理上——比如工具结果太长把窗口撑爆或者tool_call_id对不上导致模型困惑。日志里一眼就能看出来。一个完整的成功日志应该长这样[第1轮] 调用 get_weather({city: 北京}) [第1轮] 结果晴25°C湿度40% [第1轮] 调用 get_weather({city: 上海}) [第1轮] 结果小雨22°C湿度85% [第2轮] 调用 calculate({expression: 25-22}) [第2轮] 结果3 最终答案北京晴25°C上海小雨22°C温差3°C。上海有雨建议选北京。如果你想让 Agent 更聪明一点可以在循环里加个「反思」环节当工具返回错误时让模型先分析错误原因再重试。这个改动很小就是在result里检测到「错误」关键词时往 messages 里插一条 system 消息提示模型「上一步失败了请分析原因后换一种方式」。我试过对工具调用失败率的降低挺明显。还有一点max_iterations别设太大。8 轮对大多数任务够了设成 20 轮只会让死循环的 Agent 烧更多 Token。配合提示词里的防循环规则8 轮是个平衡点。5. 本篇常见错误排查401、proxy failed、choices 为空怎么解Agent 开发踩坑是常态我把最常见的几类错误和排查路径列出来你对着日志查就行。错误一401 Unauthorized / invalid api key这是最高频的。原因通常有三个Key 没复制全前后有空格、环境变量没生效、Key 被禁用。排查步骤先echo $TAOTOKEN_API_KEY确认变量有值且无空格再用 curl 直接带 Key 请求排除 SDK 干扰如果 curl 也 401去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认 Key 状态。注意 Claude Code 这类工具读的是ANTHROPIC_API_KEY而不是TAOTOKEN_API_KEY变量名写错也会 401。错误二local proxy failed / connection refused这个报错通常出现在你本地配了代理但代理没启动或端口不对。Agent 请求走的是https://taotoken.net/api如果你的环境变量里有HTTP_PROXY或HTTPS_PROXY指向一个不存在的本地端口就会报这个。排查env | grep -i proxy看有没有残留代理配置有就 unset 掉。另外检查防火墙有没有拦 443 出站。错误三reading choices of undefined / choices 为空这个错误说明 API 返回了非预期结构。常见原因Base URL 写成了https://taotoken.net/api/v1多了一层导致请求打到了不存在的路径返回 HTML 错误页而不是 JSON。SDK 解析 HTML 时拿不到choices字段就报这个。解决Base URL 严格用https://taotoken.net/api让 SDK 自己拼/v1/chat/completions。另一个可能是 Model ID 不存在API 返回了错误对象同样没有choices。打印完整response对象就能看到真实错误信息。错误四OAuth / authentication failedClaude Code 场景Claude Code 首次启动会尝试 OAuth 登录官方账号如果你要用 TaoToken 通道得跳过 OAuth 直接配 API Key。在~/.claude/settings.json里写全三件套Base URL API Key Model ID然后启动时如果还弹 OAuth检查是不是有旧的凭据缓存。删掉~/.claude/下的凭据文件重新配。记住用第三方通道时不要走 OAuth 流程直接 API Key 鉴权。错误五Agent 死循环 / 反复调用同一工具这不是报错但比报错更烧钱。表现是日志里同一个工具同样参数出现三次以上。原因模型没意识到自己在重复或者工具一直返回空结果。解决在 System Prompt 里加防循环规则见第 3 节在代码里加重复检测——记录最近 N 次调用的(name, args)哈希重复就强制中断并让模型换思路。另外max_iterations是最后一道防线别省。错误六tool_call_id 不匹配多轮循环时如果你手动构造 messages 而tool_call_id和模型返回的对不上模型会报错或行为异常。解决永远用模型返回的tool_call.id原样回填不要自己生成。用 SDK 的 message 对象直接 append 最安全。排查通用心法先看 HTTP 状态码再看响应体最后看 messages 上下文。90% 的问题在前两步就能定位。剩下 10% 是上下文管理问题打印完整 messages 基本能看出来。6. 语义一致 CTA把 Agent 跑起来之后往哪走到这里你已经有了一个能跑的最小 ReAct Agent通道走 TaoToken 统一接入工具调用链完整错误排查也有章法了。接下来看你的方向如果你主要是在调试模型、对比不同模型在 Agent 场景下的工具调用表现可以直接用模型对话入口 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 快速试不用每次改代码。如果你要把 Agent 接入 Claude Code 做长期编码任务配置文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有 Claude Code 的完整接入步骤和 settings.json 示例。如果你打算做长期的 Agent 开发、跑多轮工具调用和复杂任务编排Coding Plan 更适合 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它的额度模型对高频 Agent 调用更友好。Key 管理和新建密钥还是去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。API 入口固定是 https://taotoken.net/api 记住这个地址所有 SDK 的 base_url 都填它。最后给个实用建议Agent 开发最容易被低估的是「工具描述的质量」。模型能不能正确调用工具八成取决于你的description写得清不清楚。我踩过的坑是工具描述写得太简略模型要么不调用要么传错参数。后来我把每个工具的描述都写成「这个工具做什么 什么时候用 参数含义 返回什么」调用准确率明显上来了。这个细节比换模型管用。
 解决办法：把鼠标控制脚本的调用路径改到 TaoToken)
