## 一、背景：一个 SDK 解决什么问题

在 Claude 的技术体系中，存在明确的分层：

| 层级 | 定位 | 适用场景 |
|------|------|---------|
| **Claude API** | 底层消息接口，一次请求一次响应 | 分类、摘要、提取、固定流程 Q&A |
| **Claude API + Tool Use** | 让模型调用自定义工具，你控制循环 | 需要读文件、查数据库、调用外部 API |
| **Agent SDK** | 内置工具、安全机制、MCP 支持的自主 Agent | 需要模型自主探索、多步执行、带工具的编码助手 |

一句话概括：**Agent SDK = 帮你包好了 Agent 常需的一切基础设施**，你只需定义任务和边界。

---

## 二、架构设计哲学

### 2.1 与 Claude API 的本质区别

Claude API 是**请求-响应**模型——你发消息，模型回复，结束。

Agent SDK 引入了**循环机制**：

```
用户提示 → 模型思考 → 模型请求工具 → SDK 执行工具 → 结果返回模型 → 循环直到任务完成
```

这个循环中，SDK 负责：
- 检测模型何时请求工具
- 执行工具并收集结果
- 将结果注入下一轮上下文
- 管理权限、hooks、session 生命周期

### 2.2 工具体系的分层设计

Agent SDK 的工具分为两类：

**客户端工具（Client-side Tools）**
- 模型定义工具的 name/schema，SDK 在客户端执行
- 内置提供：Read、Write、Edit、Bash、Glob、Grep
- 可扩展：自定义函数通过 MCP 协议接入

**服务端工具（Server-side Tools）**
- 声明后完全由 Anthropic 托管执行
- 包括：WebSearch、WebFetch、CodeExecution、ComputerUse
- 无需自己实现沙箱环境

---

## 三、核心 API 解析

### 3.1 两个入口怎么选

```python
# 简单场景：一行调用，返回异步迭代器
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async for message in query(
    prompt="解释这个代码库",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],
        cwd="/path/to/project"
    )
):
    if isinstance(message, ResultMessage):
        print(message.result)
```

```python
# 复杂场景：需要自定义工具、hooks、session 管理
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async with ClaudeSDKClient(options=options) as client:
    await client.query("你的任务")
    async for msg in client.receive_response():
        # 处理中间消息、权限请求、停止事件
        pass
```

**规则**：大多数场景用 `query()` 足够了。需要自定义工具（SDK MCP）、session 恢复、流式控制时才用 `ClaudeSDKClient`。

### 3.2 权限系统——安全地给 Agent 放权

Agent 的危险在于"能力越大，破坏越大"。SDK 通过权限模式控制：

```python
options=ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"],  # 白名单工具
    permission_mode="acceptEdits"              # 自动放行文件编辑
)
```

| 模式 | 行为 |
|------|------|
| `"default"` | 危险操作（删除、写系统文件）弹出确认 |
| `"plan"` | 只做规划，不执行任何操作 |
| `"acceptEdits"` | 自动批准文件编辑，不弹窗 |
| `"bypassPermissions"` | 跳过所有检查（慎用） |

### 3.3 Hook 机制——拦截每一次工具调用

```python
async def audit_tool_use(input_data, tool_use_id, context):
    """每次工具调用后记录日志"""
    file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
    print(f"[AUDIT] {context.agent_id} 修改了: {file_path}")
    return {}

options=ClaudeAgentOptions(
    hooks={
        "PostToolUse": [HookMatcher(matcher="Edit|Write", hooks=[audit_tool_use])]
    }
)
```

可拦截的生命周期事件：
- `PreToolUse` / `PostToolUse` / `PostToolUseFailure`
- `UserPromptSubmit` — 用户提交 prompt 时
- `Stop` / `SubagentStop` — Agent 停止时
- `PermissionRequest` — 权限请求时

---

## 四、MCP 协议：扩展 Agent 能力的标准方式

MCP（Model Context Protocol）是 Anthropic 推出的**工具扩展协议**，让 Agent 可以连接任意外部数据源和工具。

### 4.1 内置 MCP 服务器示例

```python
async for message in query(
    prompt="打开 example.com 并描述页面内容",
    options=ClaudeAgentOptions(
        mcp_servers={
            # Playwright 浏览器自动化
            "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]},
            # PostgreSQL 数据库
            "postgres": {
                "command": "npx",
                "args": ["-y", "@modelcontextprotocol/server-postgres"],
                "env": {"DATABASE_URL": os.environ["DATABASE_URL"]}
            }
        }
    )
):
    pass
```

