快速入门

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

您将完成的内容：

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

前提条件

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

设置

创建一个有错误的文件

本快速入门将引导您构建一个能够查找和修复代码错误的智能体。首先，您需要一个包含一些故意错误的文件供智能体修复。在 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()

这段代码有两个错误：

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

构建一个查找和修复错误的智能体

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

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

async def main():
    # 智能体循环：在 Claude 工作时流式传输消息
    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"],  # Claude 可以使用的工具
            permission_mode="acceptEdits"            # 自动批准文件编辑
        )
    ):
        # 打印人类可读的输出
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)              # Claude 的推理
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")   # 正在调用的工具
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")      # 最终结果

asyncio.run(main())

这段代码有三个主要部分：

1. query：创建智能体循环的主入口点。它返回一个异步迭代器，因此您使用 async for 在 Claude 工作时流式传输消息。请参阅 Python 或 TypeScript SDK 参考中的完整 API。

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

3. options：智能体的配置。此示例使用 allowedTools 将 Claude 限制为 Read、Edit 和 Glob，并使用 permissionMode: "acceptEdits" 自动批准文件更改。其他选项包括 systemPrompt、mcpServers 等。查看 Python 或 TypeScript 的所有选项。

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

循环内的消息处理会过滤出人类可读的输出。如果不进行过滤，您会看到原始消息对象，包括系统初始化和内部状态，这对调试有用，但在其他情况下会产生噪音。

运行您的智能体

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

运行后，检查 utils.py。您会看到处理空列表和空用户的防御性代码。您的智能体自主完成了以下操作：

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

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

尝试其他提示

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

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

为 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."
)

在终端中运行命令：

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

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

关键概念

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

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

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

后续步骤

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

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