什么是Claude Agent SDK？AI智能体开发从入门到实践

“给AI下达指令后，让它自己思考并完成工作就好了……”AI智能体正是为了实现这一理想而生。Anthropic推出的Claude Agent SDK是一个以Claude为核心的AI智能体开发库，支持Python和TypeScript。驱动Claude Code（Anthropic官方的编程智能体）的工具、智能体循环和上下文管理，都可以直接在你自己的程序中使用。

本文将系统地讲解Claude Agent SDK——从基本概念到实现方法，再到应用场景。

什么是AI智能体？

AI智能体不同于传统的“问答式”AI。它的核心特点是自主分解任务、调用工具、分析结果并决定下一步行动。

例如，当你要求智能体“修复auth.py中的Bug”时，它会按如下流程操作：

1. 读取文件，理解代码逻辑
2. 搜索相关文件，把握整体架构
3. 定位Bug原因
4. 修改代码
5. 运行测试验证修复效果
6. 汇报结果

整个过程无需人工干预，智能体在每个环节都自主做出判断。这就是智能体的强大之处。

Claude Agent SDK概述

Claude Agent SDK是Anthropic官方提供的智能体开发库。官方文档将其描述为“运行Claude Code可执行文件的库”。也就是说，方向是由SDK调用并驱动Claude Code，而不是反过来。Python和TypeScript的SDK都自带该可执行文件，因此在大多数环境中无需另外安装Claude Code。

主要特性如下：

Agent SDK的作用是把在Claude的代码（Claude Code）中运行的智能体，搬到界面之外、嵌入你自己的应用和脚本中。

智能体循环的工作原理

Agent SDK的核心是智能体循环——一种自动运转的机制，让Claude“思考、使用工具、查看结果、再次思考”这一过程持续循环。

具体流程如下：

1. 接收指令：将用户的指令传递给Claude
2. Claude分析：分析指令内容，确定所需操作
3. 执行工具：调用Bash、Edit、Read等工具执行操作
4. 处理结果：将工具执行结果反馈给Claude
5. 继续或完成：如果还有待完成的工作，返回第2步；全部完成后返回文本回复

关键点在于：当不再需要调用工具时，循环即告结束。一旦Claude判断不再需要使用工具，就会返回最终的文本回复。

快速上手：安装与基础代码

安装

支持Python和TypeScript两种语言。

# Python
pip install claude-agent-sdk

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

运行环境要求为 Node.js 18 及以上，或 Python 3.10 及以上（官方快速入门）。

认证：使用API密钥（不能用claude.ai登录）

SDK使用环境变量 ANTHROPIC_API_KEY 中的API密钥运行。如果通过Amazon Bedrock、Google Cloud（由Google运营的版本）或Microsoft Foundry使用，请分别设置 CLAUDE_CODE_USE_BEDROCK=1、CLAUDE_CODE_USE_VERTEX=1 或 CLAUDE_CODE_USE_FOUNDRY=1，并配置相应云平台的凭据。SDK不会自动读取 .env 文件，因此请在运行智能体的shell中设置好变量。在Google Cloud上使用Claude的步骤和价格，请参阅“在 Vertex AI 上使用 Claude”。

需要特别注意claude.ai登录（Pro、Max等订阅）的问题。官方文档规定，除非事先获得批准，第三方开发者不得在自己的产品（包括用Agent SDK构建的智能体）中提供claude.ai登录或其用量额度。用SDK开发的应用应当使用API密钥进行认证。

最简智能体（Python）

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    async for message in query(
        prompt="查找并修复src/auth.py中的Bug",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash", "Grep"],
            max_turns=30,
        ),
    ):
        if isinstance(message, ResultMessage):
            if message.subtype == "success":
                print(message.result)
            if message.total_cost_usd is not None:
                print(f"费用: ${message.total_cost_usd:.4f}")

asyncio.run(main())

