Claude-Agent-SDK以编程方式构建AI代理使用Claude-Code的功能

zq
AI人工智能
2026-06-12
242热度
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

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 代理，它可以读取您的代码、查找错误并修复它们，所有这些都无需人工干预。

你的工作内容：

使用 Agent SDK 设置项目
创建一个包含一些错误代码的文件
运行一个代理程序，自动查找并修复错误。

先决条件

Node.js 18+或Python 3.10+
一个 Anthropic 账户 (在此注册)

设置

创建项目文件夹

mkdir my-agent && cd my-agent

对于您自己的项目，您可以从任何文件夹运行 SDK；默认情况下，它将可以访问该目录及其子目录中的文件。

安装 SDK

# 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 控制台获取 API 密钥，然后.env在项目目录中创建一个文件：

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，并将以下代码粘贴到其中：

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()

这段代码有两个错误：

calculate_average([])除以零时崩溃
get_user_name(None)崩溃并抛出 TypeError 异常

构建一个能够查找并修复漏洞的代理

agent.py如果您使用的是 Python SDK，请创建；如果您使用的agent.ts是 TypeScript，请创建：

  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
    }
  }

这段代码主要由三部分组成：

query：创建代理循环的主要入口点。它返回一个异步迭代器，因此您可以使用它在 Claude 工作时传输消息。请参阅Python或TypeScriptasync for SDK 参考文档中的完整 API 。
prompt你想让克劳德做什么。克劳德会根据任务选择合适的工具。
options代理的配置。本示例使用allowedTools``--pre-approve Read、--pre-approve 和Edit`` --auto-approve 来预先批准文件更改。其他选项包括--auto-approve 、--auto-approve 等。查看Python或TypeScript的所有选项。Glob``permissionMode: "acceptEdits"``systemPrompt``mcpServers

循环async for持续运行，克劳德会思考、调用工具、观察结果并决定下一步操作。每次迭代都会产生一条消息：克劳德的推理过程、工具调用、工具结果或最终结果。SDK 会处理所有编排工作（工具执行、上下文管理和重试），您只需使用数据流即可。当克劳德完成任务或遇到错误时，循环结束。

运行你的 agent

Your agent is ready. Run it with the following command:

npx tsx agent.ts

运行后，请检查utils.py。您会看到处理空列表和空用户的防御性代码。您的代理将自主执行以下操作：

阅读 utils.py代码以了解其含义
分析了逻辑并识别出会导致崩溃的极端情况
编辑文件以添加适当的错误处理

这就是 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

您可以通过更改选项来修改代理的行为。以下是一些示例：

添加网页搜索功能：

  const _ = {
    options: {
      allowedTools: ["Read", "Edit", "Glob", "WebSearch"],
      permissionMode: "acceptEdits"
    }
  };

给 Claude 一个自定义系统提示：

  const _ = {
    options: {
      allowedTools: ["Read", "Edit", "Glob"],
      permissionMode: "acceptEdits",
      systemPrompt: "You are a senior Python developer. Always follow PEP 8 style guidelines."
    }
  };

在终端中运行命令：

  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回调函数来收集用户输入。有关更多控制选项，请参阅“权限”部分。

故障排除

`thinking.type.enabled`此模型不支持API 错误。

Claude Opus 4.7 已替换thinking.type.enabled为thinking.type.adaptive。选择时，旧版本的 Agent SDK 会出现以下 API 错误claude-opus-4-7：

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。