claude-agent-sdk Skill 技能

技能简介

claude-agent-sdk 是 Anthropic 官方发布的 Python SDK，用于程序化调用 Claude Code（Agent SDK）。它将 Claude Code CLI 的能力封装为 Python 库，让开发者无需启动独立进程即可在 Python 应用中调用 Claude 的 Agent 能力，实现代码编写、文件操作、Bash 命令执行等任务。

该 SDK 支持同步/异步两种调用模式，提供 query() 简易接口和 ClaudeSDKClient 高级接口，并内置了自定义工具（MCP Server）和 Hook 拦截机制。2026-09-30 发布 v0.2.163 版本，是目前 Python 生态中调用 Claude Code 最规范、最完整的官方方案。

核心能力

1. Python 原生集成：无需启动子进程，直接在 Python 代码中调用 Claude Code 能力，支持 Python 3.10+
2. Claude Code CLI 自动打包：SDK 发行包内置 Claude Code CLI，无需单独安装，下载即用
3. 双接口设计：query() 简单异步迭代器接口 vs ClaudeSDKClient 双向交互客户端，按需选择
4. 自定义工具（In-Process MCP Server）：用 @tool 装饰器将 Python 函数注册为 MCP 工具，无需外部进程
5. 权限细粒度控制：allowed_tools 白名单自动审批，disallowed_tools 屏蔽特定工具，permission_mode 控制审批行为
6. Hook 拦截机制：在 Agent 执行链路的关键节点（PreToolUse 等）插入自定义逻辑，实现行为控制与日志审计
7. 工作目录隔离：cwd 参数为每次任务指定独立工作目录，避免多任务间状态污染
8. 错误类型完备：提供 CLINotFoundError、CLIConnectionError、ProcessError、ResultError 等分层异常类

安装配置

前置要求：Python 3.10+

标准安装（推荐，自动包含 Claude Code CLI）：

pip install claude-agent-sdk

指定 CLI 路径（已有 Claude Code 安装时）：

ClaudeAgentOptions(cli_path='/usr/local/bin/claude')

独立安装 Claude Code CLI：

curl -fsSL https://claude.ai/install.sh | bash

使用步骤

第一步：基础调用（query 接口）

import anyio from claude_agent_sdk import query

async def main(): async for message in query(prompt='用 Python 写一个快速排序'): print(message)

anyio.run(main)

第二步：配置选项（系统提示词 + 工具权限）

from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions( system_prompt='你是一个专业 Python 开发者', max_turns=5, allowed_tools=['Read', 'Write', 'Bash'], permission_mode='acceptEdits' )

第三步：使用 ClaudeSDKClient 实现自定义工具

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeSDKClient

@tool('greet', '向用户打招呼', {'name': str}) async def greet_user(args): return {'content': [{'type': 'text', 'text': f'你好，{args["name"]}！'}]}

server = create_sdk_mcp_server(name='my-tools', version='1.0.0', tools=[greet_user]) options = ClaudeAgentOptions(mcp_servers={'tools': server}, allowed_tools=['mcptoolsgreet'])

async with ClaudeSDKClient(options=options) as client: await client.query('向 Alice 打招呼')

第四步：使用 Hook 拦截工具调用

from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient, HookMatcher

async def block_dangerous_bash(input_data, tool_use_id, context): if input_data['tool_name'] == 'Bash': cmd = input_data['tool_input'].get('command', '') if 'rm -rf' in cmd or ('curl' in cmd and '|' in cmd): return {'hookSpecificOutput': {'permissionDecision': 'deny', 'permissionDecisionReason': '危险命令已拦截'}} return {}

options = ClaudeAgentOptions( allowed_tools=['Bash'], hooks={'PreToolUse': [HookMatcher(matcher='Bash', hooks=[block_dangerous_bash])]} )

适用场景

1. AI Coding 助手构建：在 Python 应用中集成 Claude Code 能力，实现代码审查、自动化重构、批量文件修改
2. CI/CD 流程自动化：用自然语言描述任务，Claude Code 自动执行 Bash 命令完成构建、测试、部署流程
3. 数据分析流水线：调用 Claude 读取数据文件、编写处理脚本、执行分析，并将结果写回指定位置
4. 文档批量处理：批量读取 Markdown 文件，按要求统一格式、补充内容、生成摘要
5. 开发环境初始化：新项目克隆后，用 Claude Code 自动安装依赖、配置 ESLint/Prettier、初始化 Git Hooks
6. 代码迁移与重构：批量将旧代码库迁移至新框架，Claude 自动识别模式并逐文件修改

适用人群

• Python 开发者：需要程序化调用 Claude Code 能力，用于自动化脚本或 AI 功能集成
• DevOps 工程师：构建 AI 驱动的 CI/CD 流水线，减少人工重复操作
• AI 应用开发者：在自主应用内嵌入 Claude Agent 能力，实现主控 AI + 工具 Agent 的混合架构
• 数据工程师：将 Claude Code 作为数据处理任务编排层，用自然语言驱动数据清洗与转换

工作原理

claude-agent-sdk 底层通过 Claude Code CLI（bundled in the wheel）以子进程方式运行 Agent 实例，Python SDK 与 CLI 之间通过 JSON-RPC over stdio 通信。query() 发起单次异步查询，CLI 启动执行返回结果后退出，适合独立任务；ClaudeSDKClient 启动持久化 CLI 会话，通过 client.query() 和 client.receive_response() 实现多轮对话，支持同一个会话内多次工具调用。自定义工具通过 SDK 内置的 In-Process MCP Server 实现，Python 函数直接注册为 MCP 工具，工具调用通过函数调用完成，无 IPC 开销。

官方链接

• PyPI 主页：https://pypi.org/project/claude-agent-sdk/
• 官方文档：https://docs.anthropic.com/en/docs/claude-code/sdk
• Anthropic Agent SDK 文档：https://platform.claude.com/docs/en/agent-sdk/python
• Claude Code 工具列表：https://code.claude.com/docs/en/settings#tools-available-to-claude