最简智能体（TypeScript）

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

for await (const message of query({
  prompt: "查找并修复src/auth.py中的Bug",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Grep"],
    maxTurns: 30,
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

就这么简单——一个能够读取文件、查找Bug、修复代码并汇报结果的智能体就运行起来了。但要注意：allowed_tools 并不是“允许Claude使用的工具列表”，而是无需确认即自动批准的工具列表。上例中包含 Bash，因此Claude选择的shell命令会在不经确认的情况下执行（少数操作除外，例如某些删除操作，任何设置都不会自动批准）。由于此例没有指定 permission_mode，模式取自设置文件中的 permissions.defaultMode，没有时则用内置默认值；自 v2.1.285 起，在不获取功能开关的会话中（例如通过第三方提供商 Bedrock、Google Cloud、Microsoft Foundry，或关闭了遥测时），该默认值曾为 auto（官方文档）。但在 v2.1.302（2026年10月16日）中有所改变：未指定权限模式的 Agent SDK 与 claude -p 会话，即使通过第三方提供商等方式运行，也改为以 default 启动。若要使用 auto，需要显式指定（CLI 中为 --permission-mode auto，参见更新历史，2026年10月18日确认）。auto 模式会去掉 Bash 这类宽泛的允许规则，因此若依赖上述行为，请显式传入 permission_mode="default"（TS: permissionMode: "default"）（官方文档）。请在即使被弄坏也无妨的工作目录中试用。如何真正限定工具，将在下一节说明。

内置工具一览

Agent SDK提供了丰富的开箱即用工具，无需编写额外代码。

使用内置工具时，不需要自己编写工具处理代码。需要注意的是，“让Claude看到哪些工具”和“哪些工具无需确认即可执行”是两项不同的设置。下表整理了官方文档的说明。

例如，把 allowed_tools=["Read"] 与 permission_mode="bypassPermissions" 一起使用时，包括未列出的 Bash、Write、Edit 在内的所有工具都会被批准（官方文档对这种组合有明确警告）。不想让Claude使用的工具，请用 tools 或 disallowed_tools 移除。如果只想用固定的一组工具运行，可以把 allowed_tools 与 permission_mode="dontAsk"（拒绝所有需要确认的调用）组合使用。

还有一点：在macOS、Linux和WSL上，Glob 和 Grep 不在默认工具集中（Windows上则包含）。此时Claude会通过 Bash 使用 find 和 grep 进行搜索。在 tools 或 allowed_tools 中写出其中任意一个的名称，即可重新启用它们（官方工具参考）。

如何创建自定义工具

当内置工具无法满足需求时，可以创建自定义工具。以下是一个天气API集成的示例。

Python版

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool(
    "get_weather",
    "获取指定城市的当前天气",
    {"city": str}
)
async def get_weather(args: dict) -> dict:
    city = args["city"]
    # 实际应用中调用天气API
    weather_data = await fetch_weather_api(city)
    return {
        "content": [
            {"type": "text", "text": f"{city}的天气: {weather_data}"}
        ]
    }

weather_server = create_sdk_mcp_server(
    name="weather",
    version="1.0.0",
    tools=[get_weather]
)

TypeScript版

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

const getWeather = tool(
  "get_weather",
  "获取指定城市的当前天气",
  { city: z.string().describe("城市名称") },
  async (args) => {
    const data = await fetchWeatherApi(args.city);
    return {
      content: [{ type: "text", text: `${args.city}的天气: ${data}` }]
    };
  }
);

自定义工具以MCP服务器的形式创建，并通过 mcp_servers（TS：mcpServers）传给智能体。每个工具的完整名称是 mcp__服务器名__工具名，如果希望它无需确认即可执行，就把这个名称加入 allowed_tools。

options=ClaudeAgentOptions(
    mcp_servers={"weather": weather_server},
    allowed_tools=["mcp__weather__get_weather"],
)

即使工具内部抛出异常，智能体循环也不会停止。SDK的MCP服务器会捕获异常，并把异常消息原样作为错误结果交给Claude。如果你自己捕获错误并返回 "is_error": True（TypeScript中为 isError: true），就可以自行编写Claude读到的消息，例如“哪个请求失败了”“可以改试什么”。无论哪种情况，Claude都可以重试、改用其他工具或说明失败原因（官方文档：自定义工具）。

利用子智能体实现并行处理

面对大型任务，将其拆分为子智能体并行执行会更加高效。这种方式不会占用主智能体的上下文（记忆），同时可以将专业任务委托给独立的智能体。

子智能体的适用场景

• 大规模测试：即使测试日志量巨大，也不会影响主智能体的上下文
• 并行调研：同时分析多个模块，只接收最终结果
• 职责分离：将“代码审查”和“测试执行”分配给不同的智能体

Claude Code中的自定义子智能体

在Claude Code（CLI）中，只需在.claude/agents/目录下放置Markdown文件即可定义自定义子智能体。

# .claude/agents/reviewer.md
---
name: code-reviewer
description: 专注于代码审查的智能体
tools: Read, Glob, Grep
model: sonnet
---

你是一位资深代码审查员。
请从代码质量、安全性和最佳实践的
角度进行审查。

通过限制可用工具（上例中仅限读取类工具），可以防止审查智能体误修改代码。

权限、钩子与会话

在生产环境中运行智能体时，最关键的就是这三项。官方文档把它们都列为SDK中可用的Claude Code功能。

权限：每次调用都按固定顺序判定

当Claude请求使用工具时，SDK会按照钩子 → 拒绝规则 → 确认规则 → 权限模式 → 允许规则 → can_use_tool 回调的顺序进行判定。与拒绝规则（例如来自 disallowed_tools）匹配的调用，即使在 bypassPermissions 模式下也会被阻止。例外是 mod（以函数编写钩子的插件）：它在加载了它的 Agent SDK 会话中同样运行（官方文档），响应 tool.check 的 mod 可以批准被拒绝规则拒绝的调用，有管理设置的机器或以 Team、Enterprise 计划登录时除外（官方文档）。只安装可信作者的 mod，详见“Claude Code mod 详解”。权限模式通过 permission_mode 选择（依据2026年9月的官方文档）。

钩子：在关键节点运行自己的代码

钩子是在特定事件发生时调用的回调，例如工具执行前（PreToolUse）、执行后（PostToolUse）或执行停止时（Stop）。钩子在权限判定之前运行，因此“无论什么模式都必须阻止的操作”应当在这里拒绝。下面的例子会拒绝写入 .env 文件（根据官方文档的示例精简而来）。

from claude_agent_sdk import ClaudeAgentOptions, HookMatcher

async def protect_env_files(input_data, tool_use_id, context):
    file_path = input_data["tool_input"].get("file_path", "")
    if file_path.split("/")[-1] == ".env":
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "deny",
                "permissionDecisionReason": "Cannot modify .env files",
            }
        }
    return {}

options = ClaudeAgentOptions(
    hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]}
)

