掌握Claude Agent SDK Python：从入门到精通的实战指南

2026-04-07 13:00:28作者：庞队千Virginia

场景化问题：AI应用开发的痛点与解决方案

在构建AI应用时，你是否遇到过以下问题：如何高效地与Claude AI助手集成？怎样安全地管理工具调用权限？如何自定义满足特定业务需求的工具？Claude Agent SDK Python为这些问题提供了全面的解决方案，让你能够快速构建强大的AI应用。

痛点解析

集成复杂度高：直接与AI模型交互需要处理复杂的通信协议和数据格式转换。
工具管理混乱：缺乏统一的工具注册和调用机制，导致代码难以维护。
权限控制不足：无法细粒度地控制AI对系统资源的访问权限。
扩展性受限：难以根据业务需求自定义工具和功能。

核心功能

Claude Agent SDK Python提供了以下核心功能来解决上述痛点：

简洁的API接口：封装了复杂的通信细节，提供直观的API供开发者使用。
MCP服务器：作为"智能工具中台"，统一管理各类工具的注册、调用和生命周期。
灵活的权限控制：通过钩子机制实现对工具使用的细粒度控制。
可扩展的架构：支持自定义工具开发，满足特定业务需求。

实战案例：智能日期处理助手

假设你需要开发一个能够处理日期相关任务的AI助手，如日期转换、计算日期间隔等。使用Claude Agent SDK Python，你可以快速实现这个功能。

环境准备与安装

场景化引入

小明是一名开发工程师，他需要为团队开发一个AI助手，帮助处理日常工作中的日期计算问题。他听说Claude Agent SDK Python可以快速构建这样的应用，但不知道如何开始。

系统要求

Python 3.10+
Node.js
Claude Code 2.0.0+

安装步骤

🔧 基础安装

首先，通过pip安装SDK：

pip install claude-agent-sdk

然后安装Claude Code：

npm install -g @anthropic-ai/claude-code

⚠️ 常见错误及解决方案

安装失败：确保Python版本符合要求，建议使用虚拟环境。

python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

Claude Code未找到：检查Node.js环境变量配置，或尝试重新安装。
权限问题：在Linux/Mac上可能需要使用sudo安装npm包。

快速入门：构建你的第一个AI助手

场景化引入

小明已经完成了环境搭建，现在他想创建一个简单的AI助手，能够回答日期相关的问题。他需要了解如何使用SDK发送查询并获取响应。

核心概念：查询流程

Claude Agent SDK Python的查询流程如下：

创建查询请求
发送请求到Claude AI
接收并处理响应流
输出结果

分级示例代码

基础版：简单日期查询

import anyio
from claude_agent_sdk import query

async def main():
    # 发送日期查询请求
    async for response in query(prompt="今天是星期几？"):
        # 处理响应
        print(f"AI响应: {response}")

if __name__ == "__main__":
    anyio.run(main)

进阶版：带选项的查询

from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    # 创建自定义选项
    agent_options = ClaudeAgentOptions(
        system_prompt="你是一个专业的日期处理助手，只回答与日期相关的问题。",
        max_turns=2  # 限制对话轮次
    )
    
    # 发送带选项的查询
    async for response in query(
        prompt="2023年10月1日是星期几？距离今天还有多少天？",
        options=agent_options
    ):
        print(f"AI响应: {response}")

if __name__ == "__main__":
    anyio.run(main)

⚠️ 常见错误及解决方案

异步执行错误：确保使用anyio.run()或其他异步运行时来执行异步函数。
选项配置错误：检查ClaudeAgentOptions的参数是否正确，特别是allowed_tools和permission_mode。
响应处理不当：query()返回的是异步迭代器，需要使用async for循环处理。

核心功能详解：ClaudeSDKClient与工具使用

场景化引入

小明的AI助手已经能够回答简单的日期问题，但他希望进一步增强功能，让AI能够执行更复杂的日期计算任务，比如计算两个日期之间的天数差。这时候需要使用ClaudeSDKClient和内置工具。

