メインコンテンツまでスキップ

ヘッドレスモードと Agent SDK

上級

Claude Code はインタラクティブに使うだけのものではありません。ヘッドレス(非インタラクティブでスクリプト化可能)で実行することも、Agent SDK を使って同じ基盤ハーネス上に独自のエージェントを構築することもできます。

What you'll learn
  • 単一のプロンプトを非インタラクティブに実行し、その出力を取得する方法
  • 無人実行には、インタラクティブのデフォルトではなく、意図的な権限方針が必要な理由
  • 1 回限りの呼び出しでは足りなくなり、代わりに Agent SDK を使うべきタイミング
  • 3 つのモードを並べて比較し、習慣ではなく意図して選ぶ方法

ヘッドレスモード​

単一のプロンプトを非インタラクティブに実行して出力を取得します。スクリプト、pre-commit フック、CI に最適です。

スクリプトからステージ済みの diff をレビューする

claude -p "Review the staged diff and list any bugs as a Markdown checklist"

入力をパイプで渡し、結果を受け取ります。承認待ちでハングしないよう、権限を安全な非インタラクティブの方針に設定して組み合わせ、さらに自動実行がシークレットに触れないよう厳重に絞り込んでください(自律実行の堅牢化を参照)。

Guided walkthrough1 of 5
  1. 1 つのプロンプトに 1 つの答えを返して終了します。尋ねてくれる UI がないため、ヘッドレス実行に必要なものはすべてフラグで指定します。

各ステップの正確なフラグと、そこにある落とし穴は、claude CLI:結果を左右するフラグにあります。これらすべてを組み合わせた典型的な使い方が、Claude にすべてのプルリクエストをレビューさせる CI ジョブです。PR レビューのウォークスルーを参照してください。

Agent SDK​

Claude Agent SDK(Python と TypeScript)を使うと、Claude Code を動かしているのと同じループ(ツール使用、ファイル/シェルアクセス、権限、コンテキスト管理)の上に本番向けのエージェントを構築し、あなたのアプリケーションに組み込めます。

単一の API 呼び出しや自作のループでは足りなくなり、すべてが揃ったエージェントのランタイムが欲しくなったときに使います。選択肢の全体像(単一の呼び出し → ワークフロー → カスタムエージェント → マネージド)については、API でエージェントを構築するを参照してください。

ヘッドレス/SDK とインタラクティブの比較​

モード用途
インタラクティブな Claude Code人が介在する日々の開発
ヘッドレス(claude -p)スクリプト、pre-commit、CI の単発処理
Agent SDKソフトウェアに組み込む本番向けエージェント

理解度チェック​

Check yourself

0/2
  1. ヘッドレス実行とインタラクティブセッションを分ける決定的な違いは何ですか?
  2. CI に 1 回限りの `claude -p` 呼び出しがあり、同じロジックを、カスタムツールと独自の権限処理を備えた自社プロダクトに組み込みたくなりました。何を使いますか?
Key takeaways
  • ヘッドレスとは、人を取り除いた同じハーネスのこと。人が決めるはずだったことは、すべて設定になります。
  • 権限を絞り、ターン数と支出に上限をつけ、構造化された出力を求める。この 4 つはすべて、慣習ではなくフラグです。
  • スクリプトからの CLI 呼び出しではなく、ループを自社のアプリケーション内に置きたくなったら、Agent SDK に移行しましょう。
  • 無人実行は、機能であると同時にセキュリティ上の姿勢でもあります。スケジュールする前に、到達できる範囲を堅牢化してください。

次に読む​