Claude-Agent-SDK以编程方式构建AI代理使用Claude-Code的功能
- AI人工智能
- -386分钟前
- 4热度
- 0评论
# 说明
Claude Agent SDK 使您能够利用 Claude Code 的功能，以编程方式构建 AI 代理。创建能够理解代码库、编辑文件、运行命令和执行复杂工作流程的自主代理。
构建能够自主读取文件、运行命令、搜索网络、编辑代码等的 AI 代理。代理 SDK 提供与 Claude Code 相同的工具、代理循环和上下文管理功能，并支持 Python 和 TypeScript 编程。
```
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Find and fix the bug in auth.ts",
options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
console.log(message); // Claude reads the file, finds the bug, edits it
}
```
# 安装 Claude Agent SDK
```bash
npm install @anthropic-ai/claude-agent-sdk
```
> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 快速入门
> 使用 Python 或 TypeScript Agent SDK 开始构建可自主运行的 AI 代理。
使用 Agent SDK 构建 AI 代理，它可以读取您的代码、查找错误并修复它们，所有这些都无需人工干预。
**你的工作内容：**
1. 使用 Agent SDK 设置项目
2. 创建一个包含一些错误代码的文件
3. 运行一个代理程序，自动查找并修复错误。
## 先决条件
* **Node.js 18+**或**Python 3.10+**
* 一个 **Anthropic 账户** ([在此注册](https://platform.claude.com/))
## 设置
### 创建项目文件夹
```bash
mkdir my-agent && cd my-agent
```
对于您自己的项目，您可以从任何文件夹运行 SDK；默认情况下，它将可以访问该目录及其子目录中的文件。
### 安装 SDK
```bash
# npm
npm install @anthropic-ai/claude-agent-sdk
# Python (uv)
uv init && uv add claude-agent-sdk
# Python（pip）
# 先创建虚拟环境，然后安装
python3 -m venv .venv && source .venv/bin/activate
pip3 install claude-agent-sdk
```
> TypeScript SDK 将适用于您平台的原生 Claude Code 二进制文件作为可选依赖项打包在一起，因此您无需单独安装 Claude Code。
### 设置您的 API 密钥
[从Claude 控制台](https://platform.claude.com/)获取 API 密钥，然后`.env`在项目目录中创建一个文件：
```bash
ANTHROPIC_API_KEY=your-api-key
```
该SDK还支持通过第三方API提供商进行身份验证：
- **Amazon Bedrock**：设置`CLAUDE_CODE_USE_BEDROCK=1`环境变量并配置 AWS 凭证
- **在 AWS 上使用 Claude 平台**：设置`CLAUDE_CODE_USE_ANTHROPIC_AWS=1`并`ANTHROPIC_AWS_WORKSPACE_ID`配置 AWS 凭证
- **Google Vertex AI**：设置`CLAUDE_CODE_USE_VERTEX=1`环境变量并配置 Google Cloud 凭据
- **Microsoft Azure**：设置`CLAUDE_CODE_USE_FOUNDRY=1`环境变量并配置 Azure 凭据
## 创建一个有缺陷的文件
本快速入门指南将引导您构建一个能够查找并修复代码错误的代理。首先，您需要一个包含一些故意设置的错误的文件，供代理修复。在指定目录`utils.py`中创建该文件`my-agent`，并将以下代码粘贴到其中：
```python theme={null}
def calculate_average(numbers):
total = 0
for num in numbers:
total += num
return total / len(numbers)
def get_user_name(user):
return user["name"].upper()
```
这段代码有两个错误：
1. `calculate_average([])`除以零时崩溃
2. `get_user_name(None)`崩溃并抛出 TypeError 异常
## 构建一个能够查找并修复漏洞的代理
`agent.py`如果您使用的是 Python SDK，请创建；如果您使用的`agent.ts`是 TypeScript，请创建：
```typescript TypeScript theme={null}
import { query } from "@anthropic-ai/claude-agent-sdk";
// Agentic loop: streams messages as Claude works
for await (const message of query({
prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options: {
allowedTools: ["Read", "Edit", "Glob"], // Tools Claude can use
permissionMode: "acceptEdits" // Auto-approve file edits
}
})) {
// Print human-readable output
if (message.type === "assistant" && message.message?.content) {
for (const block of message.message.content) {
if ("text" in block) {
console.log(block.text); // Claude's reasoning
} else if ("name" in block) {
console.log(`Tool: ${block.name}`); // Tool being called
}
}
} else if (message.type === "result") {
console.log(`Done: ${message.subtype}`); // Final result
}
}
```
这段代码主要由三部分组成：
1. **`query`**：创建代理循环的主要入口点。它返回一个异步迭代器，因此您可以使用它在 Claude 工作时传输消息。请参阅[Python](https://code.claude.com/docs/en/agent-sdk/python#query)或[TypeScript](https://code.claude.com/docs/en/agent-sdk/typescript#query)`async for` SDK 参考文档中的完整 API 。
2. **`prompt`**你想让克劳德做什么。克劳德会根据任务选择合适的工具。
3. **`options`**代理的配置。本示例使用`allowedTools``--pre-approve` `Read`、`--pre-approve` 和`Edit`` --auto-approve` 来预先批准文件更改。其他选项包括`--auto-approve` 、`--auto-approve` 等。查看[Python](https://code.claude.com/docs/en/agent-sdk/python#claudeagentoptions)或[TypeScript](https://code.claude.com/docs/en/agent-sdk/typescript#options)的所有选项。`Glob``permissionMode: "acceptEdits"``systemPrompt``mcpServers`
循环`async for`持续运行，克劳德会思考、调用工具、观察结果并决定下一步操作。每次迭代都会产生一条消息：克劳德的推理过程、工具调用、工具结果或最终结果。SDK 会处理所有编排工作（工具执行、上下文管理和重试），您只需使用数据流即可。当克劳德完成任务或遇到错误时，循环结束。
### 运行你的 agent
Your agent is ready. Run it with the following command:
```bash
npx tsx agent.ts
```
运行后，请检查`utils.py`。您会看到处理空列表和空用户的防御性代码。您的代理将自主执行以下操作：
1. **阅读** `utils.py`代码以了解其含义
2. **分析了**逻辑并识别出会导致崩溃的极端情况
3. **编辑**文件以添加适当的错误处理
这就是 Agent SDK 的不同之处：Claude 直接执行工具，而不是要求你实现它们。
> 如果看到“找不到 API 密钥”的提示，请确保已`ANTHROPIC_API_KEY`在配置`.env`文件或 shell 环境中设置了相应的环境变量。
### 尝试其他提示。
现在您的代理已设置完毕，请尝试一些不同的提示：
- `"Add docstrings to all functions in utils.py"`
- `"Add type hints to all functions in utils.py"`
- `"Create a README.md documenting the functions in utils.py"`
### 自定义 agent
您可以通过更改选项来修改代理的行为。以下是一些示例：
**添加网页搜索功能：**
```typescript TypeScript hidelines={1,-1} theme={null}
const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob", "WebSearch"],
permissionMode: "acceptEdits"
}
};
```
**给 Claude 一个自定义系统提示：**
```typescript TypeScript hidelines={1,-1} theme={null}
const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob"],
permissionMode: "acceptEdits",
systemPrompt: "You are a senior Python developer. Always follow PEP 8 style guidelines."
}
};
```
**在终端中运行命令：**
```typescript TypeScript hidelines={1,-1} theme={null}
const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob", "Bash"],
permissionMode: "acceptEdits"
}
};
```
启用此功能后`Bash`，请尝试：`"Write unit tests for utils.py, run them, and fix any failures"`
## 关键概念
**工具**控制着您的代理人可以执行的操作：
| 工具 Tools | agent 能做什么 |
| -------------------------------------- | -------------------------------------- |
| `Read`, `Glob`, `Grep` | Read-only analysis 只读分析 |
| `Read`, `Edit`, `Glob` | Analyze and modify code 分析和修改代码 |
| `Read`, `Edit`, `Bash`, `Glob`, `Grep` | Full automation 全自动 |
**权限模式**控制您希望接受多少人工监督：
| 模式 | 行为 | 用例 |
| :------------------------ | :------------------------------------------------- | :----------------------------- |
| `acceptEdits` | 自动批准文件编辑和常用文件系统命令，并询问其他操作 | 可信的开发工作流程 |
| `dontAsk` | 否认任何不在……范围内的事情`allowedTools` | 被封锁的无头特工 |
| `auto`（仅限 TypeScript） | 模型分类器批准或拒绝每次工具调用 | 具有安全防护措施的自主代理 |
| `bypassPermissions` | 所有工具均无需提示即可运行。 | 沙盒化持续集成，完全可信的环境 |
| `default` | 需要`canUseTool`回调函数来处理审批 | 自定义审批流程 |
上述示例使用了`acceptEdits`自动批准文件操作的模式，因此代理无需交互式提示即可运行。如果您希望提示用户批准，请使用`default`该模式并提供一个[`canUseTool`回调函数](https://code.claude.com/docs/en/agent-sdk/user-input)来收集用户输入。有关更多控制选项，请参阅[“权限”部分](https://code.claude.com/docs/en/agent-sdk/permissions)。
## 故障排除
### `thinking.type.enabled`此模型不支持API 错误。
Claude Opus 4.7 已替换`thinking.type.enabled`为`thinking.type.adaptive`。选择时，旧版本的 Agent SDK 会出现以下 API 错误`claude-opus-4-7`：
```text theme={null}
API Error: 400 {"type":"invalid_request_error","message":"\"thinking.type.enabled\" is not supported for this model. Use \"thinking.type.adaptive\" and \"output_config.effort\" to control thinking behavior."}
```
升级到 Agent SDK v0.2.111 或更高版本以使用 Opus 4.7。