TypeScriptでClaude Agent SDKを始める

TypeScript版のAgent SDKは、Node.jsアプリからClaude Codeのエージェントループとツールを利用するためのライブラリです。公式Quickstartの現行パッケージは @anthropic-ai/claude-agent-sdk で、TypeScriptでは tsx とESモジュール設定を使う例が掲載されています。 Quickstart

最小構成

agent.tsのコードを、入力から結果の確認までつなげて読みます。

1. 1READMEとagent.ts練習資料と、Read・Globだけを使う処理を用意。
2. 2queryからメッセージfor awaitで回答や終了結果を受け取る。
3. 3結果と原文を比較回答内容、終了状態、読み取り対象を確認。

この小さな処理を確かめてから、独自ツールなどを一つずつ足します。

mkdir my-agent
cd my-agent
npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

agent.tsから query() を呼び、返ってくるメッセージを for await で処理します。まず「READMEを説明する」だけにし、ファイル編集やShellを許可しません。APIキーはプロセスの環境変数から読み込ませ、ソースや出力へ書きません。SDKには対応するClaude Codeバイナリの扱いがあるため、optional dependencyを省いたインストールでは別途確認が必要です。

読み取り用の資料を用意する

実行するフォルダーにREADME.mdが必要です。なければ、エディターで次の架空の練習資料を保存します。既存のREADMEがある場合は上書きせず、練習用の別フォルダーを使ってください。

# 練習用プロジェクト
目的：短い資料を読み、内容を整理する練習。
対象：このREADMEのみ。ファイルは変更しない。
完了条件：目的と対象が回答に正しく含まれている。

読み取り専用の最小コード

agent.tsを作り、ツールをReadとGlobに限定します。APIキーは実行前に安全な方法で ANTHROPIC_API_KEY 環境変数へ設定済みとします。

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

for await (const message of query({
  prompt: "README.mdを読み、要点を3つだけ説明して。ファイルを変更しないで。",
  options: {
    tools: ["Read", "Glob"],
    allowedTools: ["Read", "Glob"]
  }
})) {
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) console.log(block.text);
    }
  } else if (message.type === "result") {
    console.log(`result: ${message.subtype}`);
  }
}

PowerShellでは npx tsx agent.ts を実行します。出力、終了状態、読み取ったファイルを確認してから、編集ツールを追加します。

機能を一つずつ足す

ビルトインツールを追加するときは許可リストを狭くし、Custom Toolsは tool() とZodスキーマ、createSdkMcpServer()で定義します。サブエージェントは query() の agents オプションで専門タスクを分離できます。Hooksはライフサイクルの特定時点でコードを介入させる機能です。 Agent SDK概要

追加ごとに、正常系、拒否、タイムアウト、外部通信なし、入力不正をテストします。サブエージェントの並列化は速さの保証ではなく、競合するファイルを同時に編集しない設計が必要です。

Pythonとの選択はPython版、ツールの設計はCustom Tools、構造化結果はStructured Outputへ進んでください。

限界

公式例は導入の骨組みで、実運用の認証・監視・コスト・データ保護を完成させるものではありません。型が通っても、ツールの副作用と生成内容を人が確認します。

TypeScriptの型検査は入力の形を守る助けになりますが、モデルが選んだツールの妥当性までは判断しません。テスト用ディレクトリを作業場所にし、読み取り専用の許可から始めます。サブエージェントを使う場合は担当範囲と共有データを小さくし、同じファイルを並列に編集させません。Hooksでテストを自動実行する場合も、失敗時に処理を停止してログを残す設計にします。