Agent SDK 概览

原文：Agent SDK overview

一句话

使用 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 或更高版本)
设置 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 概览

一句话

什么时候翻这页

核心概念

怎么做

安装和设置

基本使用

命令 / 配置速查

初学者易错点

相关词条