netlify-agent-runner

Netlify Agent Runner

Netlify のインフラストラクチャ上で AI コーディングエージェント（Claude、Codex、Gemini）をリモート実行し、サイトの開発タスクを自動化します。

前提条件

• サイトが Netlify プロジェクトにリンクされている必要があります（netlify link または netlify init を使用）。
• リンクを完全に省略することもできます： netlify agents:create に --project <name>（プロジェクト ID または名前）を直接渡すと、事前にリンクしなくても任意の Netlify サイトを対象にできます。
• Netlify CLI がインストールされ、認証されている必要があります。
• エージェントの実行では プランのクレジットが消費されます。アカウントに利用可能なクレジットがない場合、またはエージェント／AI の利用上限に達している場合、netlify agents:create は ブロックされ、実行は開始されません。これはユーザーに伝えるべきアカウント／プランの状態に関する問題であり、回避を試みるものではありません。

ドキュメントに記載された CLI の機能のみを使用する

エージェントタスクの操作には、ドキュメントに記載された netlify agents:* コマンド（および netlify --help と公開 CLI リファレンス）のみを使用してください。CLI を迂回してはいけません。

• タスクの取得、作成、停止のために https://api.netlify.com/... を curl しないでください。エンドポイントの形式は公開契約の一部ではありません。
• ドキュメントに記載されたコマンドが失敗した際の回避策として、netlify api <method> を実行しないでください。
• サイドチャネル呼び出しの認証に使うため、~/Library/Preferences/netlify/config.json（またはディスク上のほかの場所）から認証トークンを読み取らないでください。

ドキュメントに記載されたコマンドが失敗した場合は、正確なエラーと状況をユーザーに伝えて停止してください。タスクにアクセスするための、ドキュメントにない方法を作り出してはいけません。

エージェントタスクの実行方法

タスクを作成する前にこれを読んでください。エージェントタスクはエージェントをローカルで実行する場合とは動作が異なり、その違いは見落としやすいためです。

• リモートで実行され、ローカルでは実行されません。 タスクはお使いのマシンではなく、Netlify のインフラストラクチャ上で実行されます。タスクはお使いのローカルの作業ツリーではなく、サイトの 接続済みリポジトリ を操作します。リモートエージェントが確認できるのはリモートにプッシュされた内容のみで、コミットされていない変更や未プッシュの変更は確認できません。
• ブランチを基準に実行されます。 デフォルトでは、タスクは本番ブランチ（main または master）を対象に実行されます。エージェントの開始地点となる別の ベース ブランチを選択するには、-b <branch> を使用し、そのブランチが 事前にリモートへプッシュされていることを確認してください。そうしないと、エージェントはリモートに存在しないコードを基に作業することになります。-b が指定するのはベース（開始）ブランチであり、結果の書き込み先ではありません（次の項目を参照）。
• 出力は新しいブランチに反映され、既存ブランチには反映されません。 エージェントは選択したベースブランチに変更をコミットしません。独自の Deploy Preview を含む 新しいブランチ に作業内容をプッシュするため、既存のブランチ（または main）が上書きされることはありません。その新しいブランチ／Deploy Preview でタスクの結果を確認してください。ベースブランチが直接変更されることはありません。
• 非同期です。 netlify agents:create はタスクがキューに登録されるとすぐに返され、作業の完了まで待機することはありません。コマンドが返った時点でも、タスクはリモートで実行中です。
• Webhook やコールバックはありません。 タスクの状態が変わったときや完了したときに通知されることはありません。状況を確認するには、netlify agents:show <task-id> または netlify agents:list で ポーリング する必要があります。
• ステータスには終端状態とそれ以外があります。 タスクのステータスは new → running → done、error、cancelled のいずれかへ遷移します。結果に対処する前に、ステータスが最後の3つのいずれかになるまでポーリングを続けてください。

一般的なワークフロー

1. タスクを 作成 します：netlify agents:create "<prompt>" -a <agent>。返されたタスク ID を控えてください（確実に取得するには --json を使用します）。
2. ステータスを ポーリング します：netlify agents:show <task-id>。完了通知はないため、ステータスが done、error、cancelled のいずれかになるまで定期的に繰り返します。
3. タスクが done になったら結果を 確認 します（error の場合は失敗の内容を確認します）。

エージェントタスクの作成

# Run a prompt with the default agent
netlify agents:create "Add a contact form"

# Choose a specific agent: claude, codex, or gemini
netlify agents:create --prompt "Add dark mode" --agent claude
netlify agents:create -p "Update the README" -a codex
netlify agents:create -p "Write unit tests" -a gemini

# Target a specific branch
netlify agents:create -p "Fix the login bug" -a claude -b feature-branch

# Specify a project by name (if not in a linked directory)
netlify agents:create "Add tests" --project my-site-name

# Output result as JSON
netlify agents:create "Add a footer" --json

オプション

フラグ	説明
-a, --agent <agent>	エージェントの種類：claude、codex、または gemini
-p, --prompt <prompt>	エージェントが実行するプロンプト
-b, --branch <branch>	作業対象の Git ブランチ
-m, --model <model>	エージェントで使用するモデル
--project <project>	プロジェクト ID または名前
--json	結果を JSON 形式で出力します

エージェントタスクの管理

すべての netlify agents:* コマンドはプロジェクト単位で動作します。対象はチーム全体ではなく、単一のプロジェクト（ディレクトリがリンクされているプロジェクト、または --project <name> で指定したプロジェクト）です。netlify agents:list には、そのプロジェクトのタスクだけが表示されます。すべてのサイトにまたがるタスクを一覧表示するチーム全体向けのコマンドはありません。別のサイトのタスクを確認するには、そのサイトにリンクされたディレクトリでコマンドを実行するか、--project <name> を渡してください。

