使用Claude Agent SDK构建AI Agent - 实用指南

Claude Agent SDK为你提供了与驱动Claude Code相同的Agent循环的编程访问。你的Agent可以读取文件、执行Shell命令、搜索网页、编辑代码、通过MCP服务器调用外部API,以及编排子Agent - 所有这些只需要几行TypeScript或Python代码。

与标准的Anthropic Client SDK需要你自己构建工具循环不同,Agent SDK在内部处理工具执行、上下文管理、重试和编排。你只需描述你想做什么、提供工具,Agent会自己搞定剩下的。

架构

SDK遵循一个简单的循环: 收集上下文、执行操作、验证、重复。

核心入口是 query(),它返回一个异步迭代器,在Agent工作时流式传输消息。每条消息告诉你Agent正在做什么: 推理中、调用工具、接收结果或者交付最终输出。

开始使用

安装

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python
pip install claude-agent-sdk

你需要在环境变量中设置Anthropic API密钥 ANTHROPIC_API_KEY。

你的第一个Agent

import { query } from "@anthropic-ai/claude-agent-sdk";

const conversation = query({
  prompt: "Find all TODO comments in the codebase and create a summary",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
  },
});

for await (const message of conversation) {
  if (message.type === "assistant") {
    process.stdout.write(message.content);
  }
  if (message.type === "result" && message.subtype === "success") {
    console.log("\nDone:", message.result);
  }
}

就这么简单。Agent会使用Glob查找文件,用Grep搜索TODO模式,用Read检查匹配项,然后返回结构化的摘要。你不需要编写编排逻辑 - SDK会处理。

Python等效写法

from claude_agent_sdk import query

async for message in query(
    prompt="Find all TODO comments in the codebase and create a summary",
    options={"allowed_tools": ["Read", "Glob", "Grep"]},
):
    if message.type == "assistant":
        print(message.content, end="")
    if message.type == "result" and message.subtype == "success":
        print(f"\nDone: {message.result}")

内置工具

SDK附带了与Claude Code中相同的工具:

你通过 allowedTools 控制Agent可以使用哪些工具。如果一个工具不在列表中,Agent就无法调用它。

权限模式

由于Agent在真实系统上执行真实命令,权限至关重要。

const conversation = query({
  prompt: "Refactor the auth module to use JWT",
  options: {
    allowedTools: ["Read", "Edit", "Glob", "Grep", "Bash"],
    permissionMode: "acceptEdits",
  },
});

在生产环境中,始终在沙箱化环境(容器、VM)中运行Agent,并使用能让Agent完成工作的最严格权限模式。

使用MCP构建自定义工具

SDK的真正强大之处在于用你自己的工具扩展Agent。自定义工具被定义为进程内MCP服务器 - 无需子进程管理,没有网络开销。

示例: 天气工具

import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const getTemperature = tool(
  "get_temperature",
  "Get the current temperature at a location",
  {
    latitude: z.number().describe("Latitude"),
    longitude: z.number().describe("Longitude"),
  },
  async ({ latitude, longitude }) => {
    const res = await fetch(
      `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m&temperature_unit=celsius`
    );
    const data = await res.json();
    return {
      content: [
        {
          type: "text",
          text: `Current temperature: ${data.current.temperature_2m}C`,
        },
      ],
    };
  }
);

const weatherServer = createSdkMcpServer({
  name: "weather",
  version: "1.0.0",
  tools: [getTemperature],
});

for await (const message of query({
  prompt: "What's the weather like in Rome?",
  options: {
    mcpServers: { weather: weatherServer },
    allowedTools: ["mcp__weather__get_temperature"],
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

自定义工具遵循 mcp__{server_name}__{tool_name} 的命名约定。你可以在 allowedTools 中使用通配符: "mcp__weather__*" 允许weather服务器的所有工具。

示例: 数据库查询工具

const queryDb = tool(
  "query_database",
  "Run a read-only SQL query against the application database",
  {
    sql: z.string().describe("SQL SELECT query to execute"),
  },
  async ({ sql }) => {
    // Validate: only allow SELECT queries
    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
      return {
        content: [{ type: "text", text: "Error: Only SELECT queries are allowed." }],
      };
    }

    const result = await pool.query(sql);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result.rows, null, 2),
        },
      ],
    };
  }
);

连接外部MCP服务器

除了进程内工具,你还可以连接到任何现有的MCP服务器 - 与Claude Desktop、Cursor和其他MCP客户端兼容的同一批服务器。

for await (const message of query({
  prompt: "Check the latest issues in the frontend repo and summarize them",
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
      },
    },
    allowedTools: ["mcp__github__*"],
  },
})) {
  // ...
}

你可以组合多个MCP服务器。Agent能够看到所有已连接服务器的所有工具,并按需使用。

多Agent编排

