Claude Agent SDK Python实战：自定义工具、多轮会话与Hooks安全控制

Anthropic 近期将 Claude Code SDK 正式更名为 Claude Agent SDK，为开发者提供了在 Claude Code 的 Agent Harness 之上构建自定义 AI Agent 的能力。本文基于一个12分钟的完整演练视频，系统梳理 Claude Agent SDK（Python版）的核心概念与实战用法，帮助你快速上手。

背景补充：Agent Harness 与更名的意义 Claude Agent SDK 的前身 Claude Code SDK 脱胎于 Anthropic 的 Claude Code 产品——一个面向开发者的命令行 AI 编程助手。所谓「Agent Harness」，是指 Claude Code 内部已经实现的一套完整 Agent 执行框架，包含任务规划、工具调用、结果反馈等闭环机制。更名为 Claude Agent SDK 不仅是品牌层面的调整，更标志着 Anthropic 将这套框架从「编程助手的内部实现」提升为「通用 Agent 构建平台」，开发者可以在这个成熟的执行基础设施之上叠加自己的业务逻辑，而无需从零搭建 Agent 循环。

为什么需要 Claude Agent SDK？

如果你只是使用 Claude Code 本身，默认的交互方式已经足够。但当你需要更细粒度的控制——比如注入自定义工具、集成 MCP 服务、在工具执行前后插入安全检查——就需要 Claude Agent SDK 了。

简单来说，Claude Agent SDK 让你能够：

在 Agent 的执行循环中注入自定义逻辑
将自定义工具以 MCP Server 的形式提供给 Claude Code
通过 Hooks 机制在工具执行前后进行干预
维护多轮对话 Session，实现持续交互

SDK 提供了 TypeScript 和 Python 两个版本，本文聚焦 Python SDK。其核心 API 包括：Functions（query、tools、hooks）和 Classes（CloudSdkClient、CloudAgentOptions）。

环境搭建与安装

开始之前，需要完成以下准备工作：

# 创建项目目录和虚拟环境
mkdir cloud-agent-sdk-demo && cd cloud-agent-sdk-demo
python3.12 -m venv agent-sdk
source agent-sdk/bin/activate

# 安装 SDK
pip install cloud-agent-sdk

# 设置 API Key
export ANTHROPIC_API_KEY="your-api-key-here"

API Key 可以在 console.anthropic.com 的 API Keys 页面创建。

Claude Agent SDK 安装完成

核心功能一：Query 基础查询

最简单的使用方式是直接调用 query 函数，相当于向 Claude Code 发送一次性请求：

from cloud_agent_sdk import query

result = query(prompt="Hello Cloud")

for message in result.messages:
    if message.role == "assistant":
        print(message.content)

模型会返回类似"Hello! 我今天能怎么帮你？无论你需要 coding、文件管理、debugging 或其他任何帮助，我都在这里"的回复。

你还可以通过 CloudAgentOptions 传入系统提示词等配置：

from cloud_agent_sdk import query, CloudAgentOptions

options = CloudAgentOptions(system_prompt="你是一个 helpful assistant")
result = query(prompt="Hello", options=options)

这为每次查询提供了灵活的参数控制能力。

核心功能二：自定义 Tools 集成

Claude Agent SDK 最强大的特性之一，是允许你定义自定义工具并以 MCP Server 的形式提供给 Agent 使用。与通常创建外部 MCP Server 的方式不同，你可以直接在代码中定义工具函数。

什么是 MCP？ MCP（Model Context Protocol）是 Anthropic 于 2024 年底发布的开放协议，旨在标准化 AI 模型与外部工具、数据源之间的通信方式。它借鉴了编辑器领域 LSP（Language Server Protocol）的设计思路——LSP 统一了编辑器与语言服务之间的通信，MCP 则统一了 AI 模型与工具服务之间的通信。MCP Server 可以暴露工具（Tools）、资源（Resources）和提示词模板（Prompts）三类能力。SDK 中的 create_sdk_mcp_server 函数让开发者无需手动实现完整的 MCP 协议层，只需定义工具函数，SDK 会自动处理序列化、能力声明和消息路由，大幅降低集成门槛。

Claude Agent SDK 工具集成示例

以一个计算器工具为例：

from cloud_agent_sdk import tool, create_sdk_mcp_server

@tool
async def add(a: float, b: float):
    """Add two numbers"""
    return {"type": "text", "text": str(a + b)}

@tool
async def multiply(a: float, b: float):
    """Multiply two numbers"""
    return {"type": "text", "text": str(a * b)}

# 创建 MCP Server
calculator_server = create_sdk_mcp_server(
    name="calculator",
    version="1.0",
    tools=[add, multiply]
)

关键步骤解析：

使用 @tool 装饰器标记函数为自定义工具
异步函数接收类型化的参数，返回包含 type 和 text 的字典
通过 create_sdk_mcp_server 将多个工具打包为一个 MCP Server

创建好 MCP Server 后，在 CloudAgentOptions 中传入即可：

options = CloudAgentOptions(
    mcp_servers={"calculator": calculator_server}
)
result = query(prompt="3 乘以 2 等于多少？", options=options)

运行后可以看到，Agent 使用了 Claude Sonnet 4.5 模型，正确调用了 multiply 工具，返回结果 6。响应中还包含了完整的 metadata 信息。

核心功能三：CloudSdkClient 多轮会话

query 函数适合一次性交互，但如果你需要维护多轮对话 Session——类似与聊天机器人持续对话——就需要使用 CloudSdkClient 类。

为什么 SDK 大量使用 async/await？ AI Agent 的执行过程天然是 I/O 密集型的：调用 LLM API 需要等待网络响应，工具执行可能涉及文件读写或外部服务调用。Python 的 asyncio 事件循环允许在等待 I/O 时切换执行其他任务，避免线程阻塞。async with CloudSdkClient() 这样的异步上下文管理器则确保了连接资源的正确初始化与释放。对于不熟悉异步编程的开发者，可以将 await 理解为「在这里暂停等待结果，但不阻塞其他任务运行」——这是构建高性能 Agent 应用的基础能力。

CloudSdkClient 多轮会话示例

from cloud_agent_sdk import CloudSdkClient, tool, create_sdk_mcp_server

@tool
async def greet_user(name: str):
    """Greet a user by name"""
    return {"type": "text", "text": f"Hello, {name}!"}

my_tools_server = create_sdk_mcp_server(
    name="my_tools",
    version="1.0",
    tools=[greet_user]
)

options = CloudAgentOptions(
    mcp_servers={"my_tools": my_tools_server}
)

async with CloudSdkClient(options=options) as client:
    result = await client.query("Greet Alice")
    # 可以继续发送更多 query，保持同一 session
    result2 = await client.query("Now greet Bob")

使用 async with 上下文管理器创建 client 对象后，可以在同一 session 中多次调用 client.query()。Agent 会记住之前的对话上下文，实现真正的多轮交互。从返回结果可以看到，Agent 先说"我将使用 MCP Greet Tools 来问候 Alice"，然后实际调用工具返回"Hello, Alice!"。

核心功能四：Hooks 执行干预机制

Hooks 是 Claude Agent SDK 中最具安全价值的特性。在 Agent 的执行循环中，工具调用前后都可以插入自定义的检查逻辑。

AI 安全与 Hooks 的行业背景 Hooks 机制所解决的问题，在 AI 安全领域被称为「工具滥用」（Tool Misuse）风险。随着 AI Agent 获得越来越多的系统权限，如何防止模型被恶意提示词诱导执行破坏性操作成为关键挑战。这类攻击被称为「提示词注入」（Prompt Injection）——攻击者可能通过构造特殊输入让 Agent 执行 rm -rf / 或泄露敏感文件。pre_tool_use 拦截点本质上是在 Agent 执行链中插入了「人机协同检查点」（Human-in-the-loop Checkpoint），与 OWASP《LLM 应用十大安全风险》中推荐的「最小权限原则」高度吻合。在生产环境中，企业通常会在此层实现操作审计日志、敏感路径白名单和危险命令正则匹配等多层防护。

Claude Agent SDK Hooks 机制

一个典型的安全场景：阻止危险的 Bash 命令执行。

from cloud_agent_sdk import HookMatcher

async def check_bash_command(event):
    """检查 bash 命令是否包含危险操作"""
    if event.tool_name == "bash":
        dangerous_pattern = "mysavefile.txt"
        if dangerous_pattern in event.command:
            event.tool_use_permission = "deny"
            event.reason = f"Command contains invalid pattern: {dangerous_pattern}"

options = CloudAgentOptions(
    hooks={
        "pre_tool_use": HookMatcher(
            match="bash",  # 精确匹配工具名
            hook=check_bash_command
        )
    }
)

Hooks 的工作原理：

pre_tool_use：在工具执行之前触发，可以拦截危险操作
post_tool_use：在工具执行之后触发，可以审计或修改结果
HookMatcher 的 match 参数精确匹配工具名称
通过设置 tool_use_permission = "deny" 可以直接拒绝执行

这种机制对于生产环境中的安全防护至关重要。你可以防止 Agent 执行 rm -rf 这样的致命命令，或者保护特定文件不被删除或修改。

总结与展望

Claude Agent SDK 为开发者提供了四个层次的控制能力：

功能	适用场景	复杂度
Query	一次性查询	⭐
Tools + MCP Server	扩展 Agent 能力	⭐⭐
CloudSdkClient	多轮会话管理	⭐⭐⭐
Hooks	安全控制与执行干预	⭐⭐⭐

说个细节，该项目目前仍处于早期阶段，采用 MIT 开源许可证。随着社区的参与和 Anthropic 的持续投入，SDK 的功能和生态将会快速扩展。对于希望在 Claude Code 基础上构建定制化 AI Agent 的开发者来说，现在正是上手的好时机。

核心要点

Claude Agent SDK（原 Claude Code SDK）提供 Python 和 TypeScript 两个版本，允许开发者在 Claude Code 的 Agent Harness 之上构建自定义 AI Agent
通过 @tool 装饰器和 create_sdk_mcp_server 函数，可以将自定义工具以 MCP Server 形式注入 Agent，无需创建外部 MCP 服务
CloudSdkClient 类支持多轮对话 Session 管理，通过 async 上下文管理器维护持续交互
Hooks 机制（pre_tool_use / post_tool_use）可在工具执行前后插入安全检查逻辑，防止危险命令执行
项目目前处于早期阶段，采用 MIT 开源许可证，未来功能和生态将持续扩展