1. 为什么你的 Agent 总是“想得多、做得少”很多人第一次写 Agent代码跑起来看着挺像回事模型能输出一段“我先查天气再决定要不要带伞”的推理文本但真到调用工具那一步就卡住了。要么是工具参数拼错要么是模型返回的 JSON 里混了自然语言解析直接抛异常。更常见的情况是你本地跑通了换台机器或者换个模型就报401排查半天发现是 Key 和 Base URL 没对齐。我试过最原始的做法把工具描述硬编码进 system prompt然后让模型输出tool_call标签自己写正则去抠。结果模型稍微换个说法正则就匹配不上整个决策链断掉。后来才明白Agent 的自主决策能力本质上依赖三件事——模型能不能稳定输出结构化意图、工具调用链路能不能被追踪、上下文能不能在多次循环里保持一致。这三件事里任何一环抖动Agent 就会从“自主”退化成“随机”。这篇内容面向的是已经写过基础对话脚本、想往多步决策方向走的开发者。我会用一个“查天气 判断是否带伞 生成建议”的三步任务作为主线把环境准备、统一 Key 接入、工具注册、循环控制、日志核对完整走一遍。你跟着操作最后能拿到一个可复现的 Agent 骨架并且知道每一步的请求到底发到了哪里、返回了什么。核心检索词先摆出来大模型驱动的自主决策系统说白了就是让模型自己决定“下一步调哪个工具、传什么参数、拿到结果后要不要继续”。适合谁适合已经会调chat.completions接口、但一写多步循环就乱套的人。不适合谁如果你连 Python 虚拟环境都没配过建议先补一下基础再回来。我踩过的坑里最典型的一个是模型明明返回了tool_calls字段但我用的 SDK 版本太老解析出来是空的。后来统一升级到支持 function calling 的版本并且把base_url指向同一个入口问题才消失。所以下面第二节会先把“统一入口”这件事讲清楚不然后面所有步骤都是空中楼阁。2. TaoToken 统一 Key 接入把 endpoint 和鉴权一次配好在写 Agent 循环之前得先解决一个工程问题你的代码里会反复出现模型调用如果每次都要换 Key、换地址维护成本极高。更麻烦的是Agent 的多步决策会产生多次请求一旦某次请求的鉴权信息不一致整个链路就会在中间断掉而错误信息往往只告诉你401不告诉你哪一步出的问题。所以我的做法是把所有模型请求的base_url和api_key收敛到一处用环境变量管理。TaoToken 的 API 入口是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 OpenAI 兼容接口的base_url使用。官网入口在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end注册和查看 Key 都在那边操作。这里要强调一个细节很多教程让你把base_url写成带/v1的形式但不同 SDK 对路径拼接的处理不一样。我实测下来用https://taotoken.net/api作为base_url然后让 SDK 自己去拼/chat/completions是最稳的。如果你写成https://taotoken.net/api/v1某些版本的 SDK 会拼成/api/v1/v1/chat/completions直接 404。环境变量这样设export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api然后在 Python 里读取import os from openai import OpenAI client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), )这样写的好处是你的 Agent 代码里不再出现任何硬编码的地址和 Key。换环境、换 Key、甚至临时切到另一个兼容入口都只改环境变量不动业务逻辑。关于 Key 的获取流程不复杂进官网注册然后在控制台里创建 API Key。控制台地址是https://taotoken.net/console创建 Key 的页面在https://taotoken.net/api-keys。创建完复制出来只显示一次丢了就重新建一个。模型对话的调试页面在https://taotoken.net/chat你可以先在那里手动发一条消息确认 Key 是通的再回到代码里跑。这里有个容易忽略的点Agent 的多步决策会消耗比普通对话更多的 token因为每一轮都要把历史消息和工具定义重新发一遍。所以你在控制台里最好开一下用量提醒避免跑循环的时候不知不觉超了预算。另外如果你打算长期跑编码类 Agent可以看看 Coding Plan 的入口https://taotoken.net/coding-plan它针对高频调用场景做了额度设计比按次计费更适合持续运行的 Agent。配置完成后先别急着写 Agent 循环。用一段最小代码验证一下连通性resp client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 只回复两个字通了}], ) print(resp.choices[0].message.content)如果输出“通了”说明 Key 和地址都对。如果报401先检查 Key 有没有复制完整如果报local proxy failed检查你的网络环境是否把请求拦了如果报model not found检查模型名拼写。这一步过了再往下走。3. 可复制的 Agent 配置工具定义与循环控制现在进入核心部分。一个能自主决策的 Agent代码结构上分三块工具注册表、决策循环、结果解析。工具注册表告诉模型“有哪些工具可用”决策循环负责“调模型 → 解析工具调用 → 执行工具 → 把结果塞回上下文 → 再调模型”结果解析负责从最终回复里提取人类可读的答案。先定义工具。这里用两个最简单的工具做演示查天气和判断是否带伞。实际项目中你可以换成数据库查询、API 调用、文件读写。tools [ { type: function, function: { name: get_weather, description: 查询指定城市的当前天气, parameters: { type: object, properties: { city: { type: string, description: 城市名称例如北京、上海, } }, required: [city], }, }, }, { type: function, function: { name: need_umbrella, description: 根据天气状况判断是否需要带伞, parameters: { type: object, properties: { condition: { type: string, description: 天气状况例如晴、小雨、大雨, } }, required: [condition], }, }, }, ]注意description字段的写法。模型靠这个字段决定“什么时候调这个工具”所以描述要写清楚输入是什么、输出是什么。我见过有人把描述写成“查询天气”结果模型在用户问“今天热不热”的时候也去调天气工具但其实应该先调温度工具。描述越具体模型的决策越准。接下来是工具的实际执行函数def get_weather(city: str) - str: fake_db {北京: 晴, 上海: 小雨, 广州: 大雨} return fake_db.get(city, 未知) def need_umbrella(condition: str) - str: if 雨 in condition: return 需要带伞 return 不需要带伞 TOOL_MAP { get_weather: get_weather, need_umbrella: need_umbrella, }然后是决策循环。这是 Agent 的“大脑”所在import json def run_agent(user_input: str, max_steps: int 5): messages [ {role: system, content: 你是一个自主决策助手按需调用工具不要编造工具结果。}, {role: user, content: user_input}, ] for step in range(max_steps): resp client.chat.completions.create( modelgpt-4o-mini, messagesmessages, toolstools, tool_choiceauto, ) msg resp.choices[0].message messages.append(msg) if not msg.tool_calls: return msg.content for call in msg.tool_calls: fn_name call.function.name fn_args json.loads(call.function.arguments) result TOOL_MAP[fn_name](**fn_args) messages.append({ role: tool, tool_call_id: call.id, content: str(result), }) return 达到最大步数任务未完成这段代码的关键点有三个。第一messages.append(msg)把模型的工具调用意图也存进历史这样下一轮模型能看到自己之前决定调什么。第二tool_call_id必须和模型返回的id对上否则模型不知道哪个结果对应哪个调用。第三max_steps是保险丝防止模型陷入死循环。跑一下print(run_agent(上海今天天气怎么样需要带伞吗))预期输出类似“上海今天是小雨需要带伞。” 整个过程中模型先调get_weather拿到“小雨”再调need_umbrella拿到“需要带伞”最后组织语言回复。这就是一个最小可用的自主决策系统。如果你用的是 Claude Code 或者类似的编码 Agent配置方式略有不同。Claude Code 的配置文件通常在~/.claude/settings.json你需要把base_url和api_key写进去。具体路径和字段名以官方文档为准接入文档在https://taotoken.net/doc。Cline 的 MCP 配置则是在cline_mcp_settings.json里加 server 定义Codex 的auth.json里填 Key 和地址。不管哪种核心三件套不变Base URL、Key、Model ID。4. 验证请求与核对日志确认调用链真的稳代码跑通不等于链路稳。Agent 的多步决策会产生多次请求你需要确认每一次请求都打到了正确的地址、带了正确的 Key、返回了预期的结构。最直接的办法是打开调试日志。在 Python 里把 OpenAI SDK 的日志级别调高import logging logging.basicConfig(levellogging.DEBUG)这样每次请求的 URL、headers、body 都会打印出来。你会看到类似这样的输出POST https://taotoken.net/api/chat/completions Headers: {Authorization: Bearer sk-..., Content-Type: application/json} Body: {model: gpt-4o-mini, messages: [...], tools: [...]}重点核对三件事URL 是不是https://taotoken.net/api/chat/completionsAuthorization 头是不是Bearer开头body 里的tools字段有没有被正确序列化。如果 URL 里出现了双斜杠或者多余的/v1说明base_url配错了。另一个验证手段是看返回的usage字段。每次请求都会返回 token 消耗print(resp.usage)多步任务跑下来prompt_tokens会逐轮增加因为历史消息在累积。如果你发现prompt_tokens增长异常快可能是工具定义太长或者历史消息没有做裁剪。这时候可以考虑只保留最近 N 轮对话或者把工具定义压缩。还有一个实战技巧给每次请求打上trace_id。虽然 OpenAI 兼容接口不强制要求但你可以在extra_headers里塞一个自定义字段resp client.chat.completions.create( modelgpt-4o-mini, messagesmessages, toolstools, extra_headers{X-Trace-Id: agent-run-001}, )这样在排查问题时你可以按trace_id把所有相关请求串起来。我试过在一个 8 步的任务里靠这个字段快速定位到第 5 步的工具参数传错了。验证成功后你应该能看到完整的决策链用户提问 → 模型决定调get_weather→ 工具返回“小雨” → 模型决定调need_umbrella→ 工具返回“需要带伞” → 模型生成最终回复。每一步的请求和响应都能在日志里找到对应记录。如果中间某一步断了日志会告诉你断在哪。对于更复杂的 Agent比如需要多轮工具调用的数据分析场景建议把每次工具调用的输入输出单独存一份 JSON 日志。这样即使模型最终回复错了你也能回溯到是哪一步的工具结果有问题。5. 常见报错排查401、local proxy failed、reading choices、OAuthAgent 开发过程中遇到的报错大部分集中在鉴权、网络、解析这三类。下面按真实报错信息逐一拆解。401 Unauthorized这是最常见的。原因通常是 Key 没设对、Key 过期、或者 Key 和地址不匹配。排查顺序先确认环境变量TAOTOKEN_API_KEY有没有被正确读取可以在代码里打印os.getenv(TAOTOKEN_API_KEY)[:8]看前几位再确认base_url是不是https://taotoken.net/api最后去控制台确认 Key 的状态是“启用”。如果用的是 Claude Code检查settings.json里的api_key字段有没有写错位置。local proxy failed这个报错说明请求在到达服务端之前就被本地网络层拦了。常见原因是系统代理设置和代码里的代理配置冲突。如果你在代码里设了http_proxy环境变量但本地代理服务没开就会报这个。解决办法是检查环境变量HTTP_PROXY和HTTPS_PROXY如果不需要代理就清掉。另外某些企业网络会拦截外部 API 请求这种情况需要联系网络管理员。reading choices这个报错通常出现在解析响应的时候比如resp.choices[0]报IndexError或者KeyError。原因是响应结构和你预期的不一样。可能是模型返回了错误信息而不是正常回复也可能是 SDK 版本不兼容。排查方法先把原始响应打印出来print(resp)看choices字段是否存在。如果不存在看error字段里写了什么。常见的是模型名写错比如把gpt-4o-mini写成gpt-4-mini。OAuth 相关报错如果你用的是 Claude Code 或者 Codex 这类工具可能会遇到 OAuth 认证失败。这类工具通常有自己的认证流程你需要确认auth.json或者settings.json里的字段名是否正确。比如 Codex 的auth.json里需要填api_key和base_url字段名写错就会报 OAuth 错误。建议直接对照接入文档https://taotoken.net/doc里的示例逐字段核对。还有一个隐蔽的坑工具调用的参数解析失败。模型返回的arguments是一个 JSON 字符串如果模型输出了非法 JSONjson.loads会抛异常。解决办法是加一层 try-except并且在 system prompt 里强调“工具参数必须是合法 JSON”。如果模型频繁输出非法 JSON可以考虑换一个 function calling 能力更强的模型。排查完这些你的 Agent 应该能稳定跑完多步任务了。如果还有问题去模型对话页面https://taotoken.net/chat手动发一条同样的请求对比代码里的请求差异通常能快速定位。6. 把 Agent 跑起来之后下一步做什么到这里你已经有了一个能自主决策的 Agent 骨架统一 Key 接入、工具注册、循环控制、日志核对、报错排查整条链路都走了一遍。接下来可以往三个方向扩展。第一个方向是记忆系统。现在的 Agent 每次运行都是无状态的历史消息在循环结束后就丢了。你可以加一个简单的向量库把每次任务的输入输出存起来下次遇到相似问题时先检索历史。这样 Agent 就能“记住”之前处理过的城市天气模式减少重复调用。第二个方向是多工具编排。现在的工具只有两个实际场景可能需要查数据库、发邮件、生成图表。工具越多模型的决策难度越大。这时候可以用状态机约束模型的选择范围比如在“查询阶段”只允许调查询类工具在“生成阶段”只允许调输出类工具。第三个方向是评估与监控。Agent 的效果不能只看最终回复对不对还要看中间步骤是否合理。你可以记录每次工具调用的耗时、成功率、参数准确率形成一个简单的评估面板。长期跑下来这些数据能帮你发现模型的薄弱环节。如果你打算把 Agent 用到编码场景比如自动修 bug、生成测试用例可以看看 Coding Plan 的额度方案https://taotoken.net/coding-plan它针对高频调用做了优化。接入文档在https://taotoken.net/docAPI Key 管理在https://taotoken.net/api-keys。模型对话调试在https://taotoken.net/chat官网入口在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end。最后留一个实用技巧在 Agent 的 system prompt 里加一句“如果工具返回的结果不足以回答问题明确说明缺少什么信息不要编造”。这句话能显著降低幻觉率。我实测下来加了这句话之后模型在工具返回“未知”时会老老实实说“没有查到该城市的天气”而不是瞎编一个“晴”。