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 Code は --bg を拒否し、タスク説明付きの --cloud を拒否します。競合を名前付きエラーで報告します。セッション ID 付きの --cloud-p は代わりに そのクラウドセッションにメッセージをキューイングして終了します-p と組み合わせることが多いオプションには以下が含まれます。 この例は、コードベースについて Claude に質問し、応答を出力します。
Claude Code は成功時にコード 0 で終了し、実行が失敗した場合は 0 以外のコードで終了するため、スクリプトは終了ステータスで分岐できます。無効なフラグを渡すと、Claude Code は実行開始前にエラーを stderr に報告します。実行内での失敗(認証の欠落など)が発生した場合、Claude Code は失敗を stdout の結果として出力します。

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

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

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

Claude が claude -p 実行中に バックグラウンド Bash タスク を開始する場合(例えば、開発サーバーまたはウォッチビルド)、そのシェルは Claude が最終結果を返し、stdin が閉じられてから約 5 秒後に終了します。猶予期間により、結果の直後に終了するタスクでも出力を配信できます。 Claude が サブエージェント またはワークフローをバックグラウンドで開始する場合、その結果が最終出力の一部であるため、claude -p は代わりにその作業が完了するまで開いたままになります。 デフォルトでは、待機は 10 分間の継続的なアイドル待機後に終了するため、スタックしたサブエージェントまたはワークフローがプロセスを無期限に開いたままにすることはできません。その時点で Claude Code は実行中のものをすべて停止し、その部分的な結果をドロップします。制限を変更するには、CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS を設定するか、0 に設定して制限なく待機します。 Claude が claude -p 実行中に Monitor ウォッチを開始する場合、Claude Code はウォッチがタイムアウトするか 10 分の上限がその待機を終了するまで、どちらか先に来た方まで待機します。待機中、Claude はウォッチが報告することに応答し続けます。デフォルトでは、ウォッチは Claude が開始してから 5 分後にタイムアウトします。

SIGTERM で実行を停止する

claude -p 実行を SIGTERM で停止する場合(例えば kill またはプロセススーパーバイザーから)、Claude Code はコード 143 で終了します。Claude Code は進行中のターンを未完了のままにし、そのための結果を記録しません。代わりにターンを終了するには、SIGINT を送信するか、Agent SDK の interrupt() を呼び出してから、プロセスを停止します。 SIGTERM では、Claude Code はまだ実行中の Bash コマンドのプロセスツリーを終了します。Claude Code は SessionEnd フック を実行して終了します。終了中、Claude Code は新しいツール呼び出しを開始せず、新しいモデルリクエストを送信せず、SessionEnd 以外のフックを実行しません。実行がコマンド実行中またはシグナル到着時に許可プロンプトへの回答を待機中だった場合、Claude Code はそのステップを以下のように処理します。
  • コマンド実行中: Claude Code はコマンドをセッションで killed として記録します。
  • 許可プロンプトへの回答を待機中: プロセスに SIGTERM を送信する場合、Claude Code はプロンプトを未回答のままにします。プログラムが Agent SDK を通じてセッションを閉じる場合、SDK はシグナルを送信する前に Claude Code の入力を終了し、Claude Code は入力が終了するとすぐにプロンプトをキャンセルします。
セッションを再開 する場合、Claude Code は SIGTERM が未完了のままにしたターンを続行します。

これらの例は、一般的な CLI パターンを強調しています。auth.pybuild-error.txt などのファイルを指定するコマンドの場合は、自分のプロジェクトのファイルに置き換えてください。CI またはその他のスクリプト環境では、--bare を追加して、Claude Code がホストの hooks、プラグイン、自動メモリ、または CLAUDE.md を読み込まずに起動するようにしてください。

Claude にデータをパイプする

非対話モードは stdin を読み取るため、他のコマンドラインツールと同様にデータをパイプして応答をリダイレクトできます。 この例は、ビルドログを Claude にパイプし、説明をファイルに書き込みます。
--output-format json を使用すると、応答ペイロードに total_cost_usd とモデルごとのコスト内訳が含まれるため、スクリプト呼び出し元は 使用状況ダッシュボード を参照せずに呼び出しごとの支出を追跡できます。両方の数値は クライアント側の推定値 であり、実際の請求額と異なる場合があります。
パイプされた stdin は 10MB に制限されています。制限を超える場合、Claude Code は明確なエラーと 0 以外のステータスで終了します。より大きな入力を処理するには、コンテンツをファイルに書き込み、パイプする代わりにプロンプトでファイルパスを参照してください。
Claude Code が stdin を読み取れない場合(例えば、それを開始したプロセスがその端を切断した場合)、Claude Code は stderr に警告を出力し、コマンドラインからのプロンプトで続行します。v2.1.211 より前では、Windows で読み取り不可能な stdin はセッションをクラッシュさせるか、出力なしで黙って終了していました。

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

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

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

--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 メッセージです。 コンシューマーがストリームをゆっくり読む場合、Claude Code はキューに入った出力がドレインされるのを待ってから終了し、まだキューに入っている量に応じて待機をスケーリングし、最大 30 秒でキャップされます。v2.1.214 より前では、終了待機は約 2 秒でキャップされており、大きな応答の最後が切り詰められる可能性がありました。 次の例は、jq を使用してテキストデルタをフィルタリングし、ストリーミングテキストのみを表示します。-r フラグは生の文字列を出力し(引用符なし)、-j は改行なしで結合するため、トークンは継続的にストリーミングされます。
プログラムによるストリーミングとコールバックおよびメッセージオブジェクトについては、Agent SDK ドキュメントの リアルタイムでレスポンスをストリーミングする を参照してください。

サブエージェントメッセージをフォローする

サブエージェント からのメッセージは、ストリームに assistant および user メッセージとして表示され、その parent_tool_use_id フィールドはサブエージェントを生成したツール呼び出しの ID です。メインの会話からのメッセージはそのフィールドに null を含みます。 フォアグラウンド で実行されているサブエージェントからの最初のメッセージは、それを駆動するプロンプトを含む user メッセージです。その最初のメッセージの後、Claude Code は以下を発行します。
  • デフォルトでは:サブエージェントの tool_use および tool_result ブロック。
  • --forward-subagent-text または CLAUDE_CODE_FORWARD_SUBAGENT_TEXT を使用する場合:サブエージェントのテキストおよび思考ブロックも含まれるため、各サブエージェントのトランスクリプトを再構築できます。これには Claude Code v2.1.211 以降が必要です。
いずれかのオプションを有効にすると、Claude Code は すべてのネストの深さのサブエージェント からのメッセージを転送します。サブエージェントが独自のサブエージェントを生成する場合、ネストされたサブエージェントのメッセージは、それを生成した Agent ツール呼び出しの ID を parent_tool_use_id に含むため、これらの ID をフォローして完全なネストツリーを再構築できます。v2.1.219 より前では、ネストされたサブエージェントからのメッセージはストリームに表示されませんでした。 サブエージェントで実行される スキルは、ストリームに同じ方法で表示されます。フォークされたスキルの最初のメッセージは、実行を駆動するスキルコンテンツを含む user メッセージです。いずれかのオプションを有効にすると、ストリームはフォークされたスキルのテキストおよび思考ブロックも含みます。v2.1.265 より前では、フォークされたスキルの tool_use および tool_result ブロックのみがストリームに表示されていました。

API 再試行を処理する

API リクエストが再試行可能なエラーで失敗すると、Claude Code は再試行前に system/api_retry イベントを発行します。v2.1.246 以降では、401 または 403apiKeyHelper 認証情報を拒否する場合、Claude Code は最初の 2 回の再試行を静かに行い、イベントなしで、3 番目の連続再試行からイベントを通常どおり発行します。静かな再試行は attempt にカウントされます。イベントを使用して、独自のインターフェースで再試行の進行状況を表示できます。

セッションメタデータを読み取る

system/init イベントは、モデル、ツール、MCP サーバー、および読み込まれたプラグインを含むセッションメタデータを報告します。これはスタートアップイベントが先行しない限り、ストリームの最初のイベントです。 イベントは、このバージョンの Claude Code が実装するプロトコル動作(例:interrupt_receipt_v1 または interrupt_cancel_queued_v1)の名前を付けるオプションの capabilities 文字列配列も含みます。バージョン文字列を比較する代わりに、機能検出に使用し、認識しない値は無視してください。このフィールドは Claude Code v2.1.205 以降が必要であり、以前のバージョンでは存在しません。機能リストについては、SDKSystemMessage を参照してください。

プラグインまたは MCP サーバーが読み込まれない場合に CI を失敗させる

system/init イベントのプラグインフィールドを使用して、読み込まれなかったプラグインをキャッチします。 MCP サーバーフィールドも同じ方法で使用します。--mcp-config-p で渡す場合、Claude Code は最初のターンを実行する前に、まだ保留中のサーバーを待機します。最大で MCP_TIMEOUT スタートアップタイムアウト(デフォルト 30 秒)まで待機します。キャッシュされたツールリスト を持つリモートサーバーは待機をスキップし、system/initpending を表示し、最初のツール呼び出しで接続します。待機には Claude Code v2.1.221 以降が必要です。 Claude Code は起動時に各 --mcp-config エントリを検証し、検証に失敗したエントリをスキップします。例えば、type のない url エントリです。実行は続行され、クリーンに終了するため、これらのフィールドをチェックして、読み込まれなかったサーバーをキャッチします。 コマンドを手でターミナルで実行する場合、Claude Code は stderr に起動警告も出力します。例えば Warning: 1 MCP server skipped due to invalid config: の後に、スキップされた各エントリの理由が続きます。stderr をリダイレクトする場合、または CI ランナーなどのプログラムがそれをキャプチャする場合、Claude Code は警告を出力せず、スキップされたエントリを mcp_server_errors フィールドでのみ報告します。警告には Claude Code v2.1.219 以降が必要です。

プラグインインストールを追跡する

CLAUDE_CODE_SYNC_PLUGIN_INSTALL が設定されている場合、Claude Code は最初のターンの前にマーケットプレイスプラグインがインストールされている間、system/plugin_install イベントを発行します。これらを使用して、独自の UI にインストール進行状況を表示します。

ツールを自動承認する

--allowedTools を使用して、Claude が確認を求めずに特定のツールを使用できるようにします。この例はテストスイートを実行し、失敗を修正し、Claude が許可を求めずに Bash コマンドを実行し、ファイルを読み取り/編集できるようにします。
セッション全体のベースラインを設定する代わりに個別のツールをリストするには、権限モード を渡します。-p の場合、組み込みの開始権限モード はすべてのプランで Manual であるため、希望する権限モードを渡します。
  • auto--permission-mode auto を渡して、ほとんどのアクションをあなたの代わりに分類器にレビューさせます
  • dontAsk:Claude Code はプロンプトが表示されるすべての呼び出しを拒否します。これはロックダウンされた CI 実行に役立ちます。Manual モードで承認が不要なアクション(作業ディレクトリでのファイル読み取りや 読み取り専用コマンドセット など)はまだ実行され、--allowedTools エントリまたは permissions.allow ルールがカバーするアクションも実行されます。AskUserQuestion、組織が ask に設定したコネクタツール、および requiresUserInteraction とマークされた MCP ツールは、許可ルールが一致する場合でも拒否されます
  • acceptEdits:Claude はプロンプトなしでファイルを書き込み、Claude Code は mkdirtouchmvcp などの一般的なファイルシステムコマンドを自動承認します。モードが自動承認しないアクション はまだ適用されます。読み取り専用コマンドセット以外に、その他のシェルコマンドとネットワークリクエストは --allowedTools エントリまたは permissions.allow ルールが必要です。acceptEdits が自動承認するもの の完全なリストについては、「何を acceptEdits が自動承認するか」を参照してください
この例は acceptEdits をベースラインとしてリント修正を適用します。

無人実行で権限プロンプトをオフにする

誰も権限プロンプトに答えられない場合(例えば、スケジュール済みジョブ)、--permission-prompts none を渡します。フラグは、権限ホストを持つ実行(canUseTool コールバック を持つ Agent SDK アプリ、または --permission-prompt-tool で渡す MCP ツール)がある場合に最も重要です。フラグなしでは、実行はそのホストに各権限リクエストに答えるよう待機します。 フラグを使用すると、実行はホストに相談せず、それを待機しません。プロンプトが表示されるものはすべて、PermissionRequest フックが許可しない限り拒否され、Claude には誰も要求を承認できず、再試行しないよう伝えられ、実行は続行されます。権限ルール、PermissionRequest フック、および設定した権限モードはまず各呼び出しを決定します。Claude Code は他に何も解決しないリクエストのみを拒否します。 この例は 自動モード で無人タスクを実行します。分類器は通常どおり各アクションをレビューし、Claude Code はプロンプトにフォールバックしたであろうものをすべて拒否します。
--permission-prompts none を使用すると、Claude Code は AskUserQuestion などの人からの答えが必要なツールを削除するため、Claude はそれらを呼び出せません。Elicitation フック が答えない MCP 誘導リクエスト はキャンセルされます。 --output-format stream-json を使用すると、拒否は permission_denied システムメッセージとして表示され、最終結果メッセージは permission_denials にそれらをリストします。
--permission-prompts フラグには Claude Code v2.1.259 以降が必要です。以前のバージョンはそれを未知のオプションエラーで拒否します。

コミットを作成する

この例は、ステージされた変更を確認し、適切なメッセージを含むコミットを作成します。
--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 にパイプし、セキュリティ脆弱性をレビューするよう指示します。シェルスクリプトとして保存します。例えば review.sh
スクリプトでは、"$1" はコマンドラインで渡す最初の引数を表します。bash review.sh 123 を実行すると、シェルは "$1"123 に置き換えるため、スクリプトは PR 123 の diff をフェッチします。Claude Code はレビューを JSON として出力し、テキストは result フィールドに含まれます。 デフォルトプロンプトを完全に置き換える --system-prompt を含む詳細なオプションについては、システムプロンプトフラグ を参照してください。

会話を続ける

--continue を使用して最新の会話を続けるか、--resume をセッション ID と共に使用して特定の会話を続けます。Claude Code v2.1.257 以降では、--continue を渡すと、Claude Code は完了した バックグラウンドセッション を開きますが、まだ実行中のセッションは開きません。この例はレビューを実行し、その後フォローアッププロンプトを送信します。
複数の会話を実行している場合は、セッション ID をキャプチャして特定の会話を再開します。
2 つのコマンドを異なるディレクトリから実行できます。Claude Code は セッション ID でセッションを検索 し、このマシン上の任意のプロジェクトで検索します。v2.1.223 より前では、Claude Code は現在のプロジェクトディレクトリとその git worktrees でのみ ID を検索したため、両方のコマンドを同じディレクトリから実行する必要がありました。 セッション ID の代わりに、--resume にセッションの .jsonl トランスクリプトファイル への絶対パスを渡すことができ、Claude Code はそのファイルに保存されている会話を続けます。

次のステップ