Claude Agent SDK 入門 — Python/TypeScript・MCP・hooks・subagents の実装境界を整理

Claude Agent SDK を触ってみたいが、Claude Code をそのままライブラリ化しただけなのか、自分でどこまで実装する必要があるのか分からない。MCP や hooks や subagents まで見えてくると、逆に入口がぼやけます。この記事は、そういう段階で止まっている人向けです。

先に位置づけを分けます。Claude Code 全体の導入順を知りたいなら Claude Code の使い方 実践ガイド、MCP の接続面を深掘りしたいなら Claude Code MCP ガイド、委譲設計を深掘りしたいなら Claude Code サブエージェント運用ガイド、ハーネス全体の考え方から整理したいなら Harness Engineering とは？ の方が先です。今回はそれらより一段実装寄りに絞り、Claude Agent SDK を自前アプリに組み込むときの境界だけを整理します。

先に結論: Claude Agent SDK は「CLI の代替」ではなく「Claude Code の agent loop を自分のプロセスで動かす部品」

2026年5月1日時点の公式 docs では、Claude Code SDK は Claude Agent SDK に改称されています。中身は単なる API wrapper ではなく、Claude Code を支える agent loop、tools、context management を Python / TypeScript から呼び出せる形にしたものです。

ここを誤解すると設計がずれます。私の理解では、選び分けはかなり単純です。

何をしたいか	向くもの
1回限りの調査や修正を手元でやる	Claude Code
既存アプリや CI に agent を埋め込む	Claude Agent SDK
sandbox や session 基盤ごとホストしたくない	Managed Agents

つまり Claude Agent SDK は、CLI で便利だったものを「毎回人が起動する道具」のまま使うためではなく、自社のアプリケーション、バッチ、内部ツール、CI/CD から再利用するための実装面です。

Claude Agent SDK で最初に理解すべき 3 つの違い

入門で最初に押さえるべき差分は、機能一覧より次の3つです。

1. tool loop を自分で書かなくてよい

通常の Messages API だけで agent を作ると、tool call を受けて、自分で tool を実行し、結果をまたモデルへ返すループを書く必要があります。Claude Agent SDK ではこの loop を SDK 側が持っています。Claude が tool を呼び、SDK が実行し、結果を戻し、次の判断へ進む流れが自動で回ります。

この差はかなり大きいです。単発の function calling なら自前 loop でもよいですが、ファイル読取、grep、編集、コマンド実行、MCP、subagent 委譲まで含めると、agent loop そのものがプロダクトになります。Claude Agent SDK はそこを最初から持っています。

2. built-in tools が最初からある

公式 docs では、SDK は Claude Code と同じ built-in tools を持ちます。代表例は次の通りです。

• Read / Edit / Write
• Glob / Grep
• Bash
• WebSearch / WebFetch
• Agent / Skill / AskUserQuestion / TodoWrite

つまり「外部 API は自前 tool、ローカル作業は全部自前実装」という発想ではありません。まず built-in tools でどこまで足りるかを見て、不足分だけ MCP や custom tools を足すのが正しい順番です。

3. agent は自分のプロセス、自分のインフラで動く

Managed Agents との一番大きな違いはここです。Claude Agent SDK はあなたのプロセス内で動き、ファイル、環境変数、ネットワーク、資格情報、MCP 接続先もあなたの側にあります。

便利ですが、同時に責任もこちらに戻ります。

• どの tool を許可するか
• どのファイルやコマンドを触らせるか
• どの外部 API に出してよいか
• 監査や approval をどこに置くか

ここを曖昧にすると、SDK 導入はただの「強い bot の埋め込み」で終わります。

最小構成は Python / TypeScript どちらでもほぼ同じ

公式 overview では、インストールはかなり単純です。

• TypeScript: npm install @anthropic-ai/claude-agent-sdk
• Python: pip install claude-agent-sdk