タスクの一覧表示

# List all tasks for the current site
netlify agents:list

# Filter by status
netlify agents:list --status running
netlify agents:list --status done
netlify agents:list --status error

# Output as JSON
netlify agents:list --json

ステータスの値：new、running、done、error、cancelled。

タスクの詳細表示

netlify agents:show <task-id>
netlify agents:show <task-id> --json

実行中のタスクを停止

netlify agents:stop <task-id>

ユースケース

Agent Runners でできることの一部をご紹介します。

カテゴリ	プロンプトの例
プロトタイピング／社内ツール	"Build an internal dashboard for our HR team"
コードレビュー	"Audit the code with fresh eyes and identify areas for improvement"
セキュリティ監査	"Do a deep security audit of our codebase to identify any potential issues"
機能の提案	"Based on our current codebase & docs, what should we build next?"
パフォーマンス改善	"Scan our codebase for performance bottlenecks and suggest improvements"
テレメトリと分析	"What analytics things are we not tracking but probably should"
SEO 監査	"Audit our site for SEO issues — missing meta tags, broken links, slow pages, missing alt text"
コピーの改善	"Rewrite our landing page copy to be more compelling and conversion-focused"
アクセシビリティ	"Run an accessibility audit and fix all WCAG 2.1 AA violations"
モバイル対応	"Improve the mobile responsiveness — audit every page on small viewports"
エンドツーエンドテスト	"Add end-to-end tests for our critical user flows using Playwright"
ユニットテスト	"Generate unit tests for our untested utility functions"
ドキュメント	"Generate a README and contributing guide based on our codebase"
エラー処理	"Add proper error boundaries, logging, and user-friendly error states throughout the app"
UX の仕上げ	"Add loading states, skeleton screens, & transitions to improve perceived performance"
フォームの強化	"Add form validation, rate limiting, and spam protection to our contact form"
Edge Functions	"Add an edge function for A/B testing on our landing page"

エージェントとしての利用

AI エージェントの場合は、netlify agents:create を使用して、Netlify 上でリモート実行されるエージェントに作業を委任できます。たとえば、別のモデルにセカンドオピニオンを求めることができます。

重要 — まず、独立した確認手順として許可を求めてください。 エージェントのタスクは Netlify のインフラストラクチャ上で実行され、ユーザーのクレジットを消費するため、実際に承認を得る手順が重要です。netlify agents:create コマンドを実行する前に、明示的な許可を得てください。また、この確認はユーザーの最初の依頼とは別のターンとして扱ってください。「タスクを開始して……」「claude エージェントを使って Opus に固定して」のような指示口調のプロンプトは、それ自体が承認ではありません。ユーザーの希望を伝えるものですが、課金されるコマンドを実行するには、まだ「はい」という返事が必要です。

許可を求める際は、選択肢を並べるのではなく、具体的な提案を示してください。

• 内容を埋めた正確なコマンド — たとえば、netlify agents:create -p "<the real prompt>" -a codex のようにします。<placeholder> やエージェントを選ばせるリストにはしないでください。
• 選定済みのエージェントを1つ — -a の値を1つ選び、「認証ロジックについてセカンドオピニオンを得るため codex を選びました」のように、その理由を伝えてください。claude／codex／gemini を同等の選択肢として提示しないでください。
• 理由と、「はい」の後に何が起きるか — 実行は非同期です。agents:create はタスクをキューに入れるとすぐに戻り、コールバックはありません。結果を確認するには、netlify agents:show <task-id> でポーリングします。
• 前提条件が満たされていない場合でも（認証されていない、サイトにリンクされていない、まだ Git リポジトリではないなど）、解決後に実行する正確なコマンドと選定したエージェントを示してください。問題点だけを説明するのではなく、阻害要因と具体的な提案の両方を伝えてください。

ユーザーの承認なしに、これらのコマンドを実行してはいけません。

委任する前に、何を引き渡すのかを把握してください（上記のエージェントタスクの実行方法を参照）。

• ローカルの作業ではなく、プッシュ済みのブランチを対象にリモートで実行されます。 リモートエージェントが確認できるのは、コミットしてプッシュ済みのコードだけです。ローカルで進行中の変更に依存する作業は委任しないでください。リモートエージェントからはその変更が見えず、古いコードを使って作業することになります。タスクに現在の変更が必要な場合は、先にコミットしてプッシュするか、自分で作業を完了してください。
• 非同期であり、委任しても作業は中断されません。 あなたが別の作業を続ける間、タスクはリモートで実行されます。ただし、コールバックはないため、結果を知るにはポーリング（netlify agents:show <task-id>）が必要です。委任しただけでタスクが完了したと思い込まないでください。結果を当てにしたり説明したりする前に、ステータスを確認してください。
• セッションの続きではなく、独立した自己完結型のタスクです。 リモートエージェントは、リポジトリと渡されたプロンプトをもとに新たに作業を開始します。会話の文脈は引き継がれないため、単独で完結するプロンプトを作成してください。

次のような用途に役立ちます。

• 相互検証 — 別のモデルから実装へのセカンドオピニオンを得る
• エッジケースの発見 — 見落とした問題を別のモデルに見つけてもらう
• 別のアプローチ — 同じ問題を別のモデルがどう解決するかを確認する
• 並行作業 — 別の作業を続けながら、独立したタスクをリモートで開始し、後から結果をポーリングする