English ← MyDocs

文档索引

在此获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后再进一步探索。

快速入门

使用 Python 或 TypeScript Agent SDK 开始构建自主工作的 AI 智能体

使用 Agent SDK 构建一个 AI 智能体，它可以读取您的代码、查找 bug 并修复它们，全程无需手动干预。

您将要做的事情：

  1. 使用 Agent SDK 设置项目
  2. 创建一个包含一些有 bug 的代码的文件
  3. 运行一个自动查找并修复 bug 的智能体

前提条件

  • Node.js 18+ 或 Python 3.10+
  • Anthropic 账户（在此注册）

设置

  1. 创建项目文件夹

    为此快速入门创建一个新目录：

    mkdir my-agent && cd my-agent

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

  2. 安装 SDK

    为您的语言安装 Agent SDK 包：

    npm install @anthropic-ai/claude-agent-sdk

    uv Python 包管理器是一个快速的 Python 包管理器，自动处理虚拟环境：

    uv init && uv add claude-agent-sdk

    首先创建虚拟环境，然后安装：

    python3 -m venv .venv && source .venv/bin/activate
pip3 install claude-agent-sdk
    Note

    TypeScript SDK 作为可选依赖捆绑了适用于您平台的原生 Claude Code 二进制文件，因此您无需单独安装 Claude Code。

  3. 设置 API 密钥

    从 Claude Console 获取 API 密钥，然后在项目目录中创建 .env 文件：

    ANTHROPIC_API_KEY=your-api-key

    SDK 还支持通过第三方 API 提供商进行身份验证：

    • Amazon Bedrock：设置 CLAUDE_CODE_USE_BEDROCK=1 环境变量并配置 AWS 凭证
    • Claude Platform on AWS：设置 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 凭证

    详情请参阅 Bedrock、Claude Platform on AWS、Vertex AI 或 Azure AI Foundry 的设置指南。

    Note

    除非事先获得批准，否则 Anthropic 不允许第三方开发者为其产品提供 claude.ai 登录或速率限制，包括基于 Claude Agent SDK 构建的智能体。请改用本文档中描述的 API 密钥身份验证方法。

创建一个有 bug 的文件

此快速入门将引导您构建一个可以查找和修复代码中 bug 的智能体。首先，您需要一个包含一些故意 bug 的文件供智能体修复。在 my-agent 目录中创建 utils.py 并粘贴以下代码：

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

此代码有两个 bug：

  1. calculate_average([]) 会因除以零而崩溃
  2. get_user_name(None) 会因 TypeError 而崩溃

构建一个查找并修复 bug 的智能体

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

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage


async def main():
    # Agentic loop: streams messages as Claude works
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # Auto-approve these tools
            permission_mode="acceptEdits",  # Auto-approve file edits
        ),
    ):
        # Print human-readable output
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)  # Claude's reasoning
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")  # Tool being called
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")  # Final result


asyncio.run(main())

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"], // Auto-approve these tools
    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：创建智能体循环的主入口点。它返回一个异步迭代器，因此您使用 async for 在 Claude 工作时流式传输消息。完整 API 请参阅 Python 或 TypeScript SDK 参考。

  2. prompt：您希望 Claude 做什么。Claude 根据任务确定使用哪些工具。

  3. options：智能体的配置。此示例使用 allowedTools 预批准 Read、Edit 和 Glob，使用 permissionMode: "acceptEdits" 自动批准文件更改。其他选项包括 systemPrompt、mcpServers 等。有关所有选项，请参阅 Python 或 TypeScript。

async for 循环在 Claude 思考、调用工具、观察结果和决定下一步时持续运行。每次迭代生成一条消息：Claude 的推理、工具调用、工具结果或最终结果。SDK 处理编排（工具执行、上下文管理、重试），因此您只需消费流。循环在 Claude 完成任务或遇到错误时结束。

循环内的消息处理过滤了人类可读的输出。不过滤，您会看到原始消息对象，包括系统初始化和内部状态，这对调试有用但其他情况下很嘈杂。

Note

此示例使用流式传输来实时显示进度。如果您不需要实时输出（例如，对于后台作业或 CI 管道），您可以一次收集所有消息。详情请参阅流式传输与单轮模式。

运行您的智能体

您的智能体已准备就绪。使用以下命令运行它：

python3 agent.py

npx tsx agent.ts

运行后，检查 utils.py。您将看到处理空列表和空用户的防御性代码。您的智能体自主地：

  1. 读取 utils.py 以理解代码
  2. 分析逻辑并识别会导致崩溃的边缘情况
  3. 编辑文件以添加适当的错误处理

这就是 Agent SDK 的不同之处：Claude 直接执行工具，而不是要求您实现它们。

Note

如果您看到 "API key not found"，请确保您已在 .env 文件或 shell 环境中设置了 ANTHROPIC_API_KEY 环境变量。有关更多帮助，请参阅完整故障排除指南。

尝试其他提示

现在您的智能体已设置好了，尝试一些不同的提示：

  • "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"

自定义您的智能体

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

添加网页搜索功能：

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"], permission_mode="acceptEdits"
)

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

给 Claude 自定义系统提示：

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.",
)

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

在终端中运行命令：

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"], permission_mode="acceptEdits"
)

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

启用 Bash 后，尝试："Write unit tests for utils.py, run them, and fix any failures"

关键概念

工具控制智能体可以做什么：

工具智能体可以做什么
Read、Glob、Grep只读分析
Read、Edit、Glob分析和修改代码
Read、Edit、Bash、Glob、Grep完全自动化

权限模式控制您想要多少人工监督：

模式行为使用场景
acceptEdits自动批准文件编辑和常见文件系统命令，其他操作需要询问可信的开发工作流
dontAsk拒绝不在 allowedTools 中的任何内容锁定的无头智能体
auto（仅 TypeScript）模型分类器批准或拒绝每个工具调用带有安全护栏的自主智能体
bypassPermissions无需提示即可运行每个工具沙盒化的 CI、完全可信的环境
default需要 canUseTool 回调来处理审批自定义审批流程

上面的示例使用 acceptEdits 模式，自动批准文件操作，以便智能体无需交互提示即可运行。如果您想提示用户进行审批，请使用 default 模式并提供收集用户输入的 canUseTool 回调。有关更多控制，请参阅权限。

故障排除

API 错误 thinking.type.enabled is not supported for this model

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

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。

后续步骤

现在您已经创建了第一个智能体，了解如何扩展其功能并根据您的用例进行定制：

  • 权限：控制智能体可以做什么以及何时需要审批
  • 钩子：在工具调用前后运行自定义代码
  • 会话：构建维持上下文的多轮智能体
  • MCP 服务器：连接到数据库、浏览器、API 和其他外部系统
  • 托管：将智能体部署到 Docker、云和 CI/CD
  • 示例智能体：查看完整示例：邮件助手、研究智能体等