会话：从上次中断处继续，或另开分支

SDK会自动把对话历史（提示词、工具调用、结果和回复）作为会话保存到磁盘。记下结果消息中的 session_id，在下一次 query() 时传给 resume，智能体就能在记得已读文件和已做判断的情况下继续工作。如果只需继续最近一次会话，使用 continue_conversation=True（TS：continue: true）；如果想保留原会话、尝试另一种思路，使用 fork_session=True（TS：forkSession: true）。会话只保存对话，文件的修改不会被回滚（官方文档：会话）。

此外，项目的 .claude/ 和 ~/.claude/ 中的技能（skills）、命令和记忆会像在Claude Code中一样被自动加载。把技能、智能体、钩子和MCP服务器打包在一起的插件，也可以通过本地路径加载。

Agent SDK vs Client SDK vs Claude Code

官方的比较表列出了使用Claude进行开发的四种方式：Agent SDK、Claude Code CLI、Client SDK和Managed Agents。这里先比较在你自己的电脑或服务器上运行的三种。

如何选择：

• 日常开发工作 → Claude Code CLI
• 构建自动化系统 → Agent SDK
• 开发自定义AI应用 → Client SDK
• 连同循环和沙箱的运维一起交出去 → Managed Agents（由Anthropic托管的智能体，会话在Anthropic管理的云端沙箱或自建沙箱中运行，可通过各语言的SDK、ant CLI或REST API使用）

