
Claude Code Agent SDKとは?CLIとの違いと選び方
Claude Code Agent SDKとは何か
Claude Code Agent SDKは、Claude Codeのエージェント機能をプログラムから呼び出すためのSDKです。
Claude Codeをターミナルで対話利用するCLIに対し、SDKはPythonまたはTypeScriptの処理へ組み込み、メッセージの受信、実行場所、権限、出力の扱いをアプリ側で制御できます。
完成状態は、リポジトリの調査依頼をNode.jsスクリプトから送信し、ファイルを変更させずに結果だけを標準出力へ受け取る構成です。
CLIを自動化するだけで足りる場面と、SDKで状態や出力を扱うべき場面を分けます。
対象は、macOS・Linux・WSL上でClaude Codeを使う開発者です。
ここではTypeScriptを例にします。
SDKはPythonも提供されています。
確認日: 2026-08-19。
パッケージ名や設定の既定値は更新されるため、導入前に公式リファレンスも確認してください。
SDKはClaude Codeと別のAI製品ではありません。
公式説明では、Claude Codeを支えるツール、エージェントループ、コンテキスト管理をプログラム可能にしたものです。
SDKパッケージには通常、実行環境向けのClaude Codeバイナリも同梱されます。
対話・自動化・組込みをこの表で選ぶ
最初に選ぶのは「どの画面で使うか」ではなく、実行のたびに人が判断するか、呼び出し元が結果を処理するかです。
小さな定型処理へSDKを持ち込むと、認証や出力処理の保守だけが増えます。
用途 選ぶ入口 向く状況 結果の受け取り方 対話 claude 調査中に追加質問や承認をする ターミナル画面 自動化 claude -p 1つの指示をCIやシェルから実行する テキストまたはJSON 組込み Agent SDK アプリ内でストリーム、権限、会話を制御する プログラム上のメッセージ
たとえば、毎晩1回だけログを要約し、結果をファイルへ保存するなら、まずはCLIのprint modeで十分です。
CLIは--output-format jsonも備えるため、後続処理へ渡せます。
一方で、利用者の入力に応じて進捗を表示したい、途中で処理を中断したい、許可する操作をサービス単位で変えたいならSDKを選びます。
対話を残す必要があるかと、出力をコードで分岐するかが判断基準です。
TypeScriptで読み取り専用から試す
外部公開や書き込みを含む処理は、最初から許可しません。
SDKの導入で重要なのは、実行先ディレクトリと権限を明示し、計画だけを返すモードで観察することです。
インストールと保存場所
ターミナルで、試したいNode.jsプロジェクトのルートへ移動して実行します。
npm install @anthropic-ai/claude-agent-sdk
次に、同じプロジェクト直下へagent.tsを保存します。
API認証などの接続設定は、利用する環境の公式手順に従ってください。
キーをソースコードやGitへ書かないことが事前確認ポイントです。
最小コード
import { query } from "@anthropic-ai/claude-agent-sdk";
async function main() {
// 現在のプロジェクトを調査対象にして、変更なしで計画を作る
for await (const message of query({
prompt: "このリポジトリの構成を確認し、テスト追加の計画だけを3点で示して",
options: {
cwd: process.cwd(),
permissionMode: "plan"
}
})) {
// 最終結果だけを標準出力へ表示する
if (message.type === "result") console.log(message.result);
}
}
// 失敗時は終了コードを異常として返す
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});
query()は結果を一括で返す関数ではなく、到着順のメッセージを読む非同期イテレータです。
画面へ進捗を出す、結果種別で保存先を変える、といった組込みはこのループ内に追加します。
出力を確認して次の判断をする
TypeScriptを実行できる設定で、プロジェクトルートからagent.tsを実行します。
成功すれば、リポジトリの調査に基づく計画文が表示され、ファイルの新規作成・編集・コマンド実行を促す確認は発生しない状態が期待結果です。
確認項目は次の3つです。
出力が対象リポジトリの内容に触れている。
cwdが意図した作業ディレクトリを指している。
Gitの差分が増えていない。
ここまで確認できたら、追加する機能は1つだけにします。
次は結果をJSONで自アプリの画面へ渡す処理です。
書き込みツールやBashの許可は、その後に個別の用途と戻し方を決めてから追加します。
失敗したときの戻し方
SDKはCLI設定を自動で再現するものではない点が、移行時の見落としです。
現行の移行ガイドでは、SDKはClaude Code向けシステムプロンプトやファイルシステム上の設定を既定で読み込まないため、必要な設定は明示する案内があります。
症状 【原因】 【解決策】 ネイティブCLIが見つからない 任意依存関係が省略された、または実行形式の配置が合わない 依存関係を入れ直し、必要なら公式リファレンスの実行形式パス設定を確認する。
| |CLIと回答や振る舞いが違う|CLAUDE.mdやシステムプロンプトをSDK側へ渡していない|必要な指示だけをoptionsへ明示し、差分を小さく検証する。
| |意図しない操作が心配|書き込み可能な権限モードを先に選んだ|permissionMode: "plan"へ戻し、対象操作ごとに許可を設計する。
|
設定を戻すときは、まずagent.tsの権限モードをplanへ戻し、追加したツール許可を外します。
認証情報に触れた疑いがある場合は、出力ログを共有せず、利用環境側で認証情報の状態を確認してください。
参考:
ここまで読んだあなたへ
ここまでで、考え方と最小構成は渡しました。
実際に配れる設定ファイル一式と、複合コマンドを分解して検査するHook、壊れたときの戻し方までは、別の記事へまとめています。
▼Claude Codeでdenyが効かない3つの原因と、止める設定