Claude Agent SDK 實戰

安裝 SDK、建立專案

先確認環境:Node.js 20+ 或 Bun 1.1+,TypeScript 5+。

mkdir my-agent && cd my-agent
npm init -y
npm install @anthropic-ai/claude-agent-sdk
npm install -D typescript tsx @types/node
npx tsc --init --target ES2022 --moduleResolution bundler --esModuleInterop true

設定 API 金鑰(SDK 會自動讀取 ANTHROPIC_API_KEY 環境變數):

echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

Python 用戶改裝:

pip install claude-agent-sdk        # 需要 Python 3.10+

本堂課以 TypeScript 為主,Python 的 API 介面幾乎一一對應,語法差異在每個程式碼範例後會補一行說明。

第一個 agent:Hello, 工具世界

建立 hello-agent.ts:

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

async function main() {
  const messages = query(
    "列出當前目錄下所有 .ts 檔案,然後告訴我總共有幾個",
    {
      cwd: process.cwd(),
      allowedTools: ["Bash", "Glob"],
      permissionMode: "dontAsk",
    }
  );

  for await (const message of messages) {
    // assistant 訊息:模型輸出(包含文字和工具呼叫)
    if (message.type === "assistant") {
      for (const block of message.message?.content ?? []) {
        if (block.type === "text" && block.text.trim()) {
          process.stdout.write(block.text);
        }
      }
    }
    // result 訊息:任務結束
    if (message.type === "result") {
      console.log(`\n\n[完成] subtype: ${message.subtype}`);
    }
  }
}

main().catch(console.error);

跑起來:

npx tsx hello-agent.ts

你會看到 agent 呼叫 Glob 找出 .ts 檔案、然後用自然語言回答你——整個工具呼叫的過程 SDK 全自動處理,你什麼都沒做。

訊息類型速查:assistant(模型輸出)、user(工具結果回填)、system(系統訊息)、result(任務結束,含 success 或 error subtype)。只需要關注 assistant.text 和 result.subtype 就能處理大多數場景。

Python 等效:把 query() 換成 async for message in query(...): 同樣邏輯。

認識內建工具全覽

SDK 開箱即用的工具(2026 年 7 月):

選工具的黃金原則:只開放任務真正需要的工具。開了 Bash 就等於給了 agent 一個 shell,確定你知道它會執行什麼指令再開放。Bash + Write 組合威力最強,也是最容易出事的組合。

幾個常見搭配的邏輯:

• 純讀取分析任務:只開 Read + Glob + Grep,model 不能改任何東西,風險最低
• 文件整理任務:開 Read + Write + Edit + Glob,不開 Bash,避免 agent 執行系統指令
• 程式碼生成任務:開 Read + Write + Edit + Bash,但用 PreToolUse hook 過濾危險 Bash 指令
• 研究任務:開 Read + WebSearch + WebFetch,不給寫檔權限,讓 agent 只輸出文字結果

每次增加一個新工具之前,都應該問自己:「這個工具讓 agent 多做了什麼?如果它亂用這個工具,最壞的情況是什麼?」這個思路和第 2 課的工具設計原則是同一件事——工具的邊界決定了 agent 的邊界。

Hooks 與權限控制

permissionMode 控制整體授權策略,allowedTools 列白名單,hooks 則讓你在每一次工具呼叫前後插入邏輯——這三層組合起來才是完整的權限架構。

permissionMode 速查:

"default"          → 標準模式,依 settings.json 規則決定是否需要確認
"acceptEdits"      → 自動同意所有檔案編輯(Read/Write/Edit),其他照預設
"dontAsk"          → 白名單外的工具直接拒絕,不詢問
"bypassPermissions"→ 跳過所有權限檢查(開發測試用,絕對不進生產)
"auto"             → 用分類模型自動評估每次工具呼叫是否允許

建立 hooks-demo.ts,展示 PreToolUse 過濾敏感檔案 + PostToolUse 寫稽核日誌:

import { query } from "@anthropic-ai/claude-agent-sdk";
import { appendFile } from "fs/promises";

async function main() {
  const SENSITIVE_PATTERN = /\.env|secret|credential|private_key/i;

  const messages = query("讀取專案所有設定檔並列出內容摘要", {
    cwd: process.cwd(),
    allowedTools: ["Read", "Glob", "Grep"],
    permissionMode: "dontAsk",
    hooks: {
      PreToolUse: [
        {
          // 攔截所有 Read 工具呼叫
          matcher: "Read",
          callback: async ({ tool_name, tool_input }) => {
            const filePath: string = tool_input.file_path ?? "";

            if (SENSITIVE_PATTERN.test(filePath)) {
              console.warn(`[BLOCKED] ${tool_name} 嘗試讀取敏感檔案: ${filePath}`);
              return {
                permissionDecision: "deny" as const,
                permissionDecisionReason: `安全限制:禁止讀取敏感檔案 ${filePath}`,
              };
            }

            return { permissionDecision: "allow" as const };
          },
        },
      ],
      PostToolUse: [
        {
          // 記錄所有工具使用到稽核日誌
          matcher: ".*",
          callback: async ({ tool_name, tool_input }) => {
            const timestamp = new Date().toISOString();
            const target = tool_input.file_path ?? tool_input.query ?? "";
            await appendFile(
              "agent-audit.log",
              `${timestamp}\t${tool_name}\t${target}\n`
            );
          },
        },
      ],
    },
  });

  for await (const message of messages) {
    if (message.type === "assistant") {
      for (const block of message.message?.content ?? []) {
        if (block.type === "text") process.stdout.write(block.text);
      }
    }
  }
}