核心概念：ClaudeSDKClient与工具系统

ClaudeSDKClient是SDK的核心类，提供了与Claude AI进行双向交互的能力。它支持工具调用、钩子机制等高级功能。工具系统允许AI调用各种功能模块，扩展其能力范围。

分级示例代码

基础版：使用内置工具

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async def main():
    # 配置允许使用的工具
    options = ClaudeAgentOptions(
        allowed_tools=["Bash"],
        permission_mode='acceptEdits'  # 自动接受文件编辑
    )
    
    # 创建客户端并发送查询
    async with ClaudeSDKClient(options=options) as client:
        await client.query("计算2023年1月1日到2023年12月31日之间的天数差，并将结果保存到days_diff.txt文件中")
        
        # 接收并处理响应
        async for message in client.receive_response():
            print(f"AI响应: {message}")

if __name__ == "__main__":
    anyio.run(main)

进阶版：工具权限控制

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, HookMatcher

async def check_bash_command(input_data, tool_use_id, context):
    """检查Bash命令是否安全"""
    tool_name = input_data["tool_name"]
    tool_input = input_data["tool_input"]
    
    if tool_name != "Bash":
        return {}
        
    command = tool_input.get("command", "")
    # 禁止危险命令
    dangerous_commands = ["rm", "mv", "cp"]
    for cmd in dangerous_commands:
        if cmd in command:
            return {
                "hookSpecificOutput": {
                    "hookEventName": "PreToolUse",
                    "permissionDecision": "deny",
                    "permissionDecisionReason": f"禁止使用危险命令: {cmd}",
                }
            }
    return {}

async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Bash"],
        hooks={
            "PreToolUse": [
                HookMatcher(matcher="Bash", hooks=[check_bash_command]),
            ],
        }
    )
    
    async with ClaudeSDKClient(options=options) as client:
        await client.query("计算2023年和2024年的天数差，并将结果保存到days_diff.txt文件中")
        
        async for message in client.receive_response():
            print(f"AI响应: {message}")

if __name__ == "__main__":
    anyio.run(main)

⚠️ 常见错误及解决方案

工具未授权：确保在ClaudeAgentOptions中正确设置allowed_tools。
钩子函数错误：钩子函数需要返回特定格式的字典，否则可能导致处理异常。
上下文管理不当：确保使用async with语句来管理ClaudeSDKClient的生命周期。

自定义工具开发：构建日期处理工具集

场景化引入

小明发现内置工具无法满足团队的特定日期处理需求，比如计算两个日期之间的工作日数（排除周末和节假日）。他需要开发自定义工具来扩展AI的能力。

核心概念：MCP服务器与工具注册

MCP（工具通信协议）服务器作为"智能工具中台"，负责管理自定义工具的注册、发现和调用。通过MCP服务器，你可以将自己开发的工具集成到AI助手中。

工具架构设计

自定义工具的架构包括以下几个部分：

工具定义：使用@tool装饰器定义工具函数。
参数验证：确保输入参数的类型和格式正确。
业务逻辑：实现工具的核心功能。
结果封装：按照SDK要求的格式返回结果。
服务器注册：将工具注册到MCP服务器。

分级示例代码

基础版：简单日期转换工具

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions, ClaudeSDKClient
from datetime import datetime

# 定义日期转换工具
@tool("date_convert", "将日期在不同格式之间转换", {
    "date_str": str, 
    "input_format": str, 
    "output_format": str
})
async def convert_date(args):
    """
    将日期字符串从输入格式转换为输出格式
    
    参数:
    date_str: 要转换的日期字符串
    input_format: 输入日期格式 (如 "%Y-%m-%d")
    output_format: 输出日期格式 (如 "%d/%m/%Y")
    """
    try:
        # 解析输入日期
        date_obj = datetime.strptime(args["date_str"], args["input_format"])
        # 转换为输出格式
        result = date_obj.strftime(args["output_format"])
        return {
            "content": [{"type": "text", "text": f"转换结果: {result}"}]
        }
    except Exception as e:
        return {
            "content": [{"type": "text", "text": f"转换失败: {str(e)}"}]
        }

