Claude Agent SDK 的 agentic loop 省了手写循环但第三方产品默认不能用 claude.ai 登录。TaoToken 给 Key 和 Base URLhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 注册创建 Key模型通道 Base URL 填 https://taotoken.net/api。这篇顺着「从 Prompt 到 Agent」的进阶地图把 Claude Agent SDK 那一节从原生 Anthropic API 的 tool use 一路接到 SDK 的自动循环顺带把认证、模型通道、日志验证和几个常见报错都过一遍。原生 API 时代tool use 是这么写的请求里带上 tools 数组模型返回stop_reasontool_use你在本地执行工具把tool_result拼回messages再发一次请求。单轮对话里模型连续调三次工具你的 while 循环就得转三圈状态管理、并发、错误回灌全落在调用方代码里。Claude Agent SDK 把这套循环收进了框架你只写一次query后面的工具选择、结果回填、再请求SDK 自己管。听起来只是少写几行代码实际是把「编排」这件事从业务代码里拿了出去留给你的只有 prompt、allowed_tools和模型通道。真正让人卡住的不是循环是认证。SDK 文档里写得很清楚第三方产品默认不能用 claude.ai 的登录态要走 API Key。下面按原文第 3 节的节奏展开把每一步落到能跑的配置上。1. 手写 while 循环到 agentic loopagentic loop 到底交给谁1.1 原生 Anthropic API 的 tool use 循环长什么样先用一个简化版的心智模型对齐一下。原生 API 做 tool use本质是「请求—执行—回填—再请求」的四段循环第一段把工具定义塞进tools第二段读stop_reason如果是tool_use就从content里挑出tool_useblock第三段拿name和input去本地执行第四段构造tool_result追加进messages再发。哪一段出问题都要自己接异常、自己决定重试几次、自己判断是否需要换模型。这套写法可控但业务代码会被状态管理稀释。举个日常场景让模型先读README.md再根据内容列出待办再写一个汇总文件。三个工具调用串下来你的循环里就多了三种状态分支工具报错回灌、空结果、权限确认一个都不能少。1.2 ClaudeAgentOptions 里 allowed_tools 和 permission_mode 的分工Agent SDK 把上面那四段收进内部循环暴露给你的接口就两个query()和ClaudeAgentOptions。allowed_tools声明这个会话允许模型调哪些内置工具比如Read、Write、Bashpermission_mode决定遇到写文件、跑命令这类动作时是直接放行还是停下来问。模型选工具、拼参数、拿结果、继续推理这一整段你不参与循环次数由模型和任务复杂度决定。换句话说Agent SDK 负责的是「编排」而不是「认证」。认证和模型通道是另一条独立的线Key 从哪来、请求打到哪里SDK 本身不生产它只读环境变量。这也是为什么第三方接 Claude 时最容易踩坑的地方是环境而不是代码。2. 第三方产品为什么用不了 claude.ai 登录Key 该从哪来2.1 OAuth 登录态和 API Key 认证的差别claude.ai 的登录态是浏览器 OAuth 流程发给官方客户端用的SDK 和第三方工具拿不到这层凭据。你在终端跑claude命令时能看到那条提示要么登录官方账号要么提供 API Key。Agent SDK 走的是第二种它把认证抽象成一组环境变量你喂进去即可。所以接入的路径不是「让 SDK 帮你登录」而是「拿到一把能在兼容通道里用的 Key把它塞给 SDK」。官方 Key 的额度与区域限制往往让开发者后面又要折腾一次这时候统一 API 通道的价值就体现出来了一把 Key 走多个模型Base URL 只换一次。2.2 打开 TaoToken 创建这把 Key具体动作打开 TaoToken 注册账号进控制台创建 API Key。Key 是占位符形式下文统一写作YOUR_API_KEY你自己那把只在你本地环境里用。创建 Key 的入口和模型列表都在同一个控制台里模型 ID 也在那看——不同模型命名不一致别自己拼。这里只做两件事别看漏一是拿 Key二是确认你要用的模型 ID。Key 用于认证模型 ID 用于告诉 SDK 调哪一个Base URL 用于告诉 SDK 请求打到哪里。三件套齐了配置就能一次过。3. 把 Agent SDK 的模型通道指到 TaoToken3.1 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 怎么填Claude Agent SDK 读的环境变量跟 Claude Code 是一套最常用的两个export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENYOUR_API_KEY export ANTHROPIC_MODELYOUR_MODEL_IDANTHROPIC_BASE_URL填https://taotoken.net/api末尾不要带/v1也不要加任何 UTM 参数——那是给网页用的不是给工具用的。ANTHROPIC_AUTH_TOKEN能不能用ANTHROPIC_API_KEY替代Python SDK 两种都读但同一时间只保留一个避免自相矛盾。ANTHROPIC_MODEL是给那些不显式传model的调用兜底用的正式代码里最好还是显式写在ClaudeAgentOptions里。不想每次都 export可以写进 shell 配置或者用.env配上python-dotenv。团队协作时更稳的做法是放在~/.claude/settings.json的env字段里SDK 和 Claude Code 会一起读到{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: YOUR_MODEL_ID } }3.2 别忘了末尾不要带 /v1这一条值得单独说。很多人习惯把 OpenAI 兼容地址写成https://xxx/v1然后在 Anthropic 系 SDK 里直接照搬结果请求路径被拼成/v1/v1/messages这类明显不对的形式返回 404。Agent SDK 的请求拼接规则跟 OpenAI 客户端不一样Base URL 只到/api这一层就够了。填完先在心里默念一遍协议 域名 /api不加路径不加参数。4. 最小 Python 示例query、ClaudeAgentOptions、allowed_tools 跑通 agentic loop4.1 安装 claude-agent-sdkPython 环境建议 3.10 以上虚拟环境里装python -m venv .venv source .venv/bin/activate pip install claude-agent-sdk装完确认一下版本SDK 迭代比较快接口有时候会小改pip show claude-agent-sdk4.2 一个能跑的最小脚本把下面这段存成agent_loop.py。它做的是一件很小的事让模型看一眼当前目录、挑一个 markdown 文件、给一句话总结。任务不复杂但能触发Read这个内置工具agentic loop 至少会转一圈。import asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): options ClaudeAgentOptions( modelYOUR_MODEL_ID, allowed_tools[Read, Bash], permission_modeacceptEdits, system_prompt你是一个谨慎的代码助手读文件前先确认路径。, ) async for message in query( prompt列出当前目录下的 markdown 文件选一个读一下再用一句话总结它的主题。, optionsoptions, ): print(message) if __name__ __main__: asyncio.run(main())跑之前把环境变量设好一把 Key、一个模型 ID、一个 Base URLexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENYOUR_API_KEY export ANTHROPIC_MODELYOUR_MODEL_ID python agent_loop.py模型 ID 从 TaoToken 控制台 的模型广场里抄现成的别自己拼后缀什么日期版本、大小写抄错一个字符就是 404。4.3 从日志确认请求走了 TaoToken 通道跑完脚本屏幕上会陆续吐出事件对象先是一条 system 初始化消息再是 assistant 的文本或工具调用块接着是工具结果最后是结束消息。想确认请求打到了哪两种办法最直接打开一个调试开关让 SDK 把底层 HTTP 请求也打出来翻日志里的 host 是不是taotoken.net。更简单回到 TaoToken 控制台的用量页看刚才那几笔调用有没有记上账。有记录说明 Base URL 和 Key 都对上了没记录说明请求根本没走这条通道。到这一步Agent SDK 的 agentic loop 就算真跑通了。工具选择、结果回填、二次请求都是框架干的你写的只有query和ClaudeAgentOptions。TaoToken 只在这条链路的起点出现一次——给 Key、给 Base URL——循环里没有任何一步经过它。5. 排障对照Agent SDK 报错基本出在这三处5.1 401认证头没送到或者 Key 带错典型表现是脚本刚连上就被拒错误里能看到authentication_error或invalid api key。先检查三件事环境变量名是不是写成了ANTHROPIC_API_KEY和ANTHROPIC_AUTH_TOKEN同时存在Key 前后有没有多复制一个空格或换行.env是否真的被加载。把 Key 从 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 控制台里重新复制一遍通常能解决大部分 401。5.2 404Base URL 末尾多了 /v1或模型 ID 不存在404 一般有两种来源。第一种是 Base URL 被写成https://taotoken.net/api/v1请求路径拼出双/v1服务端找不到路由。第二种是模型 ID 写错比如大小写不一致、多加了日期后缀。逐个排除Base URL 只保留https://taotoken.net/api模型 ID 从模型广场逐字复制。5.3 工具不触发allowed_tools 名字写错或权限挡住日志里只有文本回答没有 tool_use 块多半是allowed_tools里写了个不存在的名字或者permission_mode设得太严。内置工具名区分大小写Read和read是两个东西。先只放一个Read试能触发再逐步加工具。6. 跑通之后去控制台对一下这次 agentic loop脚本跑绿、日志干净、用量页有记录说明这条链路从认证到模型通道都通了。接着可以做几件事按你的使用节奏来想看多模型效果先在 模型对话 里用同一把 Key 发一条测试消息确认模型 ID 与 Base URL 一致。打算把 Agent SDK 长期接进日常开发可以看 Coding Plan 的套餐是否够用再决定要不要扩容。需要新建或轮换 Key直接去 控制台 API Keys 页面一把 Key 对应一组环境变量别在代码里硬编。Claude Code 那侧的环境变量写法跟本文一致细节对照 接入文档改一行就能复用。Agent SDK 把 agentic loop 收进框架之后你真正要维护的东西少了很多剩下最容易反复出错的其实就两处认证和通道。把这两处一次性配好、再在控制台确认一次后面写的是业务逻辑不是管道代码。