你雇了一個很聰明的實習生。他什麼都懂，但你得告訴他三件事：可以用哪些工具、什麼時候該停下來問你、最後要交出什麼。

Claude Agent SDK 做的事情差不多。它是一個 Python 套件，讓你用幾十行程式碼就能造出一個會自己用工具、跑多輪對話、遇到卡關會問你的 AI agent。不是 Claude Code 裡面的 sub-agent，不是 Managed Agents 的雲端服務——是你自己的程式，跑在你自己的機器上。

跟你已經知道的東西有什麼不同

先釐清三個容易搞混的名詞。

Claude API Tool Use 是最底層的能力。你呼叫一次 API、Claude 回你一個 tool call、你執行完把結果丟回去。一來一回，你自己管 loop。

Claude Code Sub-agents 是 Claude Code 裡面的功能。你在 Claude Code 的對話中啟動一個子任務，它在 Claude Code 的環境裡跑。你沒辦法把它搬到自己的應用程式裡。

Agent SDK 在中間。它幫你把「收到 tool call → 執行 → 丟回去 → 再問一次」這整個迴圈包起來了。你定義工具、設定目標、按下啟動，agent 自己跑到完。

用實習生的類比：API Tool Use 是你親手遞文件給實習生、看他做完、再遞下一份。Agent SDK 是你把一整疊文件丟到他桌上說「做完這些再跟我講」。

安裝

1
pip install anthropic-agent-sdk

需要 Python 3.10 以上。安裝完設定環境變數：

1
export ANTHROPIC_API_KEY="sk-ant-..."

第一個 Agent：檔案摘要助手

從最簡單的開始。這個 agent 能讀檔案、做摘要、寫結果：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
from anthropic_agent_sdk import Agent, Tool
import json

# 定義工具
read_file = Tool(
    name="read_file",
    description="讀取指定路徑的檔案內容",
    parameters={
        "type": "object",
        "properties": {
            "path": {"type": "string", "description": "檔案路徑"}
        },
        "required": ["path"]
    },
    handler=lambda params: open(params["path"]).read()
)

write_file = Tool(
    name="write_file",
    description="將內容寫入指定路徑",
    parameters={
        "type": "object",
        "properties": {
            "path": {"type": "string", "description": "檔案路徑"},
            "content": {"type": "string", "description": "寫入內容"}
        },
        "required": ["path", "content"]
    },
    handler=lambda params: (
        open(params["path"], "w").write(params["content"]),
        "寫入完成"
    )[1]
)

# 建立 agent
agent = Agent(
    model="claude-sonnet-4-6",
    tools=[read_file, write_file],
    system="你是一個檔案摘要助手。讀取使用者指定的檔案，用繁體中文寫一份 200 字以內的摘要，存到指定位置。"
)

# 跑一個任務
result = agent.run("請讀取 ./report.txt，摘要後存到 ./summary.md")
print(result.final_message)

這裡發生了什麼？agent.run() 啟動之後，SDK 自動跑一個迴圈：送 prompt 給 Claude → Claude 回 tool call → SDK 呼叫你定義的 handler → 把結果塞回 Claude → Claude 決定要繼續用工具還是給最終回覆。

你不用自己寫 while loop，不用自己追蹤 conversation history，不用自己判斷什麼時候該停。

加上人機互動

實習生遇到不確定的事情該怎麼辦？問你。Agent SDK 內建了 human-in-the-loop 機制：

1
2
3
4
5
6
7
8
9
from anthropic_agent_sdk import Agent, Tool, HumanConfirmation

agent = Agent(
    model="claude-sonnet-4-6",
    tools=[read_file, write_file],
    confirmation=HumanConfirmation(
        require_for=["write_file"]
    )
)

加了 HumanConfirmation 之後，agent 每次要呼叫 write_file 之前會暫停，在終端機印出它打算寫什麼、寫到哪裡，等你輸入 y 才繼續。讀取不需要確認，寫入需要——最小權限原則。

模型選擇策略

Agent SDK 支援所有 Claude 模型。怎麼選？

Haiku 4.5 適合高頻率、低複雜度的任務。分類、格式轉換、簡單的資料提取。成本是 Sonnet 的三分之一左右。

Sonnet 4.6 是甜蜜點。大部分 agent 任務用 Sonnet 就夠了——寫程式碼、分析文件、多步驟推理。

Opus 4.7 留給真正需要深度推理的場景。架構決策、複雜除錯、需要同時考慮很多約束條件的任務。

一個省錢的技巧：在 agent 的 system prompt 裡寫清楚任務邊界。描述越精確，模型就越少花 token 在「搞懂你到底要什麼」上面。

多 Agent 編排

當一個 agent 不夠用，你可以讓多個 agent 分工：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
from anthropic_agent_sdk import Agent, Orchestrator

researcher = Agent(
    model="claude-sonnet-4-6",
    tools=[web_search, read_url],
    system="你是研究員。搜尋使用者指定的主題，整理成結構化筆記。"
)

writer = Agent(
    model="claude-sonnet-4-6",
    tools=[write_file],
    system="你是技術寫手。根據研究筆記，寫一篇部落格文章。"
)

orchestrator = Orchestrator(
    agents={"researcher": researcher, "writer": writer},
    workflow=[
        {"agent": "researcher", "task": "搜尋 {topic} 的最新發展"},
        {"agent": "writer", "task": "根據研究結果寫一篇 1500 字的文章"}
    ]
)

result = orchestrator.run(variables={"topic": "WebMCP 開放標準"})

Orchestrator 按照 workflow 的順序執行。前一個 agent 的輸出自動變成下一個 agent 的輸入。

更複雜的場景可以用條件分支和平行執行，但大部分時候線性 workflow 就夠了。

六月十五號計費變動

這個很重要。

從六月十五號起，Agent SDK 的用量會從你的互動式配額中獨立出來。Pro 方案每月 $20 Agent SDK credit、Max 5x 每月 $100、Max 20x 每月 $200。

實際意義：你用 Agent SDK 跑背景任務不會再吃掉你在 Claude Code 裡面打字的配額。但 Agent SDK credit 用完就停，不會自動加購。

如果你正在考慮用 Agent SDK 做 CI/CD 自動化或排程任務，六月十五號之前先測好你的用量，確認月度 credit 夠不夠。

什麼時候該用 Agent SDK

該用的場景：你要建一個獨立的 AI 應用程式，跑在自己的伺服器或 CI 上，需要 Claude 自主使用工具完成任務。

不該用的場景：你只是想在 Claude Code 裡面加一個自訂指令——那用 Claude Code 的 custom agent（.claude/agents/ 目錄下的 markdown 檔案）就好了。不需要寫 Python。

也不該用的場景：你要一個 24/7 跑在雲端的 agent——那是 Managed Agents 的守備範圍，Anthropic 幫你管 infra。

用一句話區分：Agent SDK 是給「我要把 Claude 嵌進我的程式裡」的人。Claude Code custom agent 是給「我要在 Claude Code 裡面客製化」的人。Managed Agents 是給「我不想管 infra」的人。

安全注意事項

Agent SDK 讓你定義工具，工具的 handler 是你寫的 Python 函式。這代表 agent 能做的事情完全取決於你給它什麼工具。

幾個原則：

最小權限。如果 agent 只需要讀檔案，就不要給它寫檔案的工具。聽起來很基本，但 PocketOS 事件就是因為一個 token 的權限範圍太廣，agent 九秒刪光了 production 資料庫。

輸入驗證。你的 handler 函式要驗證 agent 傳進來的參數。特別是檔案路徑——不要讓 agent 讀到 /etc/passwd 或寫到系統目錄。

人類確認。任何不可逆的操作（刪除、發送、支付）都該加 HumanConfirmation。

從這裡出發

學完 Agent SDK 的基本用法之後，下一步有幾個方向：

如果你想讓 agent 存取外部服務（資料庫、API、Slack），去看 MCP Server 開發——你可以把 MCP server 當成 Agent SDK 的工具來源。

如果你想讓 agent 在雲端自動跑，去看 Managed Agents——它是 Agent SDK 的託管版，不用自己管伺服器。

如果你想讓多個 agent 協作做更複雜的任務，去看 Agent Teams 的設計模式——雖然那是 Claude Code 裡的功能，但編排邏輯可以移植到 Agent SDK 的 Orchestrator 裡。

參考來源：Agent SDK overview — Claude Code Docs
參考來源：claude-agent-sdk-python — GitHub
參考來源：Anthropic Splits Claude Subscriptions — DevToolPicks