快速入門

使用 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 工作時串流訊息。完整 API 請參閱 Python 或 TypeScript SDK 參考文件。

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 回呼 來收集使用者輸入。如需更多控制，請參閱權限。

後續步驟

現在您已經建立了第一個代理，了解如何擴展其功能並根據您的使用場景進行調整：

• 權限：控制您的代理可以做什麼以及何時需要批准
• Hooks：在工具呼叫前後執行自訂程式碼
• Sessions：建構維持上下文的多輪代理
• MCP 伺服器：連接到資料庫、瀏覽器、API 和其他外部系統
• 託管：將代理部署到 Docker、雲端和 CI/CD
• 範例代理：查看完整範例：電子郵件助理、研究代理等