この記事では、Windows環境のClaude Codeで実際に試した結果をもとにまとめています。

Agent SDKがTypeScriptに対応したことで、Claude Codeに自然文で頼むだけで自作AIエージェントを構築できる可能性が開けた。とはいえ「どこまで頼むだけで通るのか」「どこから自分で書く必要があるのか」の境界線は、実際に試してみないと見えない。Agent SDKのインストールからビルトインツール、カスタムツール、サブエージェント、Hooksまでを段階的に5ステップで試し、頼むだけでどこまでできたかをそのまま記録する。後半では従来のClient SDKとの違いも整理する。

前提——試す前に揃えておくもの

検証はWindows 11環境で行った。Node.js（LTS版）がインストール済みで、Anthropic APIキーが取得済みであることを前提とする。

APIキーの設定は環境変数で行う。コマンドプロンプトの場合は set ANTHROPIC_API_KEY=sk-ant-...、PowerShellの場合は $env:ANTHROPIC_API_KEY="sk-ant-..." を実行しておけば、同じターミナル内でAgent SDKが読み取れる。

Claude Codeをターミナルから自然文で操作する形で検証した。つまり、コマンドを打ち込むのではなく「〇〇を作って」「〇〇を追加して」と日本語で頼む使い方だ。Agent SDKと従来のClient SDKの違いは後半で整理するが、ざっくり言うとAgent SDKは自律ループを内蔵しており、query() を1回呼ぶだけでツールの選択から実行までを自動で進めてくれる。

Step 1: インストールから最初のquery()まで——頼むだけで動くか

まずは最小構成のエージェントを作らせるところから始める。次の依頼文をClaude Codeに投げた。

Node.jsのTypeScriptプロジェクトを新規作成して、@anthropic-ai/claude-agent-sdk をインストールし、最小構成のエージェントを作って。query()を1回呼んで「Hello from Agent SDK」と返すだけのものでいい。Windows 11環境で動かす前提で作って。

依頼文にはOSと目的を書き添えた。Agent SDKの情報にはTypeScriptとPythonの両方が混在しているため、環境を明示しておくと不要な手順が減る。

結果として、package.json、tsconfig.json、エントリポイントの index.ts が生成された。query() メソッドにプロンプトを渡す最小構成で、型定義も一通り揃っていた。

良かった点は、依頼だけで基本構成が出たこと。npm init から npm install、TypeScript設定までを一気に済ませてくれた。一方で、APIキーの設定方法には言及がなかった。環境変数の名前が間違っていた場合は実行時にエラーになるため、ここは人が確認する必要があった。

このStepで人が確認したポイント: package.json の依存関係が正しいか、tsconfig.json の module 設定がNode.js向けになっているか。どちらも問題なかったが、TypeScriptに慣れていないと module の違い（ESMとCommonJS）に気づきにくい。

Step 2: ビルトインツールでどこまでできるか

次に、Agent SDKのビルトインツール（Read、Write、Edit、Bash、Glob、Grep等）を有効にして、ファイル操作をさせてみた。

今のエージェントにビルトインツールを追加して。Read、Write、Edit、Bash、Glob、Grepを使えるようにして。読み取り専用モードと読み書きモードを切り替えられるように、permission_modeで制御できる構成にして。

結果、TypeScriptでは allowedTools でツールを列挙し、permissionMode で権限を切り替える構成が出た。Python版の記事やサンプルでは allowed_tools / permission_mode と書かれるため、TypeScriptでは表記を取り違えないように確認が必要だった。読み取り専用エージェント（Read、Glob、Grepのみ許可）とフルアクセスエージェントの2パターンが提案された。

頼むだけでできたのは、ツールの列挙と権限の切り替え構成まで。ビルトインツールの名前と役割はSDK側で定義済みのため、指示通りに並べるだけで動く。

permissionMode の値は要確認だった。TypeScriptでは auto も使えるが、読み取り専用に近づけたい場合は allowedTools: ["Read", "Glob", "Grep"] と permissionMode: "dontAsk" の組み合わせが分かりやすい。allowed は permissionMode の値としては使わない方が安全だ。

ビルトインツールは予想以上に範囲が広い。ファイルの読み書き、検索、シェルコマンドの実行まで、依頼文でツール名を指定するだけで使えるようになる。ただし「どのツールを許可するか」の判断は人が行う必要がある。

Step 3: カスタムツール（インプロセスMCPサーバー）の定義

ビルトインツールだけでは足りない場合、独自のツールをMCPサーバーとしてインプロセス定義できる。具体的にどれくらい頼むだけで書けるかを試した。MCP（Model Context Protocol）は外部ツールと連携する仕組みで、MCPサーバーの追加で解説しているように、APIやデータベースとも接続可能だ。

カスタムツールを追加して。指定した都市の天気を返すツール（get_weather）と、四則演算を行うツール（calculate）を定義して。インプロセスMCPサーバーとして実装して。型安全に書いて。

結果、ツールのインターフェース定義、入力スキーマ、ハンドラ関数の骨組みが出た。TypeScriptではZodスキーマを使う形で、型推論が効く構成になっていた。get_weather の戻り値は { temperature: number, condition: string }、calculate は { result: number } という型定義も付いていた。

頼むだけでできた部分は、インターフェースとハンドラの骨組みまで。型定義も正確で、TypeScriptの型推論が効く形になっていた。

一方で、エッジケースのハンドリングには修正が必要だった。たとえば calculate にゼロ除算を渡したときの挙動や、get_weather に存在しない都市名を渡したときのエラー処理が抜けていた。これらは依頼文で明示的に指示すれば追加されたが、最初の案には含まれていない。プログラムのエラー修正でも同様に、Claude Codeはエラーメッセージから原因を特定するのに強いが、エッジケースの予測までは難しいことが分かっている。

カスタムツールの定義は、指示の具体性に依存する部分が大きい。「どんなエラーが起きそうか」まで含めて頼むと、出力が実務に近くなる。

Step 4: サブエージェントで並列作業させる

エージェント内でサブエージェントをspawnし、並列タスクを処理させる実験。サブエージェントの構成も頼むだけで設計できるかを確かめた。

サブエージェントを使った並列処理を追加して。メインエージェントが2つのサブエージェントをspawnして、それぞれに別のタスク（ファイルの検索とコードの静的解析）を割り当てて、結果をメインエージェントで統合する構成にして。

結果、spawnの基本構成は一発で出た。サブエージェントごとに異なる allowed_tools を設定し、メインエージェントで結果を統合する流れが提示された。これはエージェントチーム機能のTypeScript版と言える構造で、複数のAIエージェントが並列で別タスクを処理するアプローチだ。

頼むだけでできたのは、spawnの構成とタスクの振り分けまで。サブエージェント間でリソースが競合するケース（同じファイルに同時に書き込む等）への言及はなかった。

並列処理の設計は、指示の具体性に応じて品質が変わる。「このサブエージェントは読み取り専用で」「このサブエージェントは書き込み可能で」とレベルまで指定すると、権限の分離も含めて構成してくれる。ただし、spawnの数が増えると実行結果の検証が難しくなるため、並列数は少なめから始める方が安心だ。

Hooksの仕組みを使えば、このあたりの制御をさらに細かく調整できる。次で試す。

Step 5: Hooksでエージェントの振る舞いを制御

PreToolUseとPostToolUseのHookイベントを使って、ツール実行の前後に検証・ログ・ブロックを挟む仕組みを頼むだけで構築できるかの検証。ここは一番注意が必要なステップだ。

Hooksを追加して。PreToolUseでツールの実行前にログを出力し、書き込み系ツール（Write、Edit、Bash）の場合は一度ブロックする仕組みにして。確認フローが必要な場合は、Hookだけで完結させず、SDKの承認処理と組み合わせる前提で書いて。PostToolUseで実行結果をログに記録して。非同期で動く前提で書いて。

結果、Hookの定義自体は出た。PreToolUse でツール名を判定してブロックする関数、PostToolUse で結果をログに書き込む関数が提案された。

ただし、非同期処理の扱いに注意が必要だった。async 関数の戻り値の型が Promise で包まれていない箇所や、エラー時に reject されずに undefined を返す箇所があった。これらは実行時に無言で失敗する可能性がある。

非同期のエッジケース（タイムアウト、並列Hookの発火順序、エラー時のフォールバック）までは、頼むだけで網羅するのは難しかった。ここは必ず人が確認する必要がある。

このStepで必ず確認すべきポイント: Hook関数の戻り値が意図通りか、非同期エラーが適切に伝播するか。特に PreToolUse が undefined を返した場合の挙動は、SDKのバージョンによって扱いが異なる可能性がある。

Client SDKとAgent SDK——どう使い分けるか

従来のClient SDK（@anthropic-ai/sdk）とAgent SDK（@anthropic-ai/claude-agent-sdk）の違いを整理する。

Client SDKでは、ツールループを自前で実装する。client.messages.create() を呼び、レスポンスにツール呼び出しが含まれていれば自分で実行し、結果を再送する。このループを自分で回すため、柔軟性は高いが実装量が多い。

Agent SDKでは、query() を1回呼ぶだけでこのループが自動で回る。ツールの選択、実行、結果の再送までSDKが担う。シンプルだが、カスタマイズの境界がある——ループの途中で独自の分岐を挟みたい場合、Hooksやカスタムツールで間接的に制御することになる。

使い分けの目安としては、ツールループのカスタマイズを細かく制御したい場合はClient SDK、自律的に動かしたい場合はAgent SDKと言えそうだ。今回はAgent SDKを主ルートとして検証した理由は、Claude Codeに頼むだけで構築できる範囲を確かめるためだ。

どこまで頼むだけでできて、どこから人が書いたか

Step 1から5の検証を通じて、3段階で整理する。

比較的任せやすいのは、基本セットアップとビルトインツールの活用だ。インストール、TypeScript設定、query() の呼び出し、ツールの列挙と権限設定までは、依頼文にOSと目的を書けば一発で出た。

条件付きで使えるのは、カスタムツール定義とサブエージェント構成だ。どちらも指示の具体性に依存する。エッジケースのエラーハンドリングやリソース競合の考慮は、依頼文で明示的に指定しないと含まれない。「何が起きそうか」まで先回りして頼むと、出力の精度が上がる。

必ず確認すべきなのは、Hooksの非同期処理、エッジケースのエラーハンドリング、本番運用の安全性だ。特にHooksは、非同期関数の戻り値の型とエラー伝播が意図通りかを必ず確認する必要があった。

やり取りの回数は、セットアップが1回、各Stepが1〜2回（修正指示を含む）で、全体で6〜8回程度だった。依頼文に含めるべき情報は「OS」「目的」「制約条件（読み取り専用か等）」の3点。これらを書き添えると、Claude Codeの回答が実務に近くなる。

この検証の振り返り

依頼文のコツとして、目的とOSと制約を書き添えると出力が安定する、ということが分かった。たとえば「Windows 11で」「読み取り専用で」「エラーハンドリングも含めて」と付けるだけで、不要な手順が減り、出力が実務に近くなる。

修正指示のコツは、「何をどうしてほしいか」を具体的に書くこと。「ゼロ除算の処理を追加して」の方が「もっと丁寧にして」より確実に反映される。

Agent SDK x TypeScriptに向いているのは、Claude Codeの基本操作に慣れていて、次のステップとして自作エージェントに挑戦したい人だ。TypeScript自体が初めての場合は、先に言語の基礎に触れておいた方がスムーズに進められる。また、プロジェクトの設定ファイル（CLAUDE.md等）の使い分けはCLAUDE.mdとMEMORY.mdの違いで整理しているので、並行して確認すると理解が深まる。

一方で、Hooksの非同期処理やエッジケースの設計は、TypeScriptの非同期の知識が前提になる。このあたりは「頼むだけ」で完璧にするのは難しく、人の設計判断が入る余地として残る。

まとめ——骨組みは頼むだけで、合わない部分だけ直せばいい

Agent SDKをTypeScriptで使うと、インストールからビルトインツールの活用までは頼むだけで到達できる。カスタムツール定義やサブエージェント構成も、指示の具体性次第でかなりの部分を任せられた。ただしHooksの非同期処理やエッジケースのハンドリングでは、人の確認と修正が必要だった。

骨組みは短時間でできる。合わない部分だけ後から直せばいい。

読者が次にやることとして:
– 次に読む: Client SDK（@anthropic-ai/sdk）の公式ドキュメントで、ツールループの手動実装を理解する
– 次に試す: 依頼文に「Windows 11」「目的」「制約」を書き添えて、最小構成のエージェントを作ってみる
– 高度な設定: Hooksとサブエージェントを組み合わせて、複数タスクを並列処理するエージェントに挑戦する

環境やバージョンによっては、今後さらに進められる可能性がある。

今回の結果は、利用モデル、接続先、時期、環境によって変わる可能性があります。再現する時は検証条件もあわせて確認してください。