Claude Agent SDK 入門

Claude Agent SDK 讓你用程式啟動代理工作、接收訊息與處理結果。本篇使用 Node.js 與 JavaScript 建立一個只讀代理，讀取自己的 notes.txt 並列出待辦事項。成果是一個可執行程式、明確的時間與回合限制，以及成功和失敗分開的處理方式。

先理解非互動執行，準備 Node.js 22 以上與有效 API 認證。本篇建立獨立 sdk-todo 資料夾，不修改原待辦網站。SDK 套件、認證與設定載入方式依官方文件核對，訂閱登入不應直接被包裝成對外產品的共用認證。

SDK 與一般聊天 API 的差別

閱讀完整文字說明

Claude Agent SDK 入門，以流程和文件圖形呈現教學重點。

SDK 提供代理迴圈與工具執行，你的程式透過 query 送出任務並逐個接收訊息。一般模型回覆文字，與實際使用 Read 工具讀取磁碟檔案，是兩種不同的能力。這篇故意只提供讀取工具，方便觀察最小工作流程。

不要把 allowedTools 當成工具清單的限制欄位。它主要提供預先授權，而 tools 決定本例要提供哪些工具。正式服務還需要依工作權限、資料隔離與使用者身份設計授權，不能只靠提示寫「請安全操作」。

建立獨立程式目錄

mkdir sdk-todo
cd sdk-todo
npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk

保存 package-lock.json，記錄安裝版本，避免後續排錯時不知道實際使用哪版。新版套件在支援的平台通常包含 Claude Code 執行檔，但若安裝時跳過 optional dependencies 或平台套件不符，可能需要依官方文件另行指定原生執行檔。

建立 notes.txt，輸入三行假資料。不要把 API key 放在這個檔案，因為代理接下來就是要讀取它。也不要把真實秘密放在可分享的範例輸出中。

買牛奶
整理桌面
閱讀文件

在程序環境提供認證

在啟動 node 的同一個終端機設定 ANTHROPIC_API_KEY。SDK 不會自動載入 .env 檔；若你使用秘密管理工具，應由該工具注入環境。下面 PowerShell 範例避免把秘密直接寫進命令歷史，輸入後也不回顯內容。

$sdkSecret = Read-Host 'API key' -AsSecureString
$env:ANTHROPIC_API_KEY = [System.Net.NetworkCredential]::new('', $sdkSecret).Password

macOS 或 Linux 可使用自己的秘密管理工具，或在支援 read -s 的 Bash 中隱藏輸入。環境變數仍存在於程序環境，這只是避免顯示與歷史紀錄，不等於永久安全保存機制。

read -rs -p 'API key: ' ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY

建立只讀代理程式

import { query } from '@anthropic-ai/claude-agent-sdk';
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 60000);
let finished = false;
try {
  for await (const message of query({
    prompt: '請使用 Read 讀取 notes.txt，列出三個待辦事項。不得修改檔案；讀不到就明確回報。',
    options: {
      cwd: process.cwd(),
      tools: ['Read'],
      allowedTools: ['Read'],
      settingSources: [],
      maxTurns: 4,
      abortController: controller,
    },
  })) {
    if (message.type === 'assistant') {
      for (const block of message.message.content) {
        if (block.type === 'text') console.log(block.text);
        if (block.type === 'tool_use') console.log('Tool:', block.name);
      }
    }
    if (message.type === 'result') {
      finished = true;
      console.log('Result:', message.subtype);
      if (message.subtype !== 'success' || message.is_error) process.exitCode = 1;
    }
  }
  if (!finished) throw new Error('No final result received');
} catch (error) {
  console.error(String(error));
  process.exitCode = 1;
} finally {
  clearTimeout(timer);
}

settingSources 在本例明確使用空清單，不自動載入磁碟上的各層設定；若正式專案需要 CLAUDE.md 或專案設定，必須按 SDK 文件明確配置，不假設與互動 CLI 完全相同。maxTurns 限制工具回合，計時器則限制本程式等待時間，兩者不是同一種預算。

執行與核對結果

node agent.mjs

預期看到 Read 工具與三個真實待辦，再出現成功結果。重新開啟 notes.txt 確認內容沒有改變。只看到 Result: success 還要核對資料是否完整；程序成功退出不代表業務內容一定符合你的需求。

再把 notes.txt 暫時改名，重跑一次，應得到明確缺檔回報而不是捏造三個待辦。模型可能成功完成「回報缺檔」這個任務，所以應用程式若需要嚴格區分有資料與缺資料，下一步要加入結構化結果欄位與業務驗證。

處理失敗與停止

認證錯誤先確認環境變數在同一程序中存在，不要把值印出來。超時或回合用盡時，保存結果類型與必要訊息，調查原因後才調整限制。重試可能再次產生模型費用，也可能重複工具操作，不能無條件無限重跑。

目前範例只讀檔，容易重試；一旦加入寫檔或外部操作，就要設計重複執行的識別方式與結果保存。需要中止時可按 Ctrl+C，程式內則使用 AbortController；被中止的工作不能當成已收到完整結果。

正式程式通常還需要把任務狀態保存到可靠位置，例如開始、使用工具、收到最終結果與失敗原因。只在終端機印出文字適合練習，但程序中斷後無法靠記憶判斷哪些工作已完成。儲存紀錄時仍要過濾秘密與不必要的檔案內容。

本例的六十秒是示範限制，不是保證所有網路與模型工作都能在此時間內完成。若超時，先看程序是否已啟動、認證是否正常與 Read 是否回傳，再決定是否增加時間。增加限制之前先排除無限等待與錯誤重試。

當任務改為讀取多個檔案時，先在應用程式層決定允許的工作根目錄。Read 工具存在不代表你的服務可以讓任何使用者指定任意伺服器路徑；多使用者隔離需要另外設計與驗證。

小練習與交付紀錄

記錄 Node 與 SDK 版本、輸入檔、使用工具、結果類型與實際輸出。將三項待辦改為兩項，確認程式讀到新內容，再恢復原始材料。不要把套件成功安裝視為代理已完成操作。

完成判準是正常輸入能取得正確文字、缺檔不會被捏造、時間與回合有界限、檔案未修改。本篇範例依官方介面撰寫；真正的模型呼叫需要你自己的 API 認證，作者沒有代你執行付費請求。練習完成後移除不再需要的環境變數與測試金鑰。

回 Claude Code 教學總目錄

• AI 工具
• 教學
• Claude Code