对于复杂的工作流,你可以定义专门的子Agent,由父Agent委派任务。每个子Agent有自己的提示词、工具和专注领域。

for await (const message of query({
  prompt: "Review the PR, check for security issues, and update the changelog",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep", "Agent"],
    agents: [
      {
        name: "security-reviewer",
        description: "Reviews code for security vulnerabilities",
        prompt: "You are a security expert. Analyze code for OWASP Top 10 vulnerabilities.",
        allowedTools: ["Read", "Glob", "Grep"],
      },
      {
        name: "changelog-writer",
        description: "Updates the CHANGELOG.md file based on recent changes",
        prompt: "You maintain the project changelog. Follow Keep a Changelog format.",
        allowedTools: ["Read", "Edit", "Bash"],
      },
    ],
  },
})) {
  // The parent agent will:
  // 1. Read the PR diff
  // 2. Delegate security review to security-reviewer
  // 3. Delegate changelog update to changelog-writer
  // 4. Synthesize results
}

在父级的 allowedTools 中包含 "Agent" 以启用委派。子Agent使用自己的工具运行,除非明确授权,否则无法访问父级的工具。

会话与连续性

Agent可以使用会话在多个查询之间保持上下文。从第一次交互中捕获 session_id,并在后续查询中传递给 resume。

let sessionId: string | undefined;

// First query
for await (const message of query({
  prompt: "Read the project structure and understand the architecture",
  options: { allowedTools: ["Read", "Glob", "Grep"] },
})) {
  if (message.type === "init") {
    sessionId = message.session_id;
  }
}

// Follow-up query (same session, full context preserved)
for await (const message of query({
  prompt: "Now refactor the auth module based on what you learned",
  resume: sessionId,
  options: { allowedTools: ["Read", "Edit", "Bash"] },
})) {
  // Agent remembers the full project context from the first query
}

Claude Managed Agents

如果你不想自己托管Agent基础设施,Claude Managed Agents(2026年4月推出)提供了完全托管的云服务。Anthropic运行容器、处理扩展,并提供流式API。

关键区别: 使用Agent SDK时,你在自己的基础设施中运行Agent循环。使用Managed Agents时,Anthropic为你托管和运行Agent。你通过基于会话的API进行交互,并通过Server-Sent Events接收事件。

定价:

• Agent SDK: 仅标准Claude API token费率。你自己负责托管。
• Managed Agents: token费率加上每会话小时$0.08(按毫秒计费)。

生产环境最佳实践

1. 始终沙箱化

永远不要在生产机器上以不受限制的权限运行Agent。使用容器(Docker、Fly.io、Modal)或沙箱环境(E2B、Vercel Sandbox)。

2. 限制工具访问

遵循最小权限原则。生成报告的Agent不需要 Bash 或 Write。

// Too permissive
allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]

// Better: only what's needed
allowedTools: ["Read", "Glob", "Grep"]

3. 使用Hook设置护栏

Hook允许你在工具调用执行前后进行拦截。用于日志记录、验证和速率限制。

const conversation = query({
  prompt: "Analyze the codebase",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    hooks: {
      PreToolUse: async (toolName, input) => {
        console.log(`Tool call: ${toolName}`, input);
        // Return false to block the call
        if (toolName === "Bash" && input.command.includes("rm")) {
          return false;
        }
        return true;
      },
    },
  },
});

4. 优雅地处理错误

Agent循环可能产生错误 - 工具失败、API速率限制、上下文窗口溢出。始终检查消息类型。

for await (const message of conversation) {
  switch (message.type) {
    case "assistant":
      // Agent reasoning
      break;
    case "tool_use":
      // Agent is calling a tool
      break;
    case "result":
      if (message.subtype === "error") {
        console.error("Agent failed:", message.error);
      }
      break;
  }
}

5. 监控Token使用量

Agent循环可能消耗大量token,尤其是在大型代码库中。SDK包含自动上下文压缩功能,但你仍然应该监控使用量。

总结

Claude Agent SDK将LLM从一个问答机器转变为更接近初级开发者的角色。你的Agent可以读取、编写、执行、验证和迭代 - 与人类遵循的工作流程相同。

从小处着手: 用几个内置工具构建一个Agent。然后为你的特定领域添加自定义MCP工具。当你的工作流需要专业化时,再扩展到多Agent编排。

Agent循环与驱动Claude Code的是同一个。如果它能构建软件,你的Agent也能。

入门清单:

• 安装SDK (npm install @anthropic-ai/claude-agent-sdk)
• 在环境变量中设置 ANTHROPIC_API_KEY
• 使用内置工具(Read、Glob、Grep)构建一个简单的Agent
• 通过进程内MCP服务器添加自定义工具
• 连接外部MCP服务器(GitHub、PostgreSQL等)
• 使用子Agent实现多Agent编排
• 为生产环境搭建沙箱化环境
• 添加用于日志记录和护栏的Hook