認証は ANTHROPIC_API_KEY が基本で、Bedrock / Vertex AI / Azure AI Foundry もサポートされています。逆に、claude.ai の consumer login をそのまま third-party product に流用する前提ではありません。ここは docs でも明示されています。

最小の発火イメージは次の程度です。

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

for await (const message of query({
  prompt: "List the files in this repository",
  options: {
    allowedTools: ["Glob", "Read"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="List the files in this repository",
        options=ClaudeAgentOptions(allowed_tools=["Glob", "Read"]),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

入門段階では、ここで派手な機能を足すより allowedTools を絞った read-only agent を先に作る 方が大事です。最初から Bash と Write まで開けると、SDK そのものの理解より permission 設計の事故が先に来ます。

まずは「どの境界を自前に持つか」を決める

Claude Agent SDK を触り始めると、MCP、hooks、custom tools、subagents、memory、skills、observability と機能が多く見えます。ただ、実務では全部を同時に設計しません。私は次の4境界を先に決めます。

1. 実行境界

• read-only で足りるか
• Bash を許可するか
• 書き込みはどのディレクトリまでか

2. 接続境界

• MCP で外部サービスへ出すか
• custom tool で自前 API を呼ぶか
• 認証情報は agent process から見えるか

3. 委譲境界

• 1体の agent で足りるか
• subagents で役割分担するか
• background 実行や team 化が必要か

4. 承認境界

• どこで human approval を挟むか
• hooks で block するか
• 監査ログをどこへ出すか

この順で考えると、SDK の機能を「便利そうだから積む」のではなく、どの責任を SDK に持たせるか で整理できます。

MCP は「後から足す拡張」ではなく、最初から permission 設計の一部

公式 docs では、MCP server はコード内の mcpServers でも .mcp.json でも追加できます。local process、HTTP、in-process server まで扱えます。さらに allowedTools で mcp__server__* のように許可範囲を絞れます。

ここで重要なのは、MCP は単なる plugin 機構ではないことです。MCP を足した瞬間、agent はローカル file tools だけでなく、GitHub、Slack、database、browser のような外部面へ到達できます。つまり MCP 追加 = 権限面の拡張 です。

私なら入門の最初はこうします。

1. built-in tools だけで 1 本動かす
2. 次に read-only MCP を 1 本だけ足す
3. allowedTools で wildcard を雑に広げない
4. write 系 MCP は別 session か別 agent に分ける

MCP 自体の選び分けや allowlist 設計は Claude Code MCP ガイド で詳しく書いたので、ここでは SDK 観点だけ押さえれば十分です。

custom tools は「SDK に足りない機能を生やす」のではなく「自社の判断基準を agent に公開する」もの

公式 docs の custom tools は、in-process MCP server を使って関数を tool 化する設計です。TypeScript は tool() と Zod schema、Python は @tool と型定義または JSON Schema で定義します。

ここでよくある誤解があります。custom tool は「外部 API を叩けるようにする」ためだけのものではありません。実務で強いのはむしろ、自社の判断ロジックを Claude に安全に見せる 使い方です。

たとえば私なら次の順で考えます。

• 料金計算ロジック
• 社内承認状態の参照
• feature flag の確認
• deploy 可否のポリシー判定

こういうものは、自然言語で system prompt に長く書くより、tool に切った方が再現性が高いです。Claude には「この tool を呼べば正しい判定が返る」と覚えさせる方が安定します。

hooks は「ログを取る仕組み」より「危険操作の直前で止める仕組み」として先に使う

公式 hooks docs では、PreToolUse、PostToolUse、PermissionRequest、SubagentStart、SubagentStop、Notification など多くのイベントが用意されています。用途としても、block、modify、approval、logging、notification が想定されています。

入門段階でまず効くのは PreToolUse です。理由は単純で、事故はだいたい tool 実行前に防げるからです。

私なら最初に次のどれかを置きます。

• destructive shell command を deny
• .env や secret file への書き込みを deny
• database write を human approval 必須にする
• 特定の API call だけ監査ログへ送る

逆に、最初から全イベントを計測して大規模な observability を作ろうとすると、入門としては重すぎます。hooks の最初の価値は analytics ではなく safety gate です。

subagents は「便利だから使う」のではなく「main agent の文脈を汚したくないときだけ使う」

Agent SDK の subagents は、Claude Code の subagent 機能をアプリ側でも使えるようにしたものです。公式 docs では、subagent は Agent tool 経由で呼ばれ、明示的な allowedTools、description、resume、agent definition の再指定などが重要だと整理されています。

ここも CLI と同じで、万能化すると失敗します。私の基準ははっきりしています。

subagents を使うケース

• 大量の調査ログを main agent に残したくない
• reviewer を read-only に切りたい
• test runner 役だけ Bash を持たせたい
• 並列で独立タスクを投げたい

使わないケース

• 1ファイル修正
• 仕様がまだ固まっていない
• 実装と再修正を短いループで往復したい

SDK でも、subagents は「速くする機能」というより コンテキスト分離と権限制御の機能 と見た方が事故が少ないです。委譲設計そのものは Claude Code サブエージェント運用ガイド で詳しく扱っています。

Managed Agents とどう分けるか

公式 overview では、Claude Agent SDK と Managed Agents の違いが明確に並んでいます。

• Agent SDK: 自分のプロセス、自分のインフラ、filesystem 上の session state
• Managed Agents: Anthropic 管理のインフラ、REST API、managed sandbox

私なら次のように分けます。

状況	私ならどちらを選ぶか
まず手元の repo や社内 service に組み込みたい	Agent SDK
ファイルやローカル tool を直接使いたい	Agent SDK
sandbox 運用を自前で持ちたくない	Managed Agents
長時間・非同期 session を SaaS として捌きたい	Managed Agents

実務では、Agent SDK でプロトタイプし、要件が固まってから Managed Agents を検討する 流れがかなり自然です。逆に、最初から Managed Agents を選ぶと、ローカル filesystem に近いユースケースは遠回りになります。

私ならこう始める: Claude Agent SDK 導入の最小 5 ステップ

最後に、入門段階での進め方を実務向けに固定しておきます。

1. read-only agent を 1 本作る

Read / Glob / Grep だけで repo 調査をさせます。ここで message stream と result の扱いに慣れます。

2. Bash を足して、テスト実行だけ許可する

ここで初めて execution が入ります。なんでも shell を開けるのではなく、対象コマンドを絞ります。

3. PreToolUse hook を 1 つ入れる

危険コマンドや secret file への書き込みを block します。SDK に safety gate を入れる感覚をここで掴みます。

4. read-only MCP か custom tool を 1 本足す

GitHub issue 読取、社内 docs 検索、料金計算など、業務価値が高いが write を伴わないものから始めます。

5. 必要なら reviewer subagent を追加する

main agent が実装、reviewer が read-only で検証、という分離が最初の成功パターンになりやすいです。

この順番なら、built-in tools、permissions、hooks、MCP、subagents を一気に学べます。しかも全部 read/write 境界を保ったまま進められます。

まとめ

Claude Agent SDK は、Claude Code をコードから呼ぶための薄い wrapper ではありません。Claude Code の agent loop を、自分のプロセスと自分の安全境界の中で動かすための実装部品です。

だから最初に見るべきは、機能の多さではなく境界です。allowedTools をどう絞るか、MCP をどこまで出すか、hooks で何を止めるか、subagents をどこで分けるか。ここが先に決まると、SDK はただのデモではなく、再利用できる社内 agent 基盤になります。

参考資料

• Agent SDK overview - Claude Docs
• How the agent loop works - Claude Docs
• Connect to external tools with MCP - Claude Docs
• Intercept and control agent behavior with hooks - Claude Docs
• Subagents in the SDK - Claude Docs
• Give Claude custom tools - Claude Docs