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

"给AI下达指令后，让它自己思考并完成工作就好了……"AI智能体正是为了实现这一理想而生。Anthropic推出的Claude Agent SDK是一个以Claude为核心的AI智能体开发框架，支持Python和TypeScript。Claude Code（Anthropic官方CLI）内部使用的也是同一套技术。

本文将系统地讲解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的同一引擎。

主要特性如下：

在Claude的聊天、协作、编程三种模式中，Agent SDK正是编程模式（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

最简智能体（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)
            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、修复代码并汇报结果的智能体就运行起来了。

内置工具一览

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

只需在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服务器的形式创建，然后连接到智能体。要点是：出错时不要抛出异常，而应返回isError: true。这样智能体循环不会中断，Claude会尝试重试或采取其他方案。

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

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

子智能体的适用场景

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

Claude Code中的自定义子智能体

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

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

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

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

Agent SDK vs Client SDK vs Claude Code

Claude提供三种面向开发者的接口，各有所长。请根据实际需求选择。

如何选择：

• 日常开发工作 → Claude Code CLI
• 构建自动化系统 → Agent SDK
• 开发自定义AI应用 → Client SDK

实际应用场景

代码开发自动化

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

# 自动化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/max）
)

2. 精简工具集

允许不必要的工具会浪费上下文窗口。在allowed_tools中只指定任务实际需要的工具。

3. 用isError处理错误

自定义工具抛出异常会导致整个智能体循环停止。改为返回isError: true，让Claude尝试恢复。

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

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

5. 提示词要具体

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

总结

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

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

关于Claude的基本用法，也推荐阅读Claude"聊天·协作·编程"三种模式详细对比。