Claude Agent SDK Python 教程
用大白话带你从零开始掌握 Claude Agent SDK，最终构建一个完整的 AI Agent 助手。
这是什么？
这是一套面向有 Python 基础的开发者的中文教程。你将学会用 Python 代码控制 Claude —— 让它帮你读文件、写代码、执行命令、甚至构建一个完整的 AI 助手。
前置要求： - 熟悉 Python 基础语法 - 了解 async/await（不熟悉也没关系，教程会简要说明） - 一个 Claude API Key 或 Claude Pro/Max 订阅
教程目录
基础篇 —— "会走路"
| 章节 | 标题 | 你将学到 |
|---|---|---|
| 第 0 章 | 前言与环境准备 | SDK 是什么、环境搭建、API Key vs 订阅 |
| 第 1 章 | 第一次对话 | query() 函数、和 Claude 说第一句话 |
| 第 2 章 | 理解消息系统 | Message 类型、ContentBlock、消息结构 |
| 第 3 章 | 配置选项详解 | ClaudeAgentOptions 的核心配置项 |
进阶篇 —— "会跑步"
| 章节 | 标题 | 你将学到 |
|---|---|---|
| 第 4 章 | 多轮对话与流式交互 | ClaudeSDKClient、多轮对话、流式输出 |
| 第 5 章 | 自定义工具（SDK MCP） | @tool 装饰器、create_sdk_mcp_server |
| 第 6 章 | 钩子系统与事件驱动 | 10 种 Hook 事件、安全拦截 |
| 第 7 章 | 权限控制与安全 | 权限模式、沙盒、预算控制 |
实战篇 —— "能飞了"
| 章节 | 标题 | 你将学到 |
|---|---|---|
| 第 8 章 | 实战：项目架构设计 | MiniClaw 架构、双模式认证 |
| 第 9 章 | 实战：核心引擎与记忆 | 对话引擎、SQLite 记忆系统 |
| 第 10 章 | 实战：工具生态 | 工具注册中心、内置工具集 |
| 第 11 章 | 实战：高级特性 | 定时任务、多 Agent 协作、安全防护 |
实战项目：MiniClaw
实战篇（第 8-11 章）将渐进式构建一个 MiniClaw —— 类似 NanoClaw 的 CLI Agent 助手。
MiniClaw 的核心功能： - 多轮对话引擎（持续聊天，保持上下文） - 记忆系统（SQLite 持久化，跨会话记忆） - 可扩展工具生态（内置工具 + 自定义工具） - 安全防护（钩子拦截 + 权限控制） - 定时任务（asyncio 调度器） - 多 Agent 协作（子 Agent 完成专项任务） - 双模式认证（API Key / 订阅自动检测）
怎么学？
推荐路线： 从第 0 章开始，按顺序读到第 11 章。每章都有可运行的示例代码。
赶时间？ 直接跳到你需要的章节： - 想快速上手 → 第 0-1 章 - 想做多轮对话 → 第 4 章 - 想给 Claude 加自定义工具 → 第 5 章 - 想看完整项目 → 第 8-11 章
环境要求
- uv（Python 包管理工具）
- Claude Code CLI（
npm install -g @anthropic-ai/claude-code） - Claude API Key 或 Claude Pro/Max 订阅