实际应用场景

代码开发自动化

这是最常见的用法。只需说“实现这个功能”，智能体就会分析文件结构、编写代码并运行测试。

# 自动化Bug修复
async for msg in query(
    prompt="认证模块的测试失败了，请查明原因并修复",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Bash", "Grep"],
        max_turns=20,
        max_budget_usd=2.00,  # 成本上限$2
    ),
):
    pass

集成到CI/CD流水线

可以与GitHub Actions等工具配合，在PR创建时自动进行代码审查，或在测试失败时尝试自动修复。

数据分析与调研

“分析过去一个月的日志，找出错误模式”——类似这种需要多个步骤的调研任务也可以交给智能体。结合WebSearch工具，还能获取最新信息。

最佳实践

1. 注意成本控制

由于智能体以循环方式运行，Token消耗可能超出预期。务必设置max_budget_usd和max_turns。

options=ClaudeAgentOptions(
    max_budget_usd=5.00,   # 达到$5时停止
    max_turns=30,           # 30次迭代后停止
    effort="medium",        # 推理深度（low/medium/high/xhigh/max）
)

在不支持 xhigh 的模型上，它会按 high 处理。达到上限而停止时，最终结果消息的 subtype 会是 "error_max_budget_usd"（对应 max_budget_usd）或 "error_max_turns"（对应 max_turns），且 result 为空（None）。可以通过 subtype 判断智能体停止的原因。

不过，这个金额是SDK根据内置价格表算出的估算值，并不是实际账单。预算只计算本次调用自身的花费，通过 resume 恢复的会话之前的花费不计入其中。准确的费用请在Claude Console的Usage页面或通过Usage and Cost API确认（官方文档：费用与用量跟踪）。

2. 精简工具集

要让Claude看不到不需要的工具，可以在 tools 中只列出要用的工具，或在 disallowed_tools 中只写名称将其移除。allowed_tools 只是省去确认的设置，并没有限定工具的作用。无需确认即可执行的工具，也应控制在任务所需的最低限度。

3. 用 is_error 传达工具错误

自定义工具中发生异常时，智能体循环并不会停止，SDK会把异常消息作为错误结果交给Claude。但仅凭原始的异常消息，Claude有时难以决定下一步。自己捕获异常，并在返回 "is_error": True（TypeScript中为 isError: true）的同时写明“哪里失败了、可以改试什么”，Claude就更容易重新调整。

4. 将重任务交给子智能体

测试执行、日志分析等产生大量输出的操作应委托给子智能体，避免主智能体的上下文被占满。

5. 提示词要具体

不要说“改进代码”，而应说“在auth.py的登录函数中添加速率限制，并编写测试”。具体的指令能让智能体更高效地工作。

总结

Claude Agent SDK大幅降低了AI智能体开发的门槛。使用与Claude Code相同的引擎，您可以用Python或TypeScript构建自主执行任务的智能体。

建议的学习路径是：先通过Claude Code以交互方式体验智能体的能力，当需要自动化时再迁移到Agent SDK。

如果您不想自行运维循环、沙箱和状态管理，Anthropic提供的全托管方案是Claude Managed Agents。

关于Claude的基本用法，也推荐阅读Claude的聊天、Cowork与代码有何不同。