1. Anthropic Agent SDK 内置工具到底解决什么问题Anthropic Agent SDK 是一套让开发者用代码驱动 Claude 完成复杂任务的工具库它把 Claude Code 背后的同一套引擎以库的形式暴露出来。你可以把它理解成一个「可编程的 AI 执行器」你给它一个目标它会自己决定调用哪些工具、按什么顺序执行、遇到错误怎么回退。它适合谁适合已经用过 Claude API 做简单对话、但发现「模型只会说不会做」的开发者也适合想把代码审查、批量重构、自动化测试这类重复劳动交给 Agent 的团队。我最初接触它时的困惑很典型模型能写代码但没法读我项目里的文件没法跑测试没法搜索代码库。每次都要手动把文件内容贴进 prompt上下文很快就爆了。Anthropic Agent SDK 的 18 内置工具正是为了解决这个断层——Read、Write、Edit 负责文件操作Bash 系列负责命令执行Glob、Grep 负责搜索Task 负责子代理编排TodoWrite 负责任务列表管理MCP 系列负责外部服务集成。这些工具不是孤立的 API而是一套协同工作的执行体系。核心检索词先明确Anthropic Agent SDK 是什么它是驱动 Claude Code 的同一引擎的编程接口。能做什么让 Claude 自主读写文件、执行命令、搜索代码、编排子代理、管理任务进度。适合谁想快速上手 AI Agent 构建的开发者尤其是需要处理多步骤、多文件、多工具协作场景的人。这套工具体系最值得关注的设计是「工具即能力边界」。你授予哪些工具Agent 就能做哪些事你不给 Bash它就碰不了命令行你不给 Write它就改不了文件。这种显式授权模型让 Agent 的行为可预测、可审计。下面我会从环境准备开始一步步带你跑通内置工具链包括可复制的配置片段和本地验证步骤。2. TaoToken 前置准备拿到 Base URL 和 API Key在跑通 Anthropic Agent SDK 之前你需要一个能访问 Claude 模型的入口。TaoToken 提供了兼容 Anthropic 接口的调用方式你可以在它的控制台创建 API Key然后拿到 Base URL。这一步不复杂但有几个细节容易踩坑。首先访问官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号。注册完成后进入控制台地址是 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。创建时建议给它起个有意义的名字比如「agent-sdk-test」方便后续管理。拿到 Key 之后你需要确认 Base URL。TaoToken 的 API 入口是 https://taotoken.net/api 注意这个地址不带 UTM 参数直接用于代码配置。如果你用的是 Anthropic 官方 SDK需要把 base_url 指向这个地址。有些开发者会忘记改 base_url结果请求发到官方端点导致 401这是最常见的错误之一。环境变量配置建议这样写export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的实际Key如果你用 Python可以在代码里显式传入import os from anthropic import Anthropic client Anthropic( base_urlos.environ.get(ANTHROPIC_BASE_URL, https://taotoken.net/api), api_keyos.environ.get(ANTHROPIC_API_KEY) )如果你用 Node.js配置方式类似import Anthropic from anthropic-ai/sdk; const client new Anthropic({ baseURL: process.env.ANTHROPIC_BASE_URL || https://taotoken.net/api, apiKey: process.env.ANTHROPIC_API_KEY });这里有个关键点Anthropic Agent SDK 的包名是anthropic-ai/claude-agent-sdkPython 版是claude-agent-sdk它和基础的anthropic-ai/sdk是两个不同的包。Agent SDK 封装了工具调用循环、子代理编排、权限控制等能力而基础 SDK 只提供原始的 messages 接口。你要跑内置工具链必须用 Agent SDK。安装命令# Node.js npm install anthropic-ai/claude-agent-sdk # Python pip install claude-agent-sdk安装完成后你可以先用一个最小请求验证 Key 和 Base URL 是否配置正确。如果这一步返回 401说明 Key 无效或 Base URL 写错了如果返回 404说明路径不对。确认基础连通性之后再进入下一步配置内置工具。3. 可复制配置Agent SDK 工具链配置片段这一节是全文的核心我会给出可直接复制的配置片段覆盖 Agent SDK 的初始化、工具授权、子代理定义和 MCP 集成。你把这些片段拼起来就能跑通一个带内置工具链的 Agent。先看最基础的 Agent 初始化配置。以 Node.js 为例创建一个agent-config.tsimport { query, AgentDefinition } from anthropic-ai/claude-agent-sdk; const options { model: claude-sonnet-4-20250514, allowedTools: [ Read, Write, Edit, Glob, Grep, Bash, BashOutput, KillBash, TodoWrite, Task ], permissionMode: acceptEdits, maxTurns: 50, systemPrompt: { type: preset, preset: claude_code } }; async function runAgent(prompt: string) { for await (const message of query({ prompt, options })) { if (message.type assistant) { for (const block of message.message.content) { if (text in block) { console.log(block.text); } else if (name in block) { console.log([工具调用] ${block.name}); } } } } } runAgent(分析当前目录下的 TypeScript 文件找出所有 TODO 注释并生成报告);这段配置的关键参数说明参数作用建议值model指定使用的模型claude-sonnet-4-20250514allowedTools授权可用的工具列表按需最小化permissionMode权限模式acceptEdits 或 interactivemaxTurns最大对话轮次50-250systemPrompt系统提示显式指定 claude_code preset注意systemPrompt这个字段。新版 Agent SDK 不再默认使用 Claude Code 的系统提示你必须显式指定{ type: preset, preset: claude_code }否则 Agent 的行为会和预期不一致。这是从旧版claude-code-sdk迁移时最容易忽略的破坏性变更。接下来配置子代理。子代理通过agents字段定义每个子代理有自己的工具集和模型const agents: Recordstring, AgentDefinition { security-reviewer: { description: 安全审查专家用于检测漏洞, prompt: 你是安全专家。分析代码中的 - SQL 注入风险 - XSS 漏洞 - 认证授权问题 - 敏感数据暴露, tools: [Read, Grep, Glob], model: claude-opus-4-20250514 }, test-analyzer: { description: 测试覆盖率分析专家, prompt: 你是测试专家。分析 - 测试覆盖率缺口 - 缺失的边界情况 - 测试质量建议, tools: [Read, Grep, Glob], model: claude-haiku-4-20250514 } }; const optionsWithAgents { ...options, allowedTools: [...options.allowedTools, Task], agents };这里有个设计要点安全审查用 Opus 保证质量测试分析用 Haiku 控制成本。子代理的模型可以独立指定这是 Task 工具的核心优势之一。再配置 MCP 服务器。MCP 让 Agent 能连接外部服务比如 GitHub、数据库、文件系统const mcpConfig { mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /path/to/project] } }, allowedTools: [ListMcpResources, ReadMcpResource] };如果你用 Python配置结构类似只是语法不同from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition options ClaudeAgentOptions( modelclaude-sonnet-4-20250514, allowed_tools[Read, Write, Edit, Glob, Grep, Bash, TodoWrite, Task], permission_modeacceptEdits, max_turns50, system_prompt{type: preset, preset: claude_code}, agents{ security-reviewer: AgentDefinition( description安全审查专家, prompt分析代码安全问题, tools[Read, Grep, Glob], modelclaude-opus-4-20250514 ) } )把这些片段保存为配置文件后你的 Agent 就具备了完整的工具链能力。下一步是验证它是否真的能跑通。4. 验证请求跑通内置工具链并观察结果配置写好了怎么确认它真的在工作我建议用一个具体的、可观察的任务来验证让 Agent 读取当前目录、搜索特定模式、生成一份报告。这个任务会依次触发 Glob、Grep、Read、Write 四个工具能一次性验证工具链的连通性。先准备一个测试目录放几个文件mkdir -p /tmp/agent-test/src cat /tmp/agent-test/src/app.ts EOF // TODO: 添加错误处理 export function fetchData(url: string) { return fetch(url).then(r r.json()); } // FIXME: 硬编码的 API 地址 const API_URL https://api.example.com/v1; EOF cat /tmp/agent-test/src/utils.ts EOF // TODO: 重构这个函数 export function formatDate(d: Date) { return d.toISOString().split(T)[0]; } EOF然后运行验证脚本import { query } from anthropic-ai/claude-agent-sdk; async function verifyToolchain() { const prompt 在 /tmp/agent-test 目录下执行以下任务 1. 用 Glob 找出所有 .ts 文件 2. 用 Grep 搜索所有 TODO 和 FIXME 注释 3. 用 Read 读取包含这些注释的文件 4. 用 Write 生成一份 report.md列出所有待办项及其位置; for await (const message of query({ prompt, options: { model: claude-sonnet-4-20250514, allowedTools: [Glob, Grep, Read, Write], permissionMode: acceptEdits, maxTurns: 30, systemPrompt: { type: preset, preset: claude_code } } })) { if (message.type assistant) { for (const block of message.message.content) { if (text in block) { console.log(block.text); } else if (name in block) { console.log(→ 调用工具: ${block.name}); } } } if (message.type result) { console.log(任务完成成本:, message.total_cost_usd); } } } verifyToolchain();运行后你应该看到类似输出→ 调用工具: Glob → 调用工具: Grep → 调用工具: Read → 调用工具: Read → 调用工具: Write 任务完成成本: 0.0234然后检查/tmp/agent-test/report.md是否生成内容应该包含两个文件的 TODO 和 FIXME 列表。如果文件生成了但内容为空说明 Grep 的 pattern 没匹配上如果工具调用卡在某个环节检查allowedTools是否包含了对应工具。再验证 Task 子代理。用一个需要多专家协作的任务const prompt 对 /tmp/agent-test 执行全面审查 - 使用 security-reviewer 检查安全问题 - 使用 test-analyzer 分析测试覆盖; for await (const message of query({ prompt, options: { model: claude-sonnet-4-20250514, allowedTools: [Read, Grep, Glob, Task], permissionMode: acceptEdits, maxTurns: 100, systemPrompt: { type: preset, preset: claude_code }, agents: { security-reviewer: { description: 安全审查专家, prompt: 分析代码安全问题, tools: [Read, Grep, Glob], model: claude-opus-4-20250514 }, test-analyzer: { description: 测试分析专家, prompt: 分析测试覆盖, tools: [Read, Grep, Glob], model: claude-haiku-4-20250514 } } } })) { if (message.type assistant) { for (const block of message.message.content) { if (name in block block.name Task) { console.log(委托给子代理: ${(block.input as any).subagent_type}); } } } }看到委托给子代理: security-reviewer和委托给子代理: test-analyzer的输出说明 Task 工具正常工作。子代理会独立运行只把关键结果返回给主代理这就是上下文隔离的价值。验证 TodoWrite 也很简单给一个多步骤任务const prompt 重构 /tmp/agent-test/src/app.ts 1. 添加错误处理 2. 把硬编码 API 地址改为环境变量 3. 运行 TypeScript 编译检查;Agent 会先用 TodoWrite 创建任务列表你能在输出里看到in_progress、pending、completed状态的变化。如果没看到 TodoWrite 调用检查allowedTools里是否包含了它。5. 常见报错排查401、local proxy failed、reading choices跑 Agent SDK 的过程中有几个报错几乎每个人都会遇到。我把它们和对应的排查路径整理出来你对照着看。401 Unauthorized这是最常见的错误表现为请求直接被拒绝。原因通常有三个API Key 写错了、Base URL 没改、环境变量没生效。排查步骤# 确认环境变量已设置 echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_API_KEY # 确认 Base URL 是 https://taotoken.net/api # 确认 Key 以 sk- 开头且没有多余空格如果你在代码里硬编码了 Key检查有没有把sk-前缀漏掉。如果用的是.env文件确认加载顺序正确。还有一个隐蔽的坑某些终端会缓存旧的环境变量改完.env后需要重新打开终端或source .env。local proxy failed / connection refused这个报错说明 SDK 尝试连接一个本地代理但失败了。常见原因是你的环境里设置了HTTP_PROXY或HTTPS_PROXY环境变量但代理服务没运行。排查# 检查代理环境变量 env | grep -i proxy # 如果有临时清除 unset HTTP_PROXY unset HTTPS_PROXY unset ALL_PROXY清除后重新运行。如果你确实需要走代理确保代理服务在运行且端口正确。注意Agent SDK 的请求会走你配置的 Base URL如果 Base URL 是https://taotoken.net/api就不应该再经过本地代理。reading choices of undefined这个报错通常出现在响应解析阶段说明 SDK 收到的响应格式和预期不符。原因可能是 Base URL 指向了一个不兼容 Anthropic 接口的端点或者请求路径拼错了。排查# 确认 Base URL 结尾没有多余的斜杠 # 正确: https://taotoken.net/api # 错误: https://taotoken.net/api/另外检查你用的 SDK 版本。Agent SDK 和基础 SDK 的响应解析逻辑不同如果你混用了两个包可能出现字段不匹配。确认package.json里装的是anthropic-ai/claude-agent-sdk而不是anthropic-ai/sdk。OAuth token 相关错误如果你看到OAuth token expired或invalid_grant说明你用的是 OAuth 认证方式而不是 API Key。Agent SDK 支持两种认证API Key 和 OAuth。如果你在 TaoToken 控制台创建的是 API Key就确保代码里用的是apiKey字段而不是authToken。两者不要混用。工具调用被拒绝 / permission deniedAgent 尝试调用某个工具但被权限系统拦截。检查allowedTools列表是否包含该工具。比如你想让 Agent 执行 Bash 命令但allowedTools里只有Read和Grep就会报权限错误。另外permissionMode设为interactive时每次工具调用都需要确认如果你在非交互环境运行会一直卡住。改成acceptEdits或bypassPermissions仅限可信环境。子代理无法创建子子代理这是设计限制不是 bug。子代理的工具列表里即使包含Task它也会报告该工具不可用。如果你需要多层代理得在主代理层面编排而不是让子代理再嵌套。MCP 服务器启动失败如果 MCP 相关工具报错先单独测试 MCP 服务器能否启动npx -y modelcontextprotocol/server-filesystem /tmp/agent-test如果这个命令本身失败说明是 MCP 服务器的问题不是 Agent SDK 的问题。检查 Node.js 版本、网络连通性、路径是否存在。排查完这些你的 Agent 应该能稳定运行了。如果还有问题可以去接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 查更详细的接口说明。6. 从工具链到生产长期编码与 Agent 工作流跑通内置工具链只是起点。真正让 Agent SDK 发挥价值的地方是把它接入日常开发流程让 Agent 承担重复性高、步骤固定的任务。这一节我分享几个实际可用的工作流以及怎么用 Coding Plan 控制长期成本。第一个工作流是「代码审查自动化」。你可以在 CI 里加一个步骤每次 PR 提交时触发 Agent 审查async function reviewPR(diffPath: string) { const prompt 读取 ${diffPath} 中的代码变更执行 1. 用 Grep 检查是否引入敏感信息API_KEY、SECRET、PASSWORD 2. 用 Read 读取变更文件 3. 分析潜在的安全问题和逻辑错误 4. 用 Write 生成 review.md; for await (const message of query({ prompt, options: { allowedTools: [Read, Grep, Write, Task], permissionMode: acceptEdits, maxTurns: 80, systemPrompt: { type: preset, preset: claude_code }, agents: { security-reviewer: { description: 安全审查, prompt: 检查安全漏洞, tools: [Read, Grep], model: claude-opus-4-20250514 } } } })) { // 处理输出 } }这个工作流的关键是子代理用 Opus 保证审查质量主代理用 Sonnet 控制成本。一次 PR 审查的成本通常在几美分到几十美分之间取决于 diff 大小。第二个工作流是「批量重构」。当你需要把某个模式替换到几十个文件时Agent 的 Glob Read Edit 组合比手动改快得多const prompt 把所有 .ts 文件中的 console.log 替换为 logger.info 1. 用 Glob 找出所有 .ts 文件 2. 用 Grep 定位包含 console.log 的文件 3. 用 Read 读取每个文件 4. 用 Edit 逐个替换 5. 用 Bash 运行 tsc 检查编译;注意这里用 Edit 而不是 Write因为 Edit 只替换目标字符串保留文件其他内容风险更低。批量操作时建议先用permissionMode: interactive跑一遍确认 Agent 的修改符合预期后再切到acceptEdits。第三个工作流是「MCP 驱动的外部集成」。当你的 Agent 需要访问 GitHub、数据库、监控系统时MCP 是标准化的接入方式。比如接入 GitHub MCPconst options { mcpServers: { github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN } } }, allowedTools: [Read, Grep, ListMcpResources, ReadMcpResource] };这样 Agent 就能读取 issue、PR、代码仓库信息结合内置的 Read/Grep 做更复杂的分析。长期跑这些工作流成本是需要关注的。TaoToken 的 Coding Plan 提供了更适合持续编码场景的计费方式地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。如果你的 Agent 每天都要跑几十次任务用 Coding Plan 比按量计费更划算。具体选哪个取决于你的调用频率和任务复杂度。如果你想先手动测试模型能力可以用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 快速验证 prompt 效果确认没问题再写进 Agent 配置。最后说一个实际经验Agent SDK 的工具链能力很强但不要一次性把所有工具都授权给 Agent。最小权限原则在这里同样适用。先给 Read Grep Glob跑通只读分析确认稳定后再加 Write 和 EditBash 最后加并且用bashPatterns限制可执行的命令范围。这样即使 Agent 判断失误影响范围也可控。