# 创建MCP服务器并注册工具
date_server = create_sdk_mcp_server(
    name="date-tools",
    version="1.0.0",
    tools=[convert_date]
)

# 使用自定义工具
async def main():
    options = ClaudeAgentOptions(
        mcp_servers={"date": date_server},
        allowed_tools=["mcp__date__date_convert"]
    )
    
    async with ClaudeSDKClient(options=options) as client:
        await client.query("将日期 '2023-12-25' 从 '%Y-%m-%d' 格式转换为 '%d/%m/%Y' 格式")
        
        async for message in client.receive_response():
            print(f"AI响应: {message}")

if __name__ == "__main__":
    anyio.run(main)

进阶版：工作日计算工具集

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions, ClaudeSDKClient
from datetime import datetime, timedelta
import holidays

# 定义工作日计算工具
@tool("workday_count", "计算两个日期之间的工作日数量（排除周末和节假日）", {
    "start_date": str, 
    "end_date": str,
    "country": str
})
async def count_workdays(args):
    """
    计算两个日期之间的工作日数量
    
    参数:
    start_date: 开始日期 (格式: YYYY-MM-DD)
    end_date: 结束日期 (格式: YYYY-MM-DD)
    country: 国家代码 (如 'CN' 表示中国)
    """
    try:
        # 解析日期
        start = datetime.strptime(args["start_date"], "%Y-%m-%d")
        end = datetime.strptime(args["end_date"], "%Y-%m-%d")
        
        # 获取国家节假日
        country_holidays = holidays.country_holidays(args["country"])
        
        # 计算工作日
        workdays = 0
        current_date = start
        
        while current_date <= end:
            # 检查是否为周末或节假日
            if current_date.weekday() < 5 and current_date not in country_holidays:
                workdays += 1
            current_date += timedelta(days=1)
            
        return {
            "content": [{"type": "text", "text": f"{args['start_date']} 到 {args['end_date']} 之间共有 {workdays} 个工作日"}]
        }
    except Exception as e:
        return {
            "content": [{"type": "text", "text": f"计算失败: {str(e)}"}]
        }

# 定义日期偏移工具
@tool("date_offset", "计算日期偏移后的结果", {
    "date_str": str, 
    "days": int,
    "format": str
})
async def offset_date(args):
    """
    计算日期偏移后的结果
    
    参数:
    date_str: 基准日期 (格式: YYYY-MM-DD)
    days: 偏移天数 (正数为未来，负数为过去)
    format: 输出日期格式 (如 "%Y-%m-%d")
    """
    try:
        date_obj = datetime.strptime(args["date_str"], "%Y-%m-%d")
        new_date = date_obj + timedelta(days=args["days"])
        return {
            "content": [{"type": "text", "text": new_date.strftime(args["format"])}]
        }
    except Exception as e:
        return {
            "content": [{"type": "text", "text": f"计算失败: {str(e)}"}]
        }

# 创建MCP服务器并注册工具
date_tools_server = create_sdk_mcp_server(
    name="advanced-date-tools",
    version="1.0.0",
    tools=[count_workdays, offset_date]
)

# 使用自定义工具集
async def main():
    options = ClaudeAgentOptions(
        mcp_servers={"date": date_tools_server},
        allowed_tools=[
            "mcp__date__workday_count",
            "mcp__date__date_offset"
        ]
    )
    
    async with ClaudeSDKClient(options=options) as client:
        query_text = """
        计算2023年10月1日到2023年10月31日之间的工作日数量（中国节假日），
        然后计算这个日期范围之后30个工作日的日期，格式为YYYY-MM-DD。
        """
        await client.query(query_text)
        
        async for message in client.receive_response():
            print(f"AI响应: {message}")

if __name__ == "__main__":
    anyio.run(main)