### 4.2 自定义工具（SDK MCP）

通过 `@tool` 装饰器定义自己的工具：

```python
from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeSDKClient

@tool("get_weather", "获取指定位置的当前天气", {"location": str})
async def get_weather(args):
    location = args["location"]
    return {"content": [{"type": "text", "text": f"{location} 天气晴朗，72°F"}]}

server = create_sdk_mcp_server("my-tools", tools=[get_weather])

options = ClaudeAgentOptions(mcp_servers={"my-tools": server})
```

---

## 五、子 Agent：复杂任务的分解执行

```python
async for message in query(
    prompt="用 code-reviewer agent 审查这个代码库",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep", "Agent"],
        agents={
            "code-reviewer": AgentDefinition(
                description="代码质量与安全审查专家",
                prompt="分析代码质量，给出改进建议",
                tools=["Read", "Glob", "Grep"]
            )
        }
    )
):
    pass
```

主 Agent 通过 `"Agent"` 工具触发子 Agent，两者共享 `allowed_tools` 白名单。

---

## 六、Session 管理：上下文持久化

### 6.1 Session 恢复

```python
# 第一个请求：捕获 session_id
async for message in query(prompt="读取认证模块", options=ClaudeAgentOptions(...)):
    if isinstance(message, SystemMessage) and message.subtype == "init":
        session_id = message.data["session_id"]

# 后续请求：基于同一 session 继续
async for message in query(
    prompt="找到所有调用它的地方",
    options=ClaudeAgentOptions(resume=session_id)
):
    pass
```

### 6.2 Session 历史查询

```python
from claude_agent_sdk import list_sessions, get_session_messages

sessions = list_sessions()  # 同步调用
for s in sessions:
    print(f"{s.session_id}: {s.cwd}")
```

---

## 七、与竞品的核心差异

| 维度 | Agent SDK | LangChain Agents | OpenAI Agents SDK |
|------|-----------|-----------------|-------------------|
| 工具执行模型 | 客户端 SDK 执行，完全可控 | 自行实现循环 | 服务器端执行 |
| MCP 支持 | 原生 | 需适配器 | 不支持 |
| 权限粒度 | 工具级白名单 + 运行时 hooks | 粗粒度 | 基础 |
| Session 恢复 | 原生支持 | 需自行实现 | 不支持 |
| 代码执行 | Anthropic 托管沙箱 | 自行实现 | 不支持 |

---

## 八、工程落地建议

**推荐场景：**
- 需要模型自主读写文件/执行命令的编码助手
- 复杂多步任务，需要子 Agent 分解
- 需要与数据库、API 等外部系统深度交互
- 需要精细安全审计的企业应用

**不推荐场景：**
- 简单单次分类/提取 → 直接用 Messages API
- 固定流程对话 → Messages API + Tool Use 足够
- 对延迟敏感（每次 Tool Call 都有往返开销）

**性能优化：**
- `allowed_tools` 尽量精确，减少不必要的上下文
- Session 复用减少上下文初始化开销
- Prompt Caching 对重复任务有显著收益

---

## 结语

Claude Agent SDK 的设计思路很清晰：**让模型发挥自主能力的同时，把工程控制权完整留给开发者**。权限系统、hooks、MCP 协议构成了三层安全网，而 `query()` 的极简 API 降低了入门门槛。如果你正在构建需要模型"动手做事"的应用，Agent SDK 值得优先考虑。


一句话概括：Agent SDK = 帮你包好了 Agent 常需的一切基础设施，你只需定义任务和边界。

从 API 调用到自主 Agent：Claude Agent SDK 完整解析

架构师

人工智能

后端

开发工具

Claude Agent SDK是一款强大的AI开发工具包，提供完整的Agent基础设施，支持多步任务执行、工具调用和权限管理。它通过MCP协议扩展能力，内置安全机制和会话管理，适用于编码助手、复杂任务分解等场景。相比竞品，SDK在工具执行、权限控制和会话恢复方面更具优势，是构建智能应用的理想选择。

安全审计

SQL数据库

PostgreSQL

数据库

服务器

Agent

2026采购季 | AI焕新·智启新局

tencentdb-catalog

4核4G3M云服务器 新用户低至38元/年！

postgres

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

从 API 调用到自主 Agent：Claude Agent SDK 完整解析-腾讯云开发者社区-腾讯云

从 API 调用到自主 Agent：Claude Agent SDK 完整解析

从 API 调用到自主 Agent：Claude Agent SDK 完整解析

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