官方 Claude Agent SDK：打造誠實、可稽核的個人 AI 助理（2026）
Anthropic 的 Claude Agent SDK 讓您在自己的 Python 或 TypeScript 應用中嵌入與 Claude Code 相同的工具迴圈。入門建議：先唯讀，加上強調誠實的 system_prompt（缺資料就說不知道、不捏造路徑或命令輸出），待稽核日誌無誤後再逐步放寬 allowed_tools。
延伸閱讀：Claude Code 經 SSH 使用、Cursor Rules 與 Skills 對比、Opus 4.8 Agent 基準測試。
為何從官方 SDK 起步
封裝層常隱藏實際執行的工具及外送資料。SDK 在 code.claude.com 上明確文件化 Read、Edit、Bash、permissions、hooks 與 sessions。
雲端 Mac 對 7×24 排程可選；搭建首個受控助手，筆電即可。
SDK 結構概覽
| 層級 | 作用 | 您可設定 |
|---|---|---|
query() | Agent 迴圈（計畫 → 工具 → 觀察） | agent.py |
| Tools | 檔案、Shell、搜尋、網頁 | allowed_tools |
| Permissions | 核准 / 拒絕 / 提示 | permission_mode |
| Policy | 誠實、範圍 | system_prompt、CLAUDE.md |
| Audit | 記錄工具使用 | hooks |
自 2026 年 6 月 15 日 起，訂閱方案透過獨立額度池計量 Agent SDK——請為無人值守迴圈預留預算。
八步受控操作手冊
步驟 1 — 前置條件
python3 --version # 3.10+
pip install claude-agent-sdk步驟 2–3 — 專案與安裝
mkdir my-guarded-agent && cd my-guarded-agent
python3 -m venv .venv && source .venv/bin/activate
pip install claude-agent-sdk步驟 4 — API 金鑰
# .env (gitignore this file)
ANTHROPIC_API_KEY=sk-ant-...步驟 5–6 — 誠實提示 + 唯讀執行
from claude_agent_sdk import query, ClaudeAgentOptions
HONEST = """Say "I don't know" when data is missing.
Never invent paths or command output."""
options = ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep"],
permission_mode="dontAsk",
system_prompt=HONEST,
)執行：python3 agent.py — 見 quickstart。
步驟 7–8 — 稽核 hook，再開放編輯
在啟用 Edit 且設定 permission_mode="acceptEdits" 之前，先為 PostToolUse 新增寫入 audit.log 的 hooks。可選：AskUserQuestion 用於釐清。
疑難排解
找不到 API 金鑰
修復：在同一 Shell 中 export ANTHROPIC_API_KEY；切勿提交 .env。
pip: No matching distribution
修復：使用 Python 3.10+；重建 .venv。
thinking.type.enabled not supported
修復：將 Agent SDK 升級至 v0.2.111+ 以支援 Opus 4.7+（[quickstart](https://code.claude.com/docs/en/agent-sdk/quickstart)）。
出現意外檔案編輯
修復：用 git 還原；在 hooks 證明安全前，恢復 dontAsk 與唯讀工具。
常見問題
query() 與 ClaudeAgentOptions 使用。dontAsk，且僅允許 Read、Glob、Grep。