メインコンテンツへスキップ
Agent SDK は、Claude Code を支える同じツール、エージェントループ、およびコンテキスト管理を提供します。スクリプトと CI/CD 用の CLI として、または完全なプログラムによる制御のための Python および TypeScript パッケージとして利用できます。
CLI は以前「headless mode」と呼ばれていました。-p フラグとすべての CLI オプションは同じように機能します。
CLI からプログラムで Claude Code を実行するには、プロンプトと任意の CLI オプション を指定して -p を渡します。 
claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"
このページでは、CLI（claude -p）経由で Agent SDK を使用することについて説明しています。構造化された出力、ツール承認コールバック、およびネイティブメッセージオブジェクトを備えた Python および TypeScript SDK パッケージについては、完全な Agent SDK ドキュメント を参照してください。

​
基本的な使用方法

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

​
例

これらの例は、一般的な CLI パターンを強調しています。

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

--output-format を使用して、応答がどのように返されるかを制御します。
  • text（デフォルト）：プレーンテキスト出力
  • json：結果、セッション ID、およびメタデータを含む構造化 JSON
  • stream-json：リアルタイムストリーミング用の改行区切り JSON
この例は、セッションメタデータを含む JSON としてプロジェクト概要を返し、テキスト結果は result フィールドに含まれます。 
claude -p "Summarize this project" --output-format json
特定のスキーマに準拠した出力を取得するには、--output-format json を --json-schema および JSON Schema 定義と共に使用します。応答には、リクエストに関するメタデータ（セッション ID、使用状況など）が含まれ、構造化された出力は structured_output フィールドに含まれます。 この例は、関数名を抽出し、文字列の配列として返します。 
claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'
jq などのツールを使用して応答を解析し、特定のフィールドを抽出します。
# テキスト結果を抽出
claude -p "Summarize this project" --output-format json | jq -r '.result'

# 構造化された出力を抽出
claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

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

--output-format stream-json を --verbose および --include-partial-messages と共に使用して、生成されるトークンをリアルタイムで受け取ります。各行はイベントを表す JSON オブジェクトです。 
claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages
次の例は、jq を使用してテキストデルタをフィルタリングし、ストリーミングテキストのみを表示します。-r フラグは生の文字列を出力し（引用符なし）、-j は改行なしで結合するため、トークンは継続的にストリーミングされます。 
claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'
コールバックとメッセージオブジェクトを使用したプログラムによるストリーミングについては、Agent SDK ドキュメントの リアルタイムでレスポンスをストリーミングする を参照してください。

​
ツールを自動承認する

--allowedTools を使用して、Claude が特定のツールをプロンプトなしで使用できるようにします。この例はテストスイートを実行し、失敗を修正し、Claude が許可を求めずに Bash コマンドを実行し、ファイルを読み取り/編集できるようにします。 
claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

​
コミットを作成する

この例は、ステージされた変更を確認し、適切なメッセージでコミットを作成します。 
claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"
--allowedTools フラグは パーミッションルール構文 を使用します。末尾の * はプレフィックスマッチングを有効にするため、Bash(git diff *) は git diff で始まるコマンドを許可します。スペースは重要です。スペースがないと、Bash(git diff*) は git diff-index にも一致します。
ユーザーが呼び出した skills （/commit など）および 組み込みコマンド は、対話モードでのみ利用可能です。-p モードでは、代わりに実行したいタスクを説明してください。

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

--append-system-prompt を使用して、Claude Code のデフォルト動作を保持しながら指示を追加します。この例は PR diff を Claude にパイプし、セキュリティ脆弱性をレビューするよう指示します。 
gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json
デフォルトプロンプトを完全に置き換える --system-prompt を含む詳細なオプションについては、システムプロンプトフラグ を参照してください。

​
会話を続ける

--continue を使用して最新の会話を続けるか、--resume をセッション ID と共に使用して特定の会話を続けます。この例はレビューを実行し、その後フォローアッププロンプトを送信します。 
# 最初のリクエスト
claude -p "Review this codebase for performance issues"

# 最新の会話を続ける
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue
複数の会話を実行している場合は、セッション ID をキャプチャして特定の会話を再開します。 
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

​
次のステップ

Agent SDK クイックスタート

Python または TypeScript で最初のエージェントを構築する

CLI リファレンス

すべての CLI フラグとオプションを探索する

GitHub Actions

GitHub ワークフローで Agent SDK を使用する

GitLab CI/CD

GitLab パイプラインで Agent SDK を使用する