Skip to main content
Agent SDK は、Claude Code を支える同じツール、エージェントループ、およびコンテキスト管理を提供します。スクリプトと CI/CD 用の CLI として、または完全なプログラムによる制御のための Python および TypeScript パッケージとして利用できます。 Claude Code を非対話型モードで実行するには、プロンプトと任意の CLI オプション を指定して -p を渡します。
このページでは、CLI(claude -p)経由で Agent SDK を使用することについて説明しています。構造化された出力、ツール承認コールバック、およびネイティブメッセージオブジェクトを備えた Python および TypeScript SDK パッケージについては、完全な Agent SDK ドキュメント を参照してください。

基本的な使用方法

任意の claude コマンドに -p(または --print)フラグを追加して、非対話的に実行します。すべての CLI オプション-p で機能します。以下を含みます。 この例は、コードベースについて Claude に質問し、応答を出力します。

ベアモードでより高速に開始する

--bare を追加して、hooks、skills、plugins、MCP サーバー、auto memory、および CLAUDE.md の自動検出をスキップすることで、起動時間を短縮します。これがない場合、claude -p は対話型セッションと同じ コンテキスト を読み込みます。これには、作業ディレクトリまたは ~/.claude で設定されたすべてのものが含まれます。 ベアモードは、すべてのマシンで同じ結果が必要な CI とスクリプトに役立ちます。チームメイトの ~/.claude のフック、またはプロジェクトの .mcp.json の MCP サーバーは実行されません。ベアモードはそれらを読み込まないためです。明示的に渡すフラグのみが有効になります。 この例は、ベアモードで 1 回限りの要約タスクを実行し、Read ツールを事前承認して、呼び出しが許可プロンプトなしで完了するようにします。
ベアモードでは、Claude は Bash、ファイル読み取り、およびファイル編集ツールにアクセスできます。フラグを使用して必要なコンテキストを渡します。 ベアモードは OAuth とキーチェーン読み取りをスキップします。Anthropic 認証は ANTHROPIC_API_KEY または --settings に渡される JSON の apiKeyHelper から取得する必要があります。Amazon Bedrock、Google Cloud の Agent Platform、および Microsoft Foundry は通常のプロバイダー認証情報を使用します。
--bare はスクリプトおよび SDK 呼び出しの推奨モードであり、将来のリリースで -p のデフォルトになります。

終了時のバックグラウンドタスク

Claude が claude -p 実行中に バックグラウンド Bash タスク を開始する場合(例えば、開発サーバーまたはウォッチビルド)、そのシェルは Claude が最終結果を返し、stdin が閉じられてから約 5 秒後に終了します。猶予期間により、結果の直後に終了するタスクでも出力を配信できます。v2.1.163 より前では、終了しないバックグラウンドプロセスは claude -p 呼び出しを無期限に開いたままにしていました。 バックグラウンド サブエージェント とワークフローは、その結果が最終出力の一部であるため、5 秒の猶予期間から除外されます。そのため claude -p はそれらが完了するまで待機します。v2.1.182 から、その待機はデフォルトで 10 分に制限されているため、スタックしたバックグラウンドエージェントがプロセスを無期限に開いたままにすることはできません。CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS で上限を調整するか、0 に設定して制限なく待機します。

これらの例は、一般的な CLI パターンを強調しています。CI およびその他のスクリプト呼び出しの場合は、--bare を追加して、ローカルで設定されているものを取得しないようにします。

Claude にデータをパイプする

非対話モードは stdin を読み取るため、他のコマンドラインツールと同様にデータをパイプして応答をリダイレクトできます。 この例は、ビルドログを Claude にパイプし、説明をファイルに書き込みます。
--output-format json を使用すると、応答ペイロードに total_cost_usd とモデルごとのコスト内訳が含まれるため、スクリプト呼び出し元は 使用状況ダッシュボード を参照せずに呼び出しごとの支出を追跡できます。
Claude Code v2.1.128 以降、パイプされた stdin は 10MB に制限されています。制限を超える場合、Claude Code は明確なエラーと 0 以外のステータスで終了します。より大きな入力を処理するには、コンテンツをファイルに書き込み、パイプする代わりにプロンプトでファイルパスを参照してください。

ビルドスクリプトに Claude を追加する

非対話呼び出しをスクリプトでラップして、Claude をプロジェクト固有のリンターまたはレビュアーとして使用できます。 この package.json スクリプトは、main に対する diff を Claude にパイプし、タイプミスを報告するよう要求します。diff をパイプすることで、Claude は読み取り権限を必要とせず、エスケープされたダブルクォートはスクリプトを Windows に対応させます。

構造化された出力を取得する

--output-format を使用して、応答がどのように返されるかを制御します。
  • text(デフォルト):プレーンテキスト出力
  • json:結果、セッション ID、およびメタデータを含む構造化 JSON
  • stream-json:リアルタイムストリーミング用の改行区切り JSON
この例は、セッションメタデータを含む JSON としてプロジェクト概要を返し、テキスト結果は result フィールドに含まれます。
特定のスキーマに準拠した出力を取得するには、--output-format json--json-schema および JSON Schema 定義と共に使用します。応答には、リクエストに関するメタデータ(セッション ID、使用状況など)が含まれ、構造化された出力は structured_output フィールドに含まれます。 この例は、auth.py から関数名を抽出し、文字列の配列として返します。
値が有効な JSON Schema でない場合、claudeError: --json-schema is not a valid JSON Schema で終了し、その後にバリデータの診断が続きます。Claude Code は format キーワード(例:"format": "email")を使用するスキーマを受け入れますが、format を注釈として扱い、強制しません。v2.1.205 より前では、Claude Code は無効なスキーマを黙って無視し、構造化されていないテキストを返し、format を含むスキーマを無効として扱いました。
jq などのツールを使用して応答を解析し、特定のフィールドを抽出します。

レスポンスをストリーミングする

--output-format stream-json--verbose および --include-partial-messages と共に使用して、生成されるトークンをリアルタイムで受け取ります。各行はイベントを表す JSON オブジェクトです。
ストリームの最後の行は、最終的な応答テキスト、コスト、およびセッションメタデータを含む result メッセージです。v2.1.208 より前では、大きな応答をパイプすると最後の行が切り詰められ、result メッセージが省略される可能性がありました。 次の例は、jq を使用してテキストデルタをフィルタリングし、ストリーミングテキストのみを表示します。-r フラグは生の文字列を出力し(引用符なし)、-j は改行なしで結合するため、トークンは継続的にストリーミングされます。
API リクエストが再試行可能なエラーで失敗すると、Claude Code は再試行前に system/api_retry イベントを発行します。これを使用して、再試行の進行状況を表示したり、カスタムバックオフロジックを実装したりできます。 system/init イベントは、モデル、ツール、MCP サーバー、および読み込まれたプラグインを含むセッションメタデータを報告します。これはスタートアップイベントが先行しない限り、ストリームの最初のイベントです。 イベントは、このバージョンの Claude Code が実装するプロトコル動作(例:interrupt_receipt_v1)の名前を付けるオプションの capabilities 文字列配列も含みます。バージョン文字列を比較する代わりに、機能検出に使用し、認識しない値は無視してください。このフィールドは Claude Code v2.1.205 以降が必要であり、以前のバージョンでは存在しません。機能リストについては、SDKSystemMessage を参照してください。 プラグインフィールドを使用して、プラグインが読み込まれなかった場合に CI を失敗させます。 CLAUDE_CODE_SYNC_PLUGIN_INSTALL が設定されている場合、Claude Code は最初のターンの前にマーケットプレイスプラグインがインストールされている間、system/plugin_install イベントを発行します。これらを使用して、独自の UI にインストール進行状況を表示します。 コールバックとメッセージオブジェクトを使用したプログラムによるストリーミングについては、Agent SDK ドキュメントの リアルタイムでレスポンスをストリーミングする を参照してください。

ツールを自動承認する

--allowedTools を使用して、Claude が確認を求めずに特定のツールを使用できるようにします。この例はテストスイートを実行し、失敗を修正し、Claude が許可を求めずに Bash コマンドを実行し、ファイルを読み取り/編集できるようにします。
セッション全体のベースラインを設定する代わりに個別のツールをリストするには、権限モード を渡します。dontAskpermissions.allow ルールまたは 読み取り専用コマンドセット にないものをすべて拒否します。これはロックダウンされた CI 実行に役立ちます。AskUserQuestion、組織が ask に設定したコネクタツール、および requiresUserInteraction とマークされた MCP ツールは、許可ルールが一致する場合でも拒否されます。 acceptEdits を使用すると、Claude はプロンプトなしでファイルを書き込むことができ、mkdirtouchmvcp などの一般的なファイルシステムコマンドも自動承認します。その他のシェルコマンドとネットワークリクエストは、--allowedTools エントリまたは permissions.allow ルールが必要です。そうでない場合、実行が試みられると実行が中止されます。

コミットを作成する

この例は、ステージされた変更を確認し、適切なメッセージを含むコミットを作成します。
--allowedTools フラグは パーミッションルール構文 を使用します。末尾の * はプレフィックスマッチングを有効にするため、Bash(git diff *)git diff で始まるすべてのコマンドを許可します。スペースは重要です。スペースがない場合、Bash(git diff*)git diff-index にも一致します。
ユーザーが呼び出した skills およびカスタムコマンドは -p モードで機能します。プロンプト文字列に /skill-name を含めると、Claude Code は実行前にそれを展開します。/login などの対話ダイアログを開く組み込みコマンドは、-p モードでは利用できません。/model/effort/fast/color、および /rename は値を引数として受け入れます。例えば /model sonnet のように、/mcp は引数なしでサーバーステータスのテキスト概要を出力します。これらの形式は Claude Code v2.1.205 以降が必要であり、各コマンドの 利用可能性に関する注記 に従います。-p 呼び出しから設定を変更するには、/configkey=value を渡します。例えば /config thinking=false です。

システムプロンプトをカスタマイズする

--append-system-prompt を使用して、Claude Code のデフォルト動作を保持しながら指示を追加します。この例は PR diff を Claude にパイプし、セキュリティ脆弱性をレビューするよう指示します。
デフォルトプロンプトを完全に置き換える --system-prompt を含む詳細なオプションについては、システムプロンプトフラグ を参照してください。

会話を続ける

--continue を使用して最新の会話を続けるか、--resume をセッション ID と共に使用して特定の会話を続けます。この例はレビューを実行し、その後フォローアッププロンプトを送信します。
複数の会話を実行している場合は、セッション ID をキャプチャして特定の会話を再開します。
同じディレクトリから両方のコマンドを実行します。セッション ID ルックアップは現在のプロジェクトディレクトリとその git worktrees にスコープされます。完全なスコープルールについては、セッションを再開する を参照してください。

次のステップ