工具生命周期管理

自定义工具的生命周期包括以下阶段：

注册阶段：工具被添加到MCP服务器，AI可以发现并使用它。
调用阶段：AI根据需要调用工具，传递参数并等待结果。
执行阶段：工具函数执行，处理业务逻辑。
结果返回：工具将结果返回给AI，AI继续处理。
销毁阶段：MCP服务器关闭时，工具资源被释放。

⚠️ 常见错误及解决方案

工具注册失败：确保工具函数使用@tool装饰器正确定义，参数格式正确。
参数验证错误：工具函数应先验证输入参数，避免运行时错误。
结果格式错误：确保工具返回的结果符合SDK要求的格式。
性能问题：对于耗时操作，考虑使用异步处理或缓存机制。

高级功能与实用技巧

场景化引入

小明的日期处理AI助手已经上线使用，团队反馈良好。现在他想进一步优化性能，并添加一些高级功能，如流式响应和错误处理。

流模式处理

流模式允许实时处理AI的响应，特别适合需要即时反馈的场景。

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["mcp__date__workday_count"]
    )
    
    async with ClaudeSDKClient(options=options) as client:
        await client.query("计算2023年所有月份的工作日数量，并分别列出")
        
        # 实时处理流式响应
        async for message in client.receive_response():
            if message.type == "text":
                print(f"AI: {message.content}")
            elif message.type == "tool_use":
                print(f"正在使用工具: {message.tool_name}")
            elif message.type == "tool_result":
                print(f"工具结果: {message.content}")

if __name__ == "__main__":
    anyio.run(main)

错误处理机制

完善的错误处理可以提高应用的健壮性。

from claude_agent_sdk import (
    ClaudeSDKError, CLINotFoundError, CLIConnectionError,
    ProcessError, CLIJSONDecodeError
)

async def safe_query(prompt):
    try:
        async with ClaudeSDKClient() as client:
            await client.query(prompt)
            responses = []
            async for message in client.receive_response():
                responses.append(message)
            return responses
    except CLINotFoundError:
        print("错误: 未找到Claude Code，请先安装")
    except CLIConnectionError:
        print("错误: 无法连接到Claude Code服务")
    except ProcessError as e:
        print(f"错误: 进程执行失败，退出码: {e.exit_code}")
    except CLIJSONDecodeError:
        print("错误: 无法解析响应数据")
    except ClaudeSDKError as e:
        print(f"SDK错误: {str(e)}")
    except Exception as e:
        print(f"未知错误: {str(e)}")
    return None

实用技巧一：会话管理

通过保存和恢复会话状态，可以实现多轮对话的上下文连续性。

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        session_id="date-assistant-001",  # 会话ID，用于保存上下文
        max_turns=5  # 最大对话轮次
    )
    
    async with ClaudeSDKClient(options=options) as client:
        # 第一轮查询
        await client.query("记住今天是2023-10-01")
        async for _ in client.receive_response():
            pass  # 处理响应
        
        # 第二轮查询，利用上下文
        await client.query("30天后是几号？")
        async for message in client.receive_response():
            print(f"AI响应: {message}")

if __name__ == "__main__":
    anyio.run(main)

实用技巧二：批量处理

使用异步任务处理多个查询，提高效率。

import anyio
from claude_agent_sdk import query

async def process_query(prompt):
    """处理单个查询"""
    results = []
    async for message in query(prompt=prompt):
        results.append(message)
    return results

async def batch_process():
    """批量处理多个查询"""
    prompts = [
        "计算2023-01-01到2023-01-31的工作日数量",
        "计算2023-02-01到2023-02-28的工作日数量",
        "计算2023-03-01到2023-03-31的工作日数量"
    ]
    
    # 并发处理所有查询
    results = await anyio.gather(*[process_query(p) for p in prompts])
    
    # 输出结果
    for i, result in enumerate(results):
        print(f"查询 {i+1} 结果: {result}")

if __name__ == "__main__":
    anyio.run(batch_process)