The Complete Guide to Building Agents with the Claude Agent SDK 使用 Claude Agent SDK 构建智能体的完整指南
If you’ve used Claude Code, you’ve seen what an AI agent can actually do: read files, run commands, edit code, figure out the steps to accomplish a task. 如果你使用过 Claude Code，你就知道 AI 代理实际上能做什么：读取文件、运行命令、编辑代码、找出完成任务所需的步骤。 And you know it doesn’t just help you write code, it takes ownership of problems and works through them the way a thoughtful engineer would. 你也知道，它不仅仅帮助你编写代码，还会主动承担问题，像一位细心的工程师一样去解决它们。 The Claude Agent SDK is the same engine, yours to point at whatever problem you want, so you can easily build agents of your own. Claude Agent SDK 使用的是相同的引擎，你可以将其指向任何你想要解决的问题，轻松构建属于你自己的智能代理。 It’s the infrastructure behind Claude Code, exposed as a library. You get the agent loop, the built-in tools, the context management, basically everything you’d otherwise have to build yourself. 这是 Claude Code 背后的基础设施，现已作为库公开。你可以获得代理循环、内置工具、上下文管理功能，基本上所有原本需要自行构建的内容都已包含在内。 This guide walks through building a code review agent from scratch. By the end, you’ll have something that can analyze a codebase, find bugs and security issues, and return structured feedback. 本指南将带你从零开始构建一个代码审查代理。完成之后，你将拥有一款能够分析代码库、发现漏洞和安全问题，并返回结构化反馈的工具。 More importantly, you’ll understand how the SDK works so you can build whatever you actually need. 更重要的是，你将理解 SDK 的工作原理，从而能够构建真正需要的功能。 What we’re building 我们正在构建的内容
Our code review agent will: 我们的代码审查代理将： Analyze a codebase for bugs and security issues 分析代码库中的错误和安全问题 Read files and search through code autonomously 自主读取文件并在代码中进行搜索 Provide structured, actionable feedback 提供结构化且可操作的反馈 Track its progress as it works 跟踪其运行进度 The stack 堆栈
• Runtime - Claude Code CLI • SDK - @anthropic-ai/claude-agent-sdk • Language - TypeScript • Model - Claude Opus 4.5 • 运行时 - Claude Code CLI • SDK - @anthropic-ai/claude-agent-sdk • 语言 - TypeScript • 模型 - Claude Opus 4.5 What the SDK gives you SDK 提供的功能
If you’ve built agents with the raw API, you know the pattern: call the model, check if it wants to use a tool, execute the tool, feed the result back, repeat until done. This can get tedious when building anything non-trivial. 如果你使用原始 API 构建过智能体，就会熟悉这个模式：调用模型，检查它是否需要使用工具，执行工具，将结果反馈回去，重复此过程直到完成。当构建非简单任务时，这种流程会变得非常繁琐。
The SDK handles that loop:
SDK 会处理这个循环：
typescript
// Without the SDK: You manage the loop
let response = await client.messages.create({...});
while (response.stop_reason === "tool_use") {
const result = yourToolExecutor(response.tool_use);
response = await client.messages.create({ tool_result: result, ... });
}
// With the SDK: Claude manages it
for await (const message of query({ prompt: "Fix the bug in auth.py" })) {
console.log(message); // Claude reads files, finds bugs, edits code
}
You also get working tools out of the box: 你还可以直接使用现成的工具： • Read - read any file in the working directory • Write - create new files • Edit - make precise edits to existing files • Bash - run terminal commands • Glob - find files by pattern • Grep - search file contents with regex • WebSearch - search the web • WebFetch - fetch and parse web pages • 读取 - 读取工作目录中的任意文件 • 写入 - 创建新文件 • 编辑 - 对现有文件进行精确修改 • Bash - 运行终端命令 • Glob - 按模式查找文件 • Grep - 使用正则表达式搜索文件内容 • WebSearch - 搜索网络 • WebFetch - 获取并解析网页 You don’t have to implement any of this yourself. 您无需自行实现其中任何功能。 Prerequisites 先决条件
Node.js 18+ installed 已安装 Node.js 18+ An Anthropic API key (get one here 获取一个) Anthropic API 密钥（在此处获取） Getting started 快速入门
Step 1: Install Claude Code CLI 步骤 1：安装 Claude Code CLI The Agent SDK uses Claude Code as its runtime: Agent SDK 使用 Claude Code 作为其运行时： bash npm install -g @anthropic-ai/claude-code After installing, run claude in your terminal and follow the prompts to authenticate. 安装完成后，在终端中运行 claude 命令，并按照提示完成身份验证。 Step 2: Create your project 步骤 2：创建您的项目 bash mkdir code-review-agent && cd code-review-agent npm init -y npm install @anthropic-ai/claude-agent-sdk npm install -D typescript @types/node tsx Step 3: Set your API key 步骤 3：设置您的 API 密钥 bash export ANTHROPIC_API_KEY=your-api-key Your first agent 你的第一个代理
Create agent.ts: 创建 agent.ts： typescript import { query } from “@anthropic-ai/claude-agent-sdk”;
async function main() { for await (const message of query({ prompt: “What files are in this directory?”, options: { model: “opus”, allowedTools: [“Glob”, “Read”], maxTurns: 250 } })) { if (message.type === “assistant”) { for (const block of message.message.content) { if (“text” in block) { console.log(block.text); } } }
if (message.type === "result") {
console.log("\nDone:", message.subtype);
}
} }
main(); Run it: 运行它： bash npx tsx agent.ts Claude will use the Glob tool to list files and tell you what it found. Claude 将使用 Glob 工具列出文件，并告诉你它找到了什么。 Understanding the message stream 理解消息流
The query() function returns an async generator that streams messages as Claude works. Here are the key message types: query() 函数返回一个异步生成器，会在 Claude 处理过程中流式传输消息。以下是关键的消息类型： typescript for await (const message of query({ prompt: “…” })) { switch (message.type) { case “system”: // Session initialization info if (message.subtype === “init”) { console.log(“Session ID:”, message.session_id); console.log(“Available tools:”, message.tools); } break;
case "assistant":
// Claude's responses and tool calls
for (const block of message.message.content) {
if ("text" in block) {
console.log("Claude:", block.text);
} else if ("name" in block) {
console.log("Tool call:", block.name);
}
}
break;
case "result":
// Final result
console.log("Status:", message.subtype); // "success" or error type
console.log("Cost:", message.total_cost_usd);
break;
} } Building a code review agent 构建一个代码审查代理
Now let’s build something useful. Create review-agent.ts: 现在让我们构建一些有用的东西。创建 review-agent.ts： typescript import { query } from “@anthropic-ai/claude-agent-sdk”;
async function reviewCode(directory: string) {
console.log(\n🔍 Starting code review for: ${directory}\n);
for await (const message of query({
prompt: `Review the code in ${directory} for:
1. Bugs and potential crashes
2. Security vulnerabilities
3. Performance issues
4. Code quality improvements
Be specific about file names and line numbers.,
options: {
model: "opus",
allowedTools: ["Read", "Glob", "Grep"],
permissionMode: "bypassPermissions", // Auto-approve read operations
maxTurns: 250
}
})) {
// Show Claude's analysis as it happens
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(\n📁 Using ${block.name}…`);
}
}
}
// Show completion status
if (message.type === "result") {
if (message.subtype === "success") {
console.log(`\n✅ Review complete! Cost: $${message.total_cost_usd.toFixed(4)}`);
} else {
console.log(`\n❌ Review failed: ${message.subtype}`);
}
}
} }
// Review the current directory reviewCode(“.”); Testing It Out 测试一下 Create a file with some intentional issues. Create example.ts: 创建一个包含故意问题的文件。创建 example.ts： typescript function processUsers(users: any) { for (let i = 0; i <= users.length; i++) { // Off-by-one error console.log(users[i].name.toUpperCase()); // No null check } }
function connectToDb(password: string) {
const connectionString = postgres://admin:${password}@localhost/db;
console.log(“Connecting with:”, connectionString); // Logging sensitive data
}
async function fetchData(url) { // Missing type annotation const response = await fetch(url); return response.json(); // No error handling } Run the review: 运行审查： bash npx tsx review-agent.ts Claude will identify the bugs, security issues, and suggest fixes. Claude 将识别出错误、安全问题，并提出修复建议。 Adding Structured Output 添加结构化输出
For programmatic use, you’ll want structured data. The SDK supports JSON Schema output: 对于程序化使用，您需要结构化数据。SDK 支持 JSON Schema 输出： typescript import { query } from “@anthropic-ai/claude-agent-sdk”;
const reviewSchema = { type: “object”, properties: { issues: { type: “array”, items: { type: “object”, properties: { severity: { type: “string”, enum: [“low”, “medium”, “high”, “critical”] }, category: { type: “string”, enum: [“bug”, “security”, “performance”, “style”] }, file: { type: “string” }, line: { type: “number” }, description: { type: “string” }, suggestion: { type: “string” } }, required: [“severity”, “category”, “file”, “description”] } }, summary: { type: “string” }, overallScore: { type: “number” } }, required: [“issues”, “summary”, “overallScore”] };
async function reviewCodeStructured(directory: string) {
for await (const message of query({
prompt: Review the code in ${directory}. Identify all issues.,
options: {
model: “opus”,
allowedTools: [“Read”, “Glob”, “Grep”],
permissionMode: “bypassPermissions”,
maxTurns: 250,
outputFormat: {
type: “json_schema”,
schema: reviewSchema
}
}
})) {
if (message.type === “result” && message.subtype === “success”) {
const review = message.structured_output as {
issues: Array<{
severity: string;
category: string;
file: string;
line?: number;
description: string;
suggestion?: string;
}>;
summary: string;
overallScore: number;
};
console.log(`\n📊 Code Review Results\n`);
console.log(`Score: ${review.overallScore}/100`);
console.log(`Summary: ${review.summary}\n`);
for (const issue of review.issues) {
const icon = issue.severity === "critical" ? "🔴" :
issue.severity === "high" ? "🟠" :
issue.severity === "medium" ? "🟡" : "🟢";
console.log(`${icon} [${issue.category.toUpperCase()}] ${issue.file}${issue.line ? `:${issue.line}` : ""}`);
console.log(` ${issue.description}`);
if (issue.suggestion) {
console.log(` 💡 ${issue.suggestion}`);
}
console.log();
}
}
} }
reviewCodeStructured(“.”); Handling permissions 处理权限
By default, the SDK asks for approval before executing tools. You can customize this: 默认情况下，SDK 在执行工具前会请求批准。您可以自定义此行为： Permission modes 权限模式 typescript options: { // Standard mode - prompts for approval permissionMode: “default”,
// Auto-approve file edits permissionMode: “acceptEdits”,
// No prompts (use with caution) permissionMode: “bypassPermissions” } Custom permission handler 自定义权限处理程序 For fine-grained control, use canUseTool: 如需更精细的控制，请使用 canUseTool： typescript options: { canUseTool: async (toolName, input) => { // Allow all read operations if ([“Read”, “Glob”, “Grep”].includes(toolName)) { return { behavior: “allow”, updatedInput: input }; }
// Block writes to certain files
if (toolName === "Write" && input.file_path?.includes(".env")) {
return { behavior: "deny", message: "Cannot modify .env files" };
}
// Allow everything else
return { behavior: "allow", updatedInput: input };
} } Creating subagents 创建子代理
For complex tasks, you can create specialized subagents: 对于复杂任务，你可以创建专用的子代理： typescript import { query, AgentDefinition } from “@anthropic-ai/claude-agent-sdk”;
async function comprehensiveReview(directory: string) {
for await (const message of query({
prompt: Perform a comprehensive code review of ${directory}.
Use the security-reviewer for security issues and test-analyzer for test coverage.,
options: {
model: “opus”,
allowedTools: [“Read”, “Glob”, “Grep”, “Task”], // Task enables subagents
permissionMode: “bypassPermissions”,
maxTurns: 250,
agents: {
“security-reviewer”: {
description: “Security specialist for vulnerability detection”,
prompt: You are a security expert. Focus on:
- SQL injection, XSS, CSRF vulnerabilities
- Exposed credentials and secrets
- Insecure data handling
- Authentication/authorization issues,
tools: [“Read”, “Grep”, “Glob”],
model: “sonnet”
} as AgentDefinition,
"test-analyzer": {
description: "Test coverage and quality analyzer",
prompt: `You are a testing expert. Analyze:
,
tools: ["Read", "Grep", "Glob"],
model: "haiku" // Use faster model for simpler analysis
} as AgentDefinition
}
}
})) {
if (message.type === "assistant") {
for (const block of message.message.content) {
if ("text" in block) {
console.log(block.text);
} else if ("name" in block && block.name === "Task") {
console.log(\n🤖 Delegating to: ${(block.input as any).subagent_type}`);
}
}
}
}
}comprehensiveReview(“.”); Session management 会话管理
For multi-turn conversations, capture and resume sessions: 对于多轮对话，捕获并恢复会话： typescript import { query } from “@anthropic-ai/claude-agent-sdk”;
async function interactiveReview() { let sessionId: string | undefined;
// Initial review for await (const message of query({ prompt: “Review this codebase and identify the top 3 issues”, options: { model: “opus”, allowedTools: [“Read”, “Glob”, “Grep”], permissionMode: “bypassPermissions”, maxTurns: 250 } })) { if (message.type === “system” && message.subtype === “init”) { sessionId = message.session_id; } // … handle messages }
// Follow-up question using same session if (sessionId) { for await (const message of query({ prompt: “Now show me how to fix the most critical issue”, options: { resume: sessionId, // Continue the conversation allowedTools: [“Read”, “Glob”, “Grep”], maxTurns: 250 } })) { // Claude remembers the previous context } } } Using hooks 使用钩子
Hooks let you intercept and customize agent behavior: 钩子（Hooks）让您能够拦截并自定义代理的行为： typescript import { query, HookCallback, PreToolUseHookInput } from “@anthropic-ai/claude-agent-sdk”;
const auditLogger: HookCallback = async (input, toolUseId, { signal }) => {
if (input.hook_event_name === “PreToolUse”) {
const preInput = input as PreToolUseHookInput;
console.log([AUDIT] ${new Date().toISOString()} - ${preInput.tool_name});
}
return {}; // Allow the operation
};
const blockDangerousCommands: HookCallback = async (input, toolUseId, { signal }) => { if (input.hook_event_name === “PreToolUse”) { const preInput = input as PreToolUseHookInput; if (preInput.tool_name === “Bash”) { const command = (preInput.tool_input as any).command || “”; if (command.includes(“rm -rf”) || command.includes(“sudo”)) { return { hookSpecificOutput: { hookEventName: “PreToolUse”, permissionDecision: “deny”, permissionDecisionReason: “Dangerous command blocked” } }; } } } return {}; };
for await (const message of query({ prompt: “Clean up temporary files”, options: { model: “opus”, allowedTools: [“Bash”, “Glob”], maxTurns: 250, hooks: { PreToolUse: [ { hooks: [auditLogger] }, { matcher: “Bash”, hooks: [blockDangerousCommands] } ] } } })) { // … } Adding custom tools with MCP 使用 MCP 添加自定义工具
Extend Claude with custom tools using Model Context Protocol: 通过模型上下文协议（MCP）为 Claude 扩展自定义工具： typescript import { query, tool, createSdkMcpServer } from “@anthropic-ai/claude-agent-sdk”; import { z } from “zod”;
// Create a custom tool
const customServer = createSdkMcpServer({
name: “code-metrics”,
version: “1.0.0”,
tools: [
tool(
“analyze_complexity”,
“Calculate cyclomatic complexity for a file”,
{
filePath: z.string().describe(“Path to the file to analyze”)
},
async (args) => {
// Your complexity analysis logic here
const complexity = Math.floor(Math.random() * 20) + 1; // Placeholder
return {
content: [{
type: “text”,
text: Cyclomatic complexity for ${args.filePath}: ${complexity}
}]
};
}
)
]
});
// Use streaming input for MCP servers async function* generateMessages() { yield { type: “user” as const, message: { role: “user” as const, content: “Analyze the complexity of main.ts” } }; }
for await (const message of query({ prompt: generateMessages(), options: { model: “opus”, mcpServers: { “code-metrics”: customServer }, allowedTools: [“Read”, “mcpcode-metricsanalyze_complexity”], maxTurns: 250 } })) { // … } Cost tracking 成本跟踪
Track API costs for billing: 跟踪 API 成本以用于计费： typescript for await (const message of query({ prompt: “…” })) { if (message.type === “result” && message.subtype === “success”) { console.log(“Total cost:”, message.total_cost_usd); console.log(“Token usage:”, message.usage);
// Per-model breakdown (useful with subagents)
for (const [model, usage] of Object.entries(message.modelUsage)) {
console.log(`${model}: $${usage.costUSD.toFixed(4)}`);
}
} } Production code review agent 生产代码审查代理
Here’s a production-ready agent that ties everything together: 这是一个可投入生产的代理，将所有功能整合在一起： typescript import { query, AgentDefinition } from “@anthropic-ai/claude-agent-sdk”;
interface ReviewResult { issues: Array<{ severity: “low” | “medium” | “high” | “critical”; category: “bug” | “security” | “performance” | “style”; file: string; line?: number; description: string; suggestion?: string; }>; summary: string; overallScore: number; }
const reviewSchema = { type: “object”, properties: { issues: { type: “array”, items: { type: “object”, properties: { severity: { type: “string”, enum: [“low”, “medium”, “high”, “critical”] }, category: { type: “string”, enum: [“bug”, “security”, “performance”, “style”] }, file: { type: “string” }, line: { type: “number” }, description: { type: “string” }, suggestion: { type: “string” } }, required: [“severity”, “category”, “file”, “description”] } }, summary: { type: “string” }, overallScore: { type: “number” } }, required: [“issues”, “summary”, “overallScore”] };
async function runCodeReview(directory: string): Promise\n${"=".repeat(50)});
console.log(🔍 Code Review Agent);
console.log(📁 Directory: ${directory});
console.log(${"=".repeat(50)}\n);
let result: ReviewResult | null = null;
for await (const message of query({ prompt: `Perform a thorough code review of ${directory}.
Analyze all source files for: 1. Bugs and potential runtime errors 2. Security vulnerabilities 3. Performance issues 4. Code quality and maintainability
Be specific with file paths and line numbers where possible.,
options: {
model: "opus",
allowedTools: ["Read", "Glob", "Grep", "Task"],
permissionMode: "bypassPermissions",
maxTurns: 250,
outputFormat: {
type: "json_schema",
schema: reviewSchema
},
agents: {
"security-scanner": {
description: "Deep security analysis for vulnerabilities",
prompt:You are a security expert. Scan for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Sensitive data exposure
- Insecure dependencies,
tools: ["Read", "Grep", "Glob"],
model: "sonnet"
} as AgentDefinition
}
}
})) {
// Progress updates
if (message.type === "assistant") {
for (const block of message.message.content) {
if ("name" in block) {
if (block.name === "Task") {
console.log(🤖 Delegating to: \({(block.input as any).subagent_type}`);
} else {
console.log(`📂 \){block.name}: ${getToolSummary(block)}`);
}
}
}
}
// Final result
if (message.type === "result") {
if (message.subtype === "success" && message.structured_output) {
result = message.structured_output as ReviewResult;
console.log(`\n✅ Review complete! Cost: $${message.total_cost_usd.toFixed(4)}`);
} else {
console.log(`\n❌ Review failed: ${message.subtype}`);
}
}
}
return result; }
function getToolSummary(block: any): string {
const input = block.input || {};
switch (block.name) {
case “Read”: return input.file_path || “file”;
case “Glob”: return input.pattern || “pattern”;
case “Grep”: return "${input.pattern}" in ${input.path || "."};
default: return “”;
}
}
function printResults(result: ReviewResult) {
console.log(\n${"=".repeat(50)});
console.log(📊 REVIEW RESULTS);
console.log(${"=".repeat(50)}\n);
console.log(Score: ${result.overallScore}/100);
console.log(Issues Found: ${result.issues.length}\n);
console.log(Summary: ${result.summary}\n);
const byCategory = { critical: result.issues.filter(i => i.severity === “critical”), high: result.issues.filter(i => i.severity === “high”), medium: result.issues.filter(i => i.severity === “medium”), low: result.issues.filter(i => i.severity === “low”) };
for (const [severity, issues] of Object.entries(byCategory)) { if (issues.length === 0) continue;
const icon = severity === "critical" ? "🔴" :
severity === "high" ? "🟠" :
severity === "medium" ? "🟡" : "🟢";
console.log(`\n${icon} ${severity.toUpperCase()} (${issues.length})`);
console.log("-".repeat(30));
for (const issue of issues) {
const location = issue.line ? `${issue.file}:${issue.line}` : issue.file;
console.log(`\n[${issue.category}] ${location}`);
console.log(` ${issue.description}`);
if (issue.suggestion) {
console.log(` 💡 ${issue.suggestion}`);
}
}
} }
// Run the review async function main() { const directory = process.argv[2] || “.”; const result = await runCodeReview(directory);
if (result) { printResults(result); } }
main().catch(console.error); Run it: 运行它： bash npx tsx review-agent.ts ./src What’s next 下一步
The code review agent covers the essentials: query(), allowedTools, structured output, subagents, and permissions. 代码审查代理涵盖了基本要素：query()、allowedTools、结构化输出、子代理和权限。 If you want to go deeper: 如果你想深入了解： More capabilities 更多功能 File checkpointing - track and revert file changes 文件检查点 - 跟踪并回滚文件更改 Skills - package reusable capabilities 技能 - 打包可重用的功能 Production deployment 生产环境部署 Hosting - deploy in containers and CI/CD 托管 - 在容器和 CI/CD 中部署 Secure deployment - sandboxing and credential management 安全部署 -沙箱化与凭据管理 Full reference 完整参考 TypeScript SDK reference TypeScript SDK 参考 Python SDK reference Python SDK 参考 This guide covers V1 of the SDK. V2 is currently in development. I will update this guide with V2 once it’s released and stable.
If you’re interested in building verifiable agents, check out the work we’re doing at @eigencloud here. 本指南涵盖 SDK 的 V1 版本。V2 版本目前正在开发中，一旦发布并稳定，我将更新本指南以包含 V2 的内容。