main().catch(console.error);

PreToolUse 可以做的事:

• 回傳 permissionDecision: "deny" 阻止工具執行
• 回傳 permissionDecision: "allow" 放行
• 回傳 updatedInput 修改工具的輸入參數後再執行

PostToolUse 在工具已成功執行後觸發,input 同時包含 tool_input(送進去的參數)和 tool_response(工具回傳值),適合做日誌、監控、或把結果轉換成不同格式再送回 context。

實戰:自動整理專案文件的 agent

這個 agent 會:掃描任意專案目錄 → 分析結構與重要檔案 → 在根目錄產出 PROJECT_OVERVIEW.md。

建立 doc-organizer.ts:

import { query } from "@anthropic-ai/claude-agent-sdk";
import { appendFile } from "fs/promises";
import { resolve } from "path";

async function organizeProjectDocs(projectPath: string) {
  const absPath = resolve(projectPath);

  const prompt = `
你是一個專案文件整理助理,目標是讓任何新進開發者 5 分鐘內看懂這個專案。

請按照以下步驟完成任務(每步前先說明你要做什麼):

1. 用 Glob 列出根目錄的所有檔案(不含 node_modules、.git、dist)
2. 讀取 package.json 或 pyproject.toml 取得專案名稱與依賴
3. 找出所有現有的 .md 文件,列出它們的標題
4. 判斷哪些目錄是核心原始碼、哪些是測試、哪些是設定
5. 在專案根目錄寫入 PROJECT_OVERVIEW.md,結構如下:
   # {專案名稱} — 總覽

   ## 專案簡介
   (一段說明,從 package.json 或 README 提取)

   ## 目錄結構
   (文字版樹狀結構,只列兩層深度)

   ## 重要檔案速查
   | 檔案 | 用途 |
   (列出 10 個以內最重要的檔案)

   ## 開始開發
   (安裝指令、本機跑起來的指令,從 package.json scripts 提取)

   ## 文件索引
   (列出所有現有 .md 的連結與一行說明)

如果 PROJECT_OVERVIEW.md 已存在,請先讀取再決定是否更新,不要無腦覆寫。
`.trim();

  const messages = query(prompt, {
    cwd: absPath,
    model: "claude-opus-4-5",           // 複雜分析任務選 Opus
    allowedTools: ["Read", "Write", "Edit", "Glob", "Grep", "Bash"],
    permissionMode: "acceptEdits",       // 自動接受檔案寫入
    hooks: {
      PreToolUse: [
        {
          matcher: "Bash",
          callback: async ({ tool_input }) => {
            const cmd: string = tool_input.command ?? "";
            // 只允許唯讀 shell 指令,禁止 rm、curl、sudo 等
            const DANGEROUS = /\b(rm|rmdir|curl|wget|sudo|chmod|chown|dd|mkfs)\b/;
            if (DANGEROUS.test(cmd)) {
              console.warn(`[BLOCKED Bash] 指令包含危險操作: ${cmd}`);
              return {
                permissionDecision: "deny" as const,
                permissionDecisionReason: `不允許在文件整理任務中執行系統操作指令`,
              };
            }
            return { permissionDecision: "allow" as const };
          },
        },
      ],
      PostToolUse: [
        {
          matcher: "Write|Edit",
          callback: async ({ tool_input }) => {
            const path: string = tool_input.file_path ?? "";
            await appendFile(
              "doc-organizer-audit.log",
              `${new Date().toISOString()}\tWRITE\t${path}\n`
            );
            console.log(`  [已寫入] ${path}`);
          },
        },
      ],
    },
  });

  console.log(`\n開始整理專案文件:${absPath}\n${"─".repeat(50)}`);

  for await (const message of messages) {
    if (message.type === "assistant") {
      for (const block of message.message?.content ?? []) {
        if (block.type === "text" && block.text.trim()) {
          process.stdout.write(block.text);
        }
      }
    }
    if (message.type === "result") {
      if (message.subtype === "success") {
        console.log(`\n${"─".repeat(50)}\n任務完成!PROJECT_OVERVIEW.md 已更新。`);
      } else {
        console.error(`\n任務失敗:${message.subtype}`);
      }
    }
  }
}

// 從命令列參數取目錄路徑,預設當前目錄
const targetPath = process.argv[2] ?? ".";
organizeProjectDocs(targetPath).catch(console.error);

使用方式:

# 整理當前目錄
npx tsx doc-organizer.ts .

# 整理指定專案
npx tsx doc-organizer.ts /path/to/your-project

這個實戰展示了三個關鍵設計決策:

1. model 選 Opus:文件分析需要多步驟推理,Opus 在複雜任務上比 Sonnet 更可靠,成本換正確率值得。
2. acceptEdits + Bash 過濾:整個任務需要寫檔,用 acceptEdits 省掉反覆確認;但 Bash 指令用 hook 加白名單過濾,防止意外的系統操作。
3. 判斷再寫、不覆寫:prompt 明確要求 agent 先讀取現有文件再決定怎麼更新,避免反覆執行時每次都重寫一遍。