企业官网建设流程全解析

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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 注册账号。注册完成后进入控制台，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。在控制台里找到 API Keys 页面，路径是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，创建一个新的 Key。创建时建议给它起个有意义的名字，比如「agent-sdk-test」，方便后续管理。

拿到 Key 之后，你需要确认 Base URL。TaoToken 的 API 入口是 https://taotoken.net/api ，注意这个地址不带 UTM 参数，直接用于代码配置。如果你用的是 Anthropic 官方 SDK，需要把 base_url 指向这个地址。有些开发者会忘记改 base_url，结果请求发到官方端点导致 401，这是最常见的错误之一。

环境变量配置建议这样写：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的实际Key"

如果你用 Python，可以在代码里显式传入：

import os from anthropic import Anthropic client = Anthropic( base_url=os.environ.get("ANTHROPIC_BASE_URL", "https://taotoken.net/api"), api_key=os.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-sdk（Python 版是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.ts：

import { 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 注释并生成报告");

这段配置的关键参数说明：

注意systemPrompt这个字段。新版 Agent SDK 不再默认使用 Claude Code 的系统提示，你必须显式指定{ type: "preset", preset: "claude_code" }，否则 Agent 的行为会和预期不一致。这是从旧版claude-code-sdk迁移时最容易忽略的破坏性变更。

接下来配置子代理。子代理通过agents字段定义，每个子代理有自己的工具集和模型：

const agents: Record<string, 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( model="claude-sonnet-4-20250514", allowed_tools=["Read", "Write", "Edit", "Glob", "Grep", "Bash", "TodoWrite", "Task"], permission_mode="acceptEdits", max_turns=50, system_prompt={"type": "preset", "preset": "claude_code"}, agents={ "security-reviewer": AgentDefinition( description="安全审查专家", prompt="分析代码安全问题", tools=["Read", "Grep", "Glob"], model="claude-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 denied

Agent 尝试调用某个工具但被权限系统拦截。检查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_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 查更详细的接口说明。

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 MCP：

const 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_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。如果你的 Agent 每天都要跑几十次任务，用 Coding Plan 比按量计费更划算。具体选哪个，取决于你的调用频率和任务复杂度。

如果你想先手动测试模型能力，可以用模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite 快速验证 prompt 效果，确认没问题再写进 Agent 配置。

最后说一个实际经验：Agent SDK 的工具链能力很强，但不要一次性把所有工具都授权给 Agent。最小权限原则在这里同样适用。先给 Read + Grep + Glob，跑通只读分析；确认稳定后再加 Write 和 Edit；Bash 最后加，并且用bashPatterns限制可执行的命令范围。这样即使 Agent 判断失误，影响范围也可控。