自分のプロダクトやバッチ処理にエージェントを組み込むと決めたとき、最初に書くべきものはエージェントループではありません。Claude Codeを動かしている中身——モデルを呼び、ツールを実行し、結果を見てまた考えるループ——は、Claude Agent SDKというライブラリとして切り出されていて、自分のコードからそのまま呼べます。先に判断軸を言い切ると、「Claude Codeで足りるうちはSDKは要らない。while文でツール呼び出しのループを自作し始めそうになった時が、SDKを検討するタイミング」です。
対象読者は、Claude Codeは日常的に使っていて、次は自分のアプリケーションや業務システムにエージェントを組み込みたい人。そして「Messages APIを直接叩くのと何が違うのか」を先に知ってから採用を決めたい人です。SDKそのものが初見でも追えるように、位置づけから順に整理します。
Claude Agent SDKとは——Claude Codeからの切り出し
Claude Agent SDKは、Anthropicが提供するエージェント構築用のライブラリです。もともとは「Claude Code SDK」という名前で、Claude Codeをスクリプトから呼ぶための仕組みでしたが、2025年9月末のClaude Sonnet 4.5リリースに合わせてClaude Agent SDKへ改名されました（Anthropicの発表）。
名前から「Code」が外れたのは、位置づけの変化そのものです。Anthropicのエンジニアリングブログは、このSDKを「Claude Codeを支えているものと同じ基盤の上に、コーディング以外のエージェントも作るためのもの」として説明しています。ファイル操作もコマンド実行も検索も、考えてみればコーディング専用の能力ではありません。同じ部品でリサーチ用、事務処理用、運用自動化用のエージェントが組める、という整理です。
Anthropic公式：Building agents with the Claude Agent SDKHow to get started with the Claude Agent SDK and best practices for using it.claude.com
パッケージはTypeScriptとPythonの2つが提供されています。
- TypeScript:
@anthropic-ai/claude-agent-sdk（npm） - Python:
claude-agent-sdk（PyPI）
Messages APIとの違い——ループを書くか、借りるか
「エージェントを作る＝LLMのAPIを呼ぶコードを書く」と考えると、Messages APIを直接叩く選択肢がまず浮かびます。単発の生成・要約・抽出ならそれで十分です。違いが出るのは、モデルに道具を持たせて、結果を確認しながら何手も進ませたい場合です。
Messages APIでこれをやると、次を全部自分で実装することになります。
- ツールの定義と、ツール呼び出し要求を受けて実際に実行するディスパッチ処理
- 実行結果を会話履歴へ積み直して、もう一度モデルを呼ぶループ
- 会話が長くなったときのコンテキスト管理（要約・圧縮・切り捨ての判断）
- 「どのツールをどこまで実行させてよいか」の権限判断
- エラーやリトライ、コストと手数の上限
Claude Agent SDKは、この一式が最初から入っています。対応関係を並べるとこうなります。
| 自作ループで書くもの | Claude Agent SDKでは |
|---|---|
| ツール定義・実行のディスパッチ | Read / Write / Edit / Bash / Glob / Grep などが組み込み済み |
| ループと履歴管理 | query() が内部で回す |
| コンテキスト圧縮 | 自動のコンテキスト管理（コンパクション）が入っている |
| 外部サービス連携 | MCPサーバーをそのまま接続できる |
| 権限判断 | permissionMode・ツール許可リスト・フックで制御 |
| 停止条件 | ターン数上限などのオプションで指定 |
エンジニアリングブログはエージェントの基本形を「コンテキストを集める → 行動する → 結果を検証する → 繰り返す」というループとして説明しています。SDKを使う判断は、要するにこのループを自分で書いて保守するか、Claude Codeで毎日使われているものを借りるか、の選択です。
自前の業務ロジックをツールとして持たせたい場合も、ループ側を書き換えるのではなく、ツールをMCPサーバーの形で足します。SDKにはプロセス内でカスタムツールを定義してMCPサーバーとして渡す仕組みも用意されているので、「組み込みツール＋自社ツール」の構成が素直に作れます。自作MCPサーバーの作り方自体は別記事にまとめてあります。
TypeScriptの最小構成
実際のコードの形を見ます。インストールは1行です。
npm install @anthropic-ai/claude-agent-sdk
認証は環境変数 ANTHROPIC_API_KEY にAPIキーを設定するのが基本形で、課金はAnthropic APIの従量制です。最小のコードはこうなります。
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "src配下のTODOコメントを一覧にして、優先度の提案を付けてください",
options: {
cwd: "/path/to/project",
allowedTools: ["Read", "Glob", "Grep"],
maxTurns: 10,
},
})) {
if (message.type === "assistant") {
// モデルの応答（途中経過を含む）
}
if (message.type === "result") {
console.log(message.total_cost_usd); // このセッションで使った金額
}
}
query() は非同期ジェネレーターで、エージェントの動きがメッセージのストリームとして流れてきます。最初にセッション情報を持つsystemメッセージ、続いてモデルの応答やツール実行を反映したメッセージ、最後に結果のresultメッセージという流れです。resultには成否だけでなく、消費トークンやコストが含まれます。定時実行や多重起動を想定するなら、この値をログへ落として観測できる形にしておくのが実務上の要点です。
ハマりやすい注意点を先に2つ書いておきます。
- 既定では、Claude Codeの設定ファイル群を読みません。公式ドキュメントとSDKの移行ガイドに明記されている挙動で、CLAUDE.mdや
settings.jsonは、オプション（設定ソースの指定）で明示的に読み込ませない限り無視されます。「Claude Codeでは守られていた指示がSDKだと効かない」と感じたら、まずここを疑うのがよいはずです。 - 既定のシステムプロンプトはClaude Codeと同じではありません。Claude Codeと同等の振る舞いが欲しい場合は、オプションでClaude Code相当のプリセットを指定します。逆に言えば、素のSDKは「まっさらなエージェント基盤」から始まるということです。
どちらも不具合ではなく、「アプリに組み込むライブラリは、開発マシンのローカル設定に暗黙に依存すべきではない」という方向の設計だと理解しています。ただ、Claude Codeの感覚のまま移ると最初に戸惑う場所なので、入門の段階で知っておく価値があります。
書き始めると、主戦場はプロンプトではなく権限設計になる
ここまでの説明だと「ループを借りてプロンプトを書けば完成」に見えます。ところが構成を検討していくと、考える時間の大半を持っていくのはプロンプトではありません。どのツールを、どこまで、誰の確認なしに実行させるかという権限設計です。
理由は単純で、対話で使うClaude Codeには人間が同席しているからです。危ない操作の手前で確認が挟まり、画面の前の人が最終判断を下します。SDKで組み込んだエージェントには、その人間がいません。確認ダイアログに相当するものを出すのか、出さないなら何で代替するのかを、コードを書く側が決めることになります。
SDKにはそのための道具が一通りあります。
- permissionMode: 確認を求める既定の動きから、編集を自動承認するモード、計画だけ立てさせる読み取り専用寄りのモードまで、動作の基調を選べます
- ツールの許可・禁止リスト:
allowedTools/disallowedToolsで、そもそも持たせる道具を絞れます - ツール実行のフック・確認コールバック: ツール実行の前後へ自前の検査を差し込み、条件を満たさない呼び出しを弾けます
私の運用では、SNS運用の自動化パイプラインを無人で回すにあたって、都度の承認ボタンを置かない代わりに「許可の既定値・回数上限・検査の分離」を先に固める形を取りました。その設計判断はヒューマンインザループ設計の記事に書いた通りで、SDKで組み込みエージェントを作る場合も考えることは同じです。渡す道具を最小にし、破られたくない線はプロンプトではなく機械側に置く。Claude Code本体の権限の考え方は4層ガイドで整理しているので、SDKの許可リスト設計にもそのまま流用できます。
入門段階の実践的な指針としては、読み取り系ツールだけで動かし始めることです。上のコード例が Read / Glob / Grep だけを許可しているのはそのためで、まず観測・分析系のエージェントとして動かし、書き込みやBashは必要になった時点で、範囲を決めて1つずつ足していく。権限を後から絞るより、足していく方が事故になりません。
Claude Code・headlessモードとの使い分け
「自動化したい」だけなら、実はSDKの前に選択肢が2つあります。Claude CodeのCLIをそのまま使う方法と、claude -p の非対話実行（headlessモード）です。3つの守備範囲を並べます。
| 手段 | 起動のされ方 | 向いている場面 |
|---|---|---|
| Claude Code（対話） | 人がターミナルで使う | 開発作業そのもの。試行錯誤しながら進める仕事 |
claude -p（headless） | CI・cron・スクリプトから1回ずつ | 定型タスクの自動実行。既存のCLI運用に足す |
| Claude Agent SDK | 自分のアプリのコードから | プロダクトへの組み込み。独自UI・独自ツール・細かい制御が要る場合 |
境界線はこう考えると引きやすいはずです。成果物がそのタスクの出力だけならheadlessで足ります。エージェントの動作自体を自分のソフトウェアの一部として扱いたくなったら、SDKの領域です。たとえば途中経過を自社サービスの画面へ流す、実行のたびにセッションや権限をコードで組み立てる、複数のエージェントを自分のスケジューラーで束ねる、といった要件が出てきたら、シェルからCLIを叩く構成では細かい制御が難しくなってきます。
Claude Codeヘッドレスモード入門｜claude -p を自動化に組み込む設計Claude Codeを非対話で実行するヘッドレスモード（claude -p）の使い方を解説します。出力をJSONで受ける方法、許可ツールと権限モードの固定、max-turnsによる暴走と費用の上限設計、CI・cronへの組み込みパターンと向かない用途までをまとめます。www.tentspace.net
逆に、SDKを選ばない判断も明確にしておきます。単発のテキスト生成・分類・抽出のように、ツール実行のループが要らない処理は、Messages APIを直接呼ぶ方が依存も挙動もシンプルです。エージェントという形——道具を持って、複数手で、結果を確かめながら進む——が本当に必要かは、SDKを入れる前に一度疑う価値があります。
まとめ——最初の一歩
Claude Agent SDKは、Claude Codeの中身（エージェントループ・ツール・コンテキスト管理・権限制御）をライブラリとして使えるようにしたものです。入門の進み方を3段階にまとめます。
- 今の用途がCLIで済まないかを先に確認する。対話はClaude Code、定型実行は
claude -p。この2つで足りるうちはSDKを入れない - 最初のSDKコードは読み取り専用で書く。
query()にallowedTools: ["Read", "Glob", "Grep"]程度から始めて、resultメッセージのコストとターン数を観測する - 書き込み系を足す前に、権限の置き場を決める。許可リスト、permissionMode、実行前フックのどれで守るかを決めてから道具を増やす
エージェントのループは、もう自作するものではなく借りられるものになりました。そのぶん設計の重心は「何をさせるか」から「何をさせないか」へ移っています。組み込みを検討する段階になったら、プロンプトより先に権限の表を書く。これが、Claude Codeを日常的に使ってきた人がSDKへ進むときの、いちばん実務的な入り口だと考えています。