快速開始

使用 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():
    # 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"],  # Tools Claude can use
            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())

此程式碼有三個主要部分：

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 完成任務或遇到錯誤時，迴圈結束。

迴圈內的訊息處理會篩選出人類可讀的輸出。如果不進行篩選，你會看到原始訊息物件，包括系統初始化和內部狀態，這對除錯很有用，但通常會很冗長。

執行你的代理

你的代理已準備好。使用以下命令執行它：

python3 agent.py

執行後，檢查 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
• 範例代理：查看完整範例：電子郵件助手、研究代理等