Agent SDK 概览
一句话
使用 Claude Code 作为库构建生产级 AI 代理，提供文件读取、命令执行、代码编辑等自主能力。
什么时候翻这页
- 需要在应用程序中集成 Claude 的代理功能
- 构建需要自主操作文件、运行命令、搜索代码的 AI 代理
- 想了解如何使用 Python 或 TypeScript 编程控制 Claude 代理
- 需要在 CI/CD 流程中自动化 Claude 代理任务
核心概念
- Agent SDK：将 Claude Code 的功能封装为库，允许开发者通过编程方式创建 AI 代理
- 内置工具：SDK 提供读取文件、运行命令、编辑代码等预置工具，无需自行实现工具执行
- 代理循环：Agent SDK 处理代理的完整循环，包括工具调用、结果处理和决策
- 上下文管理：维护代理的上下文信息，包括文件读取、分析结果和对话历史
- 子代理：可以创建专门处理特定子任务的代理，由主代理协调工作
- 会话：维护跨多次交流的上下文，可以恢复或分支以探索不同方法
怎么做
安装和设置
-
安装 SDK
- TypeScript:
npm install @anthropic-ai/claude-agent-sdk - Python:
pip install claude-agent-sdk(需要 Python 3.10 或更高版本)
- TypeScript:
-
设置 API 密钥
- 从 Console 获取 API 密钥
- 设置环境变量:
export ANTHROPIC_API_KEY=your-api-key - 支持第三方提供商认证（Amazon Bedrock、Claude Platform on AWS、Google Vertex AI、Microsoft Azure）
-
运行第一个代理
- 使用
query函数创建代理 - 通过
allowed_tools参数指定代理可用的工具 - 处理代理返回的消息流
- 使用
基本使用
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="What files are in this directory?",
options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "What files are in this directory?",
options: { allowedTools: ["Bash", "Glob"] }
})) {
if ("result" in message) console.log(message.result);
}
命令 / 配置速查
| 工具 | 功能 |
|---|---|
| Read | 读取工作目录中的任何文件 |
| Write | 创建新文件 |
| Edit | 对现有文件进行精确编辑 |
| Bash | 运行终端命令、脚本、git 操作 |
| Monitor | 监视后台脚本并将每行输出作为事件反应 |
| Glob | 按模式查找文件（**/*.ts、src/**/*.py） |
| Grep | 使用正则表达式搜索文件内容 |
| WebSearch | 搜索网络获取最新信息 |
| WebFetch | 获取并解析网页内容 |
| AskUserQuestion | 向用户提出澄清问题并提供多选选项 |
| 环境变量 | 用途 |
|---|---|
| ANTHROPIC_API_KEY | Anthropic API 密钥 |
| CLAUDE_CODE_USE_BEDROCK | 使用 Amazon Bedrock 认证（设为 1） |
| CLAUDE_CODE_USE_ANTHROPIC_AWS | 使用 Claude Platform on AWS 认证（设为 1） |
| CLAUDE_CODE_USE_VERTEX | 使用 Google Vertex AI 认证（设为 1） |
| CLAUDE_CODE_USE_FOUNDRY | 使用 Microsoft Azure 认证（设为 1） |
初学者易错点
- Python 版本兼容性：Python SDK 需要 3.10 或更高版本，否则会报 "No matching distribution found for claude-agent-sdk"
- 工具权限：默认情况下，代理没有工具权限，必须在
allowed_tools中明确指定 - 异步处理：Python SDK 使用异步模式，需要正确使用
asyncio.run()或其他异步运行机制 - 第三方认证：使用第三方提供商认证时，需要同时设置相应的环境变量和提供商凭证
- 会话管理：会话 ID 需要从系统消息中捕获，而不是从结果消息中获取
相关词条
agent-sdk/quickstart- 快速构建代理的入门指南agent-sdk/hooks- 自定义代理生命周期中的关键点agent-sdk/subagents- 创建专门处理特定子任务的代理agent-sdk/mcp- 通过模型上下文协议连接外部系统agent-sdk/permissions- 控制代理可以使用哪些工具agent-sdk/sessions- 维护跨多次交流的上下文