Claude Agent SDK 使用指南：打造高效AI助手

引言

随着人工智能技术的飞速发展，构建能够自主思考、执行任务的AI助手已成为可能。Claude Agent SDK 正是 Anthropic 公司推出的一个强大工具包，旨在帮助开发者使用其先进的 Claude 大模型，轻松创建和部署高效的 AI 智能体。该 SDK 赋予 Claude 访问计算机环境的能力，使其能够自主读取文件、运行命令、搜索网络、甚至编辑代码，从而将 Claude 从一个对话式模型提升为一名能够执行复杂任务的“数字员工”。无论是自动化编程、深度研究、内容创作还是复杂工作流管理，Claude Agent SDK 都为打造具有高度自主性的 AI 助手提供了坚实的基础。

主要特性

Claude Agent SDK（原 Claude Code SDK）提供了一系列强大的特性，使其成为构建智能体的理想选择：

自动化上下文管理：智能地压缩和处理对话上下文，有效避免“上下文耗尽”问题，让智能体能够处理更长的任务序列。
丰富的工具生态系统：内置多种实用工具，包括：
- 文件操作：Read (读取文件), Write (写入文件), Edit (编辑文件), Glob (模式匹配文件), Grep (搜索文件内容)。
- 代码执行：Bash (执行 shell 命令)。
- Web 搜索：集成网络搜索能力，让 Claude 获取实时信息。
细粒度权限控制：开发者可以对智能体使用的工具和其访问权限进行精细控制，确保安全性和合规性。
流式和单次模式：提供灵活的交互模式，既可以用于单次任务执行，也可以用于持续对话和复杂流程。
自定义工具：支持使用 @tool 装饰器定义和集成自定义工具，极大扩展了 Claude 的能力，使其能够与任何外部系统或 API 交互。
钩子 (Hooks)：允许在智能体执行流程的关键节点插入自定义逻辑，实现自动化反馈、安全检查（例如，在执行 Bash 命令前拦截危险命令）和确定性处理。
子智能体 (Subagents)：支持创建具有独立上下文的专业智能体，用于处理特定子任务，实现任务分解和模块化管理。
会话连续性：在多次 query() 调用之间保持对话上下文，确保智能体对先前交互有记忆。
成本跟踪：内置使用情况监控，帮助开发者了解和控制智能体运行成本。

安装与环境准备

要开始使用 Claude Agent SDK，请确保您的开发环境满足以下先决条件：

Python: Python 3.10 或更高版本。
Node.js: 对于某些安装方式或 TypeScript SDK 的使用可能需要。

安装步骤：

安装 Claude Agent SDK (Python):
通过 pip 命令安装 Python SDK 是最常见的方式：

bash pip install claude-agent-sdk
请注意，从 v0.1.8+ 版本开始，Claude Code CLI 会自动与 SDK 捆绑，因此通常无需单独安装 CLI。
（可选）安装 Claude Code CLI:
如果您需要使用系统范围的安装或特定版本的 Claude Code CLI，可以通过 npm 或 curl 进行安装。SDK 默认会使用捆绑的 CLI，但您也可以通过 ClaudeAgentOptions(cli_path="/path/to/claude") 参数指定自定义的 CLI 路径。
- 通过 npm 安装 (macOS/Linux/WSL):
  bash npm i -g @anthropic-ai/claude-code
- 通过 curl 安装 (macOS/Linux):
  bash curl -fsSL https://claude.ai/install.sh | bash

认证

SDK 支持多种认证方式来访问 Claude API，最常用的是设置 Claude API Key：

Claude API Key (标准):
在运行智能体之前，请将您的 Claude API 密钥设置为环境变量：

bash export CLAUDE_API_KEY="your-api-key-here"
（请替换 "your-api-key-here" 为您的实际 API 密钥。）
其他认证方式：SDK 也支持与 Amazon Bedrock (AWS) 和 Google Vertex AI (GCP) 等平台的集成认证。

使用教程与核心概念

Claude Agent SDK 提供了两种主要的交互方式来构建智能体：query() 函数（适用于单次任务）和 ClaudeSDKClient 类（适用于持续对话和更复杂的控制）。

智能体循环 (Agent Loop)

Claude Agent SDK 的核心是一个结构化的智能体循环，它指导智能体完成任务，通常包括以下四个关键步骤：

收集上下文 (Gathering Context)：智能体通过自身的能力（如文件系统、Web 搜索）或与子智能体协作来获取完成任务所需的信息。
执行操作 (Taking Action)：根据收集到的上下文和任务目标，智能体利用内置工具、自定义工具、Bash 命令或代码生成等方式执行具体操作。
验证工作 (Verifying Work)：智能体（或外部机制）对执行结果进行验证，确保任务按预期完成。这可以通过定义规则、视觉反馈或让 LLM 作为评判者来实现。
重复 (Repeating)：根据任务的复杂性和当前状态，智能体可能会重复上述步骤，直到任务完全解决。

示例：使用 `query()` 函数进行单次任务

对于简单的、一次性任务，query() 函数是快速启动智能体的便捷方式。Claude 会自主处理工具的调用和执行过程：

“`python
from claude_agent_sdk import query
import asyncio

async def main():
async for message in query(prompt=”Fix the bug in auth.py”):
# 智能体执行过程中的信息会以流式输出
print(message)

if name == “main“:
asyncio.run(main())
“`

工具 (Tools)

工具是 Claude Agent SDK 的核心，它们赋予 Claude 与外部环境交互的能力。

内置工具：SDK 提供了开箱即用的工具，如 Read (读取文件), Write (写入文件), Bash (执行 shell 命令), Edit (编辑文件), Glob (文件模式匹配) 和 Grep (搜索文件内容)。这些工具使得 Claude 能够像一个程序员一样与文件系统和命令行进行交互。
自定义工具：通过使用 @tool 装饰器，您可以轻松地为 Claude 定义自定义工具。这允许您将 Claude 的能力扩展到任何外部 API 或自定义逻辑，例如，连接到数据库、发送邮件、调用内部微服务等。

“`python
from claude_agent_sdk import tool, query
import asyncio

@tool
def get_current_weather(location: str) -> str:
“””
Gets the current weather for a given location.
“””
if location == “London”:
return “Current weather in London: Cloudy with a temperature of 10°C.”
return “Weather data not available for this location.”

async def main():
async for message in query(prompt=”What’s the weather in London?”):
print(message)

if name == “main“:
asyncio.run(main())
“`

钩子 (Hooks)

钩子提供了一种在智能体执行流程中的特定点插入自定义逻辑的机制。这对于实现安全策略、日志记录、用户交互或预处理/后处理步骤非常有用。例如，您可以定义一个钩子来阻止智能体执行危险的 Bash 命令，如 rm -rf /。

适用场景

Claude Agent SDK 广泛适用于以下构建各种高效 AI 助手的场景：

开发助手：
- 自动化代码生成、测试和分析。
- SRE (Site Reliability Engineering) 诊断工具。
- 安全审查机器人。
- CI/CD 流程自动化。
研究与知识管理：
- 深度研究代理，能够自主检索、分析和总结信息。
- 自动化笔记记录和文档整理。
内容创作：
- 视频脚本生成。
- 文章撰写和编辑助手。
业务智能体：
- 法律助手，协助法律文档分析和咨询。
- 客户支持代理，自动处理常见问题和请求。
通用自动化：
- 自动化复杂工作流和任务。
- 构建聊天应用或对话式 UI。
- 将 Claude 的能力集成到现有 Python 应用中。
- 需要自定义工具和权限控制的企业级应用。