Agent SDKの基礎

このレッスンで学ぶこと

• Agent SDKとは何か、Claude Code CLIとの違い・関係性を理解する
• TypeScript / Pythonそれぞれの環境でAgent SDKをインストールし、基本構成を整える
• 最小構成のエージェント（Hello World的なサンプル）を実際に動かす
• 実行結果の確認方法と、つまずいたときの基本的なデバッグ手順を身につける

前提条件

• 入門コース Lesson 1〜3を修了し、Claude Code CLIの基本操作に慣れていること
• Node.js（TypeScriptの場合）またはPython 3.10以上（Pythonの場合）がインストールされていること
• 応用コース Lesson 7（サブエージェント）を読んでいると、後半の理解がスムーズです

Agent SDKとは何か

これまでのレッスンで使ってきたClaude Codeは、ターミナルで対話的に操作するCLIツールでした。一方Agent SDKは、Claude Codeを支えているのと同じエージェントループ・ツール実行・コンテキスト管理の仕組みを、プログラムから呼び出せるライブラリとして提供するものです。

つまり、「Claude Codeというアプリケーションを使う」のではなく、「Claude Codeを動かしているエンジンを自分のコードに組み込む」というのがAgent SDKの位置づけです。TypeScriptとPythonの両方で提供されています。

graph TD
    subgraph "共通基盤"
        E["エージェントループ<br/>ツール実行・コンテキスト管理"]
    end
 
    CLI["Claude Code CLI<br/>（ターミナルで対話的に操作）"]
    SDK["Agent SDK<br/>（コードからプログラム的に呼び出す）"]
 
    E --> CLI
    E --> SDK
 
    style E fill:#e8f4fd,stroke:#1a73e8
    style CLI fill:#fff3e0,stroke:#e65100
    style SDK fill:#e8f5e9,stroke:#2e7d32

CLIとSDK、どちらを使うべきか

両者は対立する選択肢ではなく、用途によって使い分けるものです。

多くのチームは両方を併用します。日常の開発はCLIで行い、その過程で固まったワークフローをSDKでプログラム化して自動化する、という流れが自然です。実際、ワークフローの考え方そのもの（ツールへの権限付与、サブエージェントへの委譲など）はCLIとSDKの間でほぼそのまま通用します。

インストールと基本構成

TypeScriptとPython、どちらの環境でも数分でセットアップできます。

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python（Python 3.10以上が必要）
pip install claude-agent-sdk

export ANTHROPIC_API_KEY=your-api-key

最小構成のサンプル: Hello Worldエージェント

まずは「カレントディレクトリのファイル一覧を確認する」だけの、最小構成のエージェントを動かしてみます。

# agent_hello.py
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
 
 
async def main():
    async for message in query(
        prompt="このディレクトリにどんなファイルがありますか？",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)
 
 
asyncio.run(main())

// agent-hello.ts
import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt: "このディレクトリにどんなファイルがありますか？",
  options: { allowedTools: ["Bash", "Glob"] }
})) {
  if ("result" in message) console.log(message.result);
}

ここで起きていることを分解すると、次のようになります。

1. query()にプロンプトと、許可するツール（allowed_tools / allowedTools）を渡す
2. SDKがエージェントループを内部で実行する。「ファイル一覧を見るにはBashかGlobが必要」とモデルが判断し、ツールを呼び出す
3. ツールの実行結果がモデルに返され、最終的な回答がまとまる
4. query()は処理の過程で発生する複数のmessageを順番に返す（ストリーミング）。最終結果を含むメッセージにresultが含まれる

allowed_toolsで許可していないツール（たとえばWriteやEdit）をモデルが使おうとした場合は拒否されます。これにより、「ファイルを読むだけのエージェント」「ファイルを書き換えられるエージェント」を明確に区別して構築できます。

少し発展させる: TODOコメントを集計するエージェント

実用に近づけた例として、コードベース内のTODOコメントを検索して要約するエージェントを見てみましょう。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
 
 
async def main():
    async for message in query(
        prompt="すべてのTODOコメントを探して要約を作成して",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
    ):
        if hasattr(message, "result"):
            print(message.result)
 
 
asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt: "すべてのTODOコメントを探して要約を作成して",
  options: { allowedTools: ["Read", "Glob", "Grep"] }
})) {
  if ("result" in message) console.log(message.result);
}

Bashを許可せずRead Glob Grepに絞っているため、このエージェントはファイルを検索・閲覧することしかできません。CLAUDE.mdの禁止事項にある「TODO/FIXMEを残したままコミットしない」という方針を、定期的にチェックする仕組みの土台としても応用できそうです。

実行・デバッグの基本

実行する

通常のスクリプトと同じように実行します。

python agent_hello.py

npx tsx agent-hello.ts

メッセージの種類を理解する

query()が返すmessageには複数の種類があり、最終結果以外にも、ツール呼び出しの過程を表すメッセージが含まれます。デバッグ時はすべてのメッセージを出力してみると、エージェントが何をしているかを追跡できます。

async for message in query(
    prompt="このディレクトリにどんなファイルがありますか？",
    options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
):
    print(type(message).__name__, message)  # すべてのメッセージ種別を出力

セッション開始時にはSystemMessage（subtypeが"init"のもの）が流れ、ここにセッションIDなど後続処理で使える情報が含まれます。最終的な結果はResultMessage相当のオブジェクトに含まれます。

よくあるつまずきポイント

Claude Code CLIの設定資産はそのまま使える

Agent SDKは、デフォルトでは作業ディレクトリの.claude/と~/.claude/から設定を読み込みます。つまり、これまでのレッスンで作成してきたCLAUDE.md・Skills・サブエージェントの定義は、SDK経由で動かすエージェントでもそのまま活用できます。

どのソースを読み込むかはsetting_sources（Python）/ settingSources（TypeScript）オプションで制限できます。たとえば「CLAUDE.mdは読み込みたいが個人のグローバル設定は無視したい」といった制御が可能です。

まとめ

このレッスンでは、Agent SDKがClaude Code CLIと同じエンジンをプログラムから扱うためのライブラリであることを理解し、TypeScript / Python両方での最小構成のエージェントを実際に動かしました。

• Agent SDKはCLIの代替ではなく、CI/CDや自社サービスへの組み込みなど「プログラムから呼び出したい」場面で使い分けるもの
• query()にプロンプトと許可ツールを渡すだけで、ツール実行ループを自分で実装せずにエージェントを動かせる
• allowed_tools / allowedToolsに許可されていないツールは拒否されるため、権限エラーの多くはここを確認すれば解決する
• CLAUDE.mdやSkillsなど、CLIで育てた設定資産はSDK経由のエージェントでもそのまま活用できる

最小構成のエージェントが動かせるようになったら、次はこれを実用的なツールとして拡張していきます。Lesson 9: Agent SDKでカスタムエージェントを構築するでは、独自ツールの定義、状態管理、エラーハンドリングを組み込んだ実践的なエージェントを作ります。