Claude Agent SDK 入門：用 Python 寫出你自己的 AI 助理

每次要整理會議筆記，都得打開 Claude Code、打一樣的話、等它做完。做久了會想：能不能寫成一支程式，丟一個資料夾就自動整理好？Claude Agent SDK 就是用程式指揮 Claude 的工具。Claude Code 會的讀檔、搜尋、改檔，你都可以在 Python 裡叫它做。這篇寫一支 21 行的程式，把一整個資料夾的筆記整理成重點。

快速回答 Claude Agent SDK 是 Anthropic 的 Python／TypeScript 套件，讓你用程式呼叫跟 Claude Code 一樣的 AI 助理。Python 版用 pip install claude-agent-sdk 安裝（Python 3.10 以上），設好 ANTHROPIC_API_KEY，再呼叫 query()：用 allowed_tools 只給它讀檔、找檔、搜尋的工具，用 prompt 告訴它要整理什麼。2026-10-23 用 claude-agent-sdk 0.2.173 實測整理 3 個筆記檔，兩次分別約 US$0.20、US$0.10。

做完這篇，你會有

• 一支 Python 程式 summarize.py：丟一個資料夾，就產生內容摘要
• 知道怎麼限制它只能讀、不能改檔案
• 每次跑完看得到花了多少錢

開始之前要準備：

• Python 3.10 以上：在終端機輸入 python3 --version 確認
• 一把 Anthropic API 金鑰：到 Claude Console（console.anthropic.com）建立。金鑰只放在你自己的電腦，不要貼到程式碼、聊天或任何截圖裡
• 一個放了幾份筆記（.md 檔）的資料夾，這篇用 notes

步驟 1：安裝 SDK

開一個新資料夾，建立虛擬環境再安裝：

mkdir folder-helper && cd folder-helper
python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

Windows 的啟用指令是 .venv\Scripts\activate。

SDK 已經內建 Claude Code，不用另外安裝。

步驟 2：設定 API 金鑰

在同一個終端機輸入（把後面換成你自己的金鑰）：

export ANTHROPIC_API_KEY=你的金鑰

Windows PowerShell 是 $env:ANTHROPIC_API_KEY = "你的金鑰"。這樣設只在這個終端機視窗有效，關掉就要重設。

用 SDK 寫的程式，官方文件的設定方式是 API 金鑰，或 Amazon Bedrock 等雲端平台，費用另外計算。

步驟 3：寫 21 行程式

在資料夾裡建一個 summarize.py：

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

async def main(folder):
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],  # 只給讀的權限
        system_prompt="你是整理筆記的助理，用繁體中文回答，條列重點。",
        cwd=folder,
        max_turns=10,
    )
    prompt = "讀這個資料夾裡所有的 .md 檔，整理成：1. 已決定的事 2. 還沒決定的事 3. 誰要做什麼。"
    async for message in query(prompt=prompt, options=options):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)
        elif isinstance(message, ResultMessage):
            print(f"\n[完成] 狀態：{message.subtype}，花費：約 US${message.total_cost_usd:.4f}")

asyncio.run(main(sys.argv[1] if len(sys.argv) > 1 else "."))

query() 會一邊做一邊把訊息交回來。程式只印出它說的話（TextBlock），最後印出結果和花費（ResultMessage）。

步驟 4：丟一個資料夾給它

python summarize.py notes

它自己找到資料夾裡的三個檔案、全部讀完，再按你要的三段整理。最後一行的 success 代表順利做完。同一支程式實測跑了兩次，分別花了約 US$0.20 和 US$0.10，每次的寫法也會有點不同。

換你做

改 prompt 那一行，讓它做你常做的整理。例如：

• 「讀所有 .csv 的欄位名稱，告訴我每個檔案在記什麼」
• 「讀這個專案的程式碼，寫一份給新人的 README 草稿，印出來就好，不要存檔」

想讓它把結果存成檔案，要在 allowed_tools 加上 Write。先在測試資料夾試，確定沒問題再用在重要的資料夾。

常見卡關

• ModuleNotFoundError: No module named 'claude_agent_sdk'：先確認虛擬環境已啟用（提示字元前面有 (.venv)），再確認有在這個環境執行過 pip install claude-agent-sdk。
• 出現 Not logged in 或 Invalid API key：這個終端機視窗沒設 ANTHROPIC_API_KEY，或金鑰打錯。開新視窗要重設一次。
• 它說讀不到檔案：確認資料夾路徑對，cwd 指的是你丟進去的那個資料夾。
• 花費比預期高：檔案越多越大，它讀得越多。先拿少量檔案試，max_turns 也可以調小。

你做到了

• 裝好 Claude Agent SDK，設好 API 金鑰
• 寫出 21 行的 summarize.py，丟資料夾就產生摘要
• 用 allowed_tools 讓它只能讀不能改，每次跑完看得到花費

常見問題

SDK 和 Claude Code 有什麼不同？

用的是同一套 AI 助理和工具。Claude Code 是你坐在終端機前一句一句跟它說；SDK 是把要做的事寫進程式，像這篇的 summarize.py，之後執行程式、指定資料夾就好。

可以用我的 Claude Pro 或 Max 訂閱嗎？

官方文件的設定方式是 Anthropic API 金鑰，或 Amazon Bedrock 等雲端平台，沒有教用訂閱登入。文件也寫明：除非先取得 Anthropic 同意，用 SDK 做給別人用的產品，不能讓使用者用 claude.ai 帳號登入。

有 TypeScript 版嗎？

有。官方同時提供 Python 和 TypeScript 套件，TypeScript 版用 npm install @anthropic-ai/claude-agent-sdk 安裝，需要 Node.js 18 以上。這篇只示範 Python 版。

下一步

• 讓 Claude Code 每天自己工作：排程教學：想讓它定時整理，可以從這篇開始。
• Claude Code Subagents 教學：組一支 AI 小隊，一個寫、一個審：用 allowed_tools 限制工具，跟 subagent 的 tools 是同一個概念。

參考資料

• Anthropic, Agent SDK overview（Claude Code 文件，SDK 與 Claude Code 的關係、內建工具、驗證方式、claude.ai 登入限制） https://code.claude.com/docs/en/agent-sdk/overview
• Anthropic, Quickstart（Claude Code 文件，Python 3.10 以上、pip install claude-agent-sdk、ANTHROPIC_API_KEY、allowed_tools、permission_mode、疑難排解） https://code.claude.com/docs/en/agent-sdk/quickstart
• Anthropic, Agent SDK reference - Python（Claude Code 文件，query()、ClaudeAgentOptions、AssistantMessage、TextBlock、ResultMessage） https://code.claude.com/docs/en/agent-sdk/python