Claude Agent SDK 入門：是什麼、怎麼裝、第一個智能體（Python / TypeScript）

本文根據 Claude Code 官方文檔的 Agent SDK 部分整理，核對日期 2026-10-07。示例代碼基於官方快速開始改寫。

適用於誰

• 想在自己的 Python / Node.js 程序裏，嵌入一個能自己讀文件、改代碼、跑命令的 AI 智能體的開發者；
• 搜「claude agent sdk 教學」「claude code sdk 是什麼」「agent sdk python 使用」的人；
• 用過舊的 Claude Code SDK、需要遷移的人。

結論先說

1. Claude Agent SDK = 把 Claude Code 當成一個庫來用：它提供和 Claude Code 相同的內置工具（讀寫文件、執行命令、網頁搜尋）、智能體循環、上下文管理，以及權限、會話、Hooks、子代理、MCP、技能、插件，可以用 Python 或 TypeScript 編程控制。
2. 它就是以前的 Claude Code SDK，已經改名：npm 包 @anthropic-ai/claude-code → @anthropic-ai/claude-agent-sdk，Python 包 claude-code-sdk → claude-agent-sdk。
3. 要求 Node.js 18+ 或 Python 3.10+；SDK 包自帶 Claude Code 原生程序，大多數情況下不用另裝 Claude Code。
4. 認證用 Claude Console 的 API Key（ANTHROPIC_API_KEY），也支持 Bedrock、Vertex 等雲平台。官方明確：未經許可，第三方開發者不得在自己的產品裏提供 claude.ai 登入或使用訂閱的額度。
5. 和直接調 API 的區別：用 Client SDK 你要自己寫工具和循環；用 Agent SDK，Claude 直接執行內置工具，你只需要消費它輸出的消息流。

一、幾種「用代碼調 Claude」的方式怎麼選

想用 Python / TypeScript 之外的語言驅動同樣的智能體循環，官方建議以子進程方式運行 claude -p --output-format json，詳見本站《Claude Code headless 模式：用 claude -p 寫腳本和自動化》。

二、安裝

Python（pip）：

bash
mkdir my-agent && cd my-agent
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\Activate.ps1
pip install claude-agent-sdk

（也可以用 uv：uv init 後 uv add claude-agent-sdk。）

TypeScript：

bash
mkdir my-agent && cd my-agent
npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

官方注意事項：SDK 通過平台對應的包自帶 Claude Code 程序。如果 pip 裝的是源碼包而不是平台 wheel（比如 ARM64 Windows），或者 npm 安裝時跳過了可選依賴（如 npm ci --omit=optional），就沒有自帶程序，需要另外原生安裝 Claude Code。

三、設定 API Key

bash
export ANTHROPIC_API_KEY=你的API Key           # macOS / Linux
$env:ANTHROPIC_API_KEY = "你的API Key"         # Windows PowerShell

SDK 不會自動讀取 .env 文件，用 .env 的話要自己先加載（比如用 dotenv）。API Key 的獲取詳見本站《Claude API Key 怎麼獲取：Claude Console 創建密鑰、充值與用量查看》。

四、第一個智能體：自己找 bug、自己修

先準備一個有 bug 的文件 utils.py（官方示例）：

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

它有兩個問題：空列表會除以零；傳入 None 會報 TypeError。

新建 agent.py：

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

async def main():
    async for message in query(
        prompt="檢查 utils.py 裏會導致崩潰的 bug，並把它們修好。",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],   # 這些工具自動批准
            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"調用工具：{block.name}")
        elif isinstance(message, ResultMessage):
            print(f"完成：{message.subtype}")

asyncio.run(main())

運行 python agent.py。它會打印自己的思路和每次調用的工具，最後輸出 完成：success。再打開 utils.py，會看到已經加上了處理空列表和空用戶的防禦代碼——整個過程 Claude 自己讀文件、分析、改文件，你沒有寫任何工具實現。

TypeScript 版本（agent.ts，用 npx tsx agent.ts 運行）：

typescript
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "檢查 utils.py 裏會導致崩潰的 bug，並把它們修好。",
  options: {
    allowedTools: ["Read", "Edit", "Glob"],
    permissionMode: "acceptEdits",
  },
})) {
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) console.log(block.text);
      else if ("name" in block) console.log(`調用工具：${block.name}`);
    }
  } else if (message.type === "result") {
    console.log(`完成：${message.subtype}`);
  }
}

代碼的三個部分：

• query：主入口，創建智能體循環，返回一個異步迭代器，Claude 思考、調用工具、觀察結果的過程會逐條流出來；
• prompt：你要它做的事，它自己決定用哪些工具；
• options：配置，如允許的工具、權限模式、系統提示詞、MCP 伺服器等。

五、常用配置

給它更多能力：

加上 WebSearch 就能聯網搜尋；加上 Bash 後可以試試「給 utils.py 寫單元測試、運行並修復失敗」。

自定義系統提示詞：

python
options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="你是一名資深 Python 開發者，始終遵循 PEP 8 規範。",
)

權限：權限模式（如 acceptEdits、plan、dontAsk 等）和 allow / deny 規則一起按固定順序判定，規則和 Claude Code 一致，詳見官方 Agent SDK 的 Permissions 頁。給智能體執行命令的權限時要謹慎，生產環境建議在容器等隔離環境中運行（官方有專門的 Hosting 和安全部署文檔）。

會話、Hooks、子代理、MCP：SDK 都支持，並且預設會像 Claude Code 一樣加載項目 .claude/ 和 ~/.claude/ 裏的技能、命令和記憶。

六、從 Claude Code SDK 遷移

步驟：卸載舊包、安裝新包、把 import 改成新包名。官方提醒 v0.1.0 起有一些不兼容改動，例如 Python 的 ClaudeCodeOptions 改名為 ClaudeAgentOptions，遷移前請看官方遷移指南的 Breaking changes 一節。

七、品牌與條款（做產品時注意）

• Agent SDK 的使用受 Anthropic《商業服務條款》約束，包括你用它給自己客戶提供產品和服務時；
• 你的產品可以叫「Claude Agent」或「XX Powered by Claude」，但不能叫「Claude Code」，也不能模仿 Claude Code 的視覺元素，產品要保持自己的品牌。

常見問題

Q：報「Not logged in」或「Invalid API key」？

確認在運行智能體的那個終端裏設定了 ANTHROPIC_API_KEY；SDK 不會自動讀 .env。

Q：能用我的 Claude Pro / Max 訂閱額度跑 SDK 嗎？

官方說明未經事先批准，第三方開發者不得在其產品中提供 claude.ai 登入或訂閱額度，SDK 應使用 API Key 認證。

Q：Agent SDK 和 Tool Use 有什麼區別？

Tool Use 是 API 層面的能力，工具要你自己實現和執行；Agent SDK 內置了一整套工具和循環，開箱即用。詳見本站《Claude Tool Use（工具調用 / Function Calling）入門：定義工具與返回 tool_result》。

Q：有完整的示例項目嗎？

官方 GitHub 倉庫 anthropics/claude-agent-sdk-demos 提供了電郵助手、研究助手等示例。

參考資料

• Agent SDK overview（官方）：https://code.claude.com/docs/en/agent-sdk/overview
• Agent SDK Quickstart（官方）：https://code.claude.com/docs/en/agent-sdk/quickstart
• Migrate to Claude Agent SDK（官方）：https://code.claude.com/docs/en/agent-sdk/migration-guide
• Agent SDK Permissions（官方）：https://code.claude.com/docs/en/agent-sdk/permissions
• 示例項目（官方 GitHub）：https://github.com/anthropics/claude-agent-sdk-demos