まずは、1つのAIエージェントに何でもかんでも任せるスタイルがなぜ行き詰まるのか、現場目線で理由を整理してみます。

単一エージェントで起きるリアルな問題

ひとつの会話スレッドで「仕様確認 → 実装 → テスト実行 → エラー修正」と進めていくと、遅かれ早かれ次のような壁にぶつかります。

• 会話が長引くほど、序盤で伝えたはずの大事な前提や設計ルールを見失う
• テストログやビルドログが何千行も履歴に溜まり、1回のやり取りにかかる待ち時間と、従量課金契約であればAPI料金が跳ね上がる
• 「調査もしながら、コードも書いて、UIも調整して」と欲張った結果、指示がブレて回答のキレが悪くなる

要するに、人間でいう「机の上が書類やゴミで溢れかえって、今何をやっているのか分からなくなった状態」です。どれだけモデルの性能が上がっても、1つの作業スペースにすべてを詰め込めば集中力が落ちるのは避けられません。

司令塔と作業員に切り分ける「Orchestrator-Worker」の考え方

この散らかりを一掃するために取り入れたいのが、AIエージェント設計の王道パターンであるOrchestrator-Worker（司令塔-作業員）パターンです。

Antigravityは標準でサブエージェント機能を備えているため、この設計パターンを非常にスムーズに実践できます。やり方はシンプルで、メインエージェントに直接コードを書かせるのではなく、「タスクの分解、計画づくり、ワーカーへの指示出し、上がってきた成果物の確認」というマネジメント（司令塔）に専念させます。そして、実際の重たい調査やテスト、実装作業は、独立したサブエージェント（作業員）に任せるのです。

Antigravityのサブエージェントは、単に裏でプロンプトを切り替えているだけではありません。OSのプロセスやGitのリポジトリ機能と連携した、かなり頑丈な仕組みになっています。

最初から使える組み込みワーカーと、自作ワーカー

Antigravityには最初から便利なサブエージェントが用意されていますし、自分で専用ワーカーを作ることもできます。

• research：ファイル検索やドキュメント調査専用のワーカー。ファイル書き込み権限を持たない読み取り専用なので、大事なコードを勝手に弄られる心配が一切ありません。
• self：親エージェントと同じツールと指示を受け継ぐ分身ワーカー。独立したスレッドで単体テストをがっつり書いてほしいときなどに活躍します。
• browser：ヘッドレスブラウザを立ち上げて、クリックやスクロール、画面キャプチャを撮ってUI動作を検証してくれるテスト専用ワーカー（/browser コマンドで呼び出せます）。
• 自作カスタムワーカー：特定の業務（セキュリティ監査、移行作業など）に合わせて、指示プロンプトや許可ツールを絞り込んだオリジナルワーカー。

モデルを使い分けてコストと速度を両立する

サブエージェントを起動するとき、どのモデルで動かすか（Model）をタスクごとに選べます。全部一番賢いモデルに任せるとお金も時間も溶けてしまうので、メリハリをつけるのがコツです。

• flash_lite：とにかく速くて安い軽量モデル。特定キーワードの grep 検索やファイル一覧の整理など、頭を使わない単純作業はこれで十分です。
• flash：スピードと精度のバランスが抜群の主力モデル。単体テストの作成、一般的なAPI実装、コード調査など、日常業務の大半はこれで気持ちよく回ります。
• pro：深くじっくり考える最上位モデル。難解なバグの根本原因究明、複雑なリファクタリングの設計、セキュリティ脆弱性の診断など、ここぞという難所にだけ投入します。
• inherit：特に指定せず、親エージェントと同じモデルを引き継ぎます。

【現場検証】inherit と flash はどう違う？実際にログを追ってみた

「設定ファイルに gemini-3.8-flash などと直接書けないのはなぜ？」と疑問に思うかもしれませんが、Antigravityでは inherit や flash、pro という抽象的な階層（Tier）で指定します。

実際に Vertex AI の呼び出しログを確認してみると、非常に興味深い挙動が分かりました。親エージェントを最新の Gemini 3.8 Flash で動かしている状態でサブエージェントを呼んだ場合、以下のようにルーティングされます。

• inherit を指定：親エージェントと同じ最新世代（Gemini 3.8 Flash）がそのまま割り当てられます。
• flash を指定：大量並列での安定性とスループットを重視するため、実績のある Gemini 3.5 Flash などの安定版エンドポイントにルーティングされます。

つまり、「親と同じ最新の賢さで作業させたいなら inherit」「コストを抑えて大量並列で高速に捌かせたいなら flash」と使い分けるのが現場の真のベストプラクティスです。

▲ Vertex AI API の呼び出しログ実測：親エージェント（上段）は最新の Gemini 3.8 Flash、サブエージェントで flash 指定時（下段）は高スループット安定版の Gemini 3.5 Flash にルーティングされている

ここで1つ、現場ならではの非常に重要なTipsがあります。最近の各種コーディングベンチマークでは、前世代の Gemini 3.1 Pro よりも、最新世代の Gemini 3.8 Flash のほうが高いスコアを叩き出す逆転現象が起きています。

そのため、「難関タスクだから」と安易に pro を指定すると、Gemini 3.1 Pro が呼ばれてかえって精度や速度が落ちてしまうことがあります。次世代の Pro モデル（3.5 Pro や 4.0 Pro など）が登場するまでは、親エージェントを Gemini 3.8 Flash に設定し、サブエージェントには inherit を指定して最新の Gemini 3.8 Flash をフル活用するのが、今一番コスパ良く賢く動かす裏ワザです（親側で /effort コマンドを使って推論レベルを上げておけば、その深い思考設定も inherit でそのままサブエージェントへ引き継がれます）。

待っている間はトークンを消費しない「完全イベント駆動」

自作のスクリプトでエージェントを組むと、「サブエージェントが終わったかどうかを数秒おきに親がループして確認する」なんてコードを書いてしまいがちです。これだと待っている間もAPIリクエストが走り、トークンを無駄に食い潰してしまいます。

Antigravityはそのあたりがとてもスマートです。親エージェントがサブエージェントを呼び出したら、そこで自分のターンをスパッと終わらせて自動スリープに入ります。サブエージェントが仕事を終えてメッセージを送ってきた瞬間にシステムが親をパッと起こしてくれるので、待ち時間のトークン消費は完全にゼロです。

サブエージェントを用意する方法は2つあります。「リポジトリにMarkdownで書いてチームで共有する（静的定義）」方法と、「チャットの会話中にその場で作る（動的定義）」方法です。実際の現場では前者が圧倒的に使いやすいので、まずはこちらから見ていきましょう。

1. リポジトリにMarkdownを置くだけ！静的エージェント定義

プロジェクトの .agents/agents/ フォルダ配下に、YAMLヘッダー付きのMarkdownファイルを置くだけで、自分たち専用のカスタムワーカーが完成します。Gitでそのままコミットできるので、チーム全員で同じワーカーを使えるのが最高に便利です。

---

name: security-auditor

description: ソースコードのセキュリティ脆弱性（認証不備、SQLi、秘密情報の露出など）を専門に監査・修正するサブエージェント

subagent: true

model: inherit

tools:

  - view_file

  - grep_search

  - replace_file_content

  - run_command

commandExecutionPolicy: sandbox

---



# セキュリティ監査エージェントの行動指針



あなたはコードベースのセキュリティ監査を担当する専門家です。

指定されたファイルやディレクトリの脆弱性をスキャンし、問題点と修正案をレポートしてください。



## 大事なルール

- 修正コードを書いたときは、必ずテストコマンドを実行して既存機能を壊していないか確認すること。

- 作業が終わったら、検出した脆弱性の要約と修正した差分を親エージェントに報告すること。

ポイントは subagent: true を付けておくこと。これで親エージェントが作業員として認識してくれます。また、tools で必要なツールだけを渡しておけば、余計なツールを使って予期せぬ事故を起こす心配も防げます。

2. その場限りの使い捨てなら動的定義（define_subagent）

「わざわざファイルを作るほどでもないけれど、今やっている古いJSONデータの変換だけ専用ワーカーに隔離してやらせたい」というときは、会話中にエージェント自身が define_subagent ツールを呼び出して一時ワーカーを組み立てます。

{

  "name": "data_migrator",

  "description": "旧スキーマのJSON設定ファイルを新フォーマットに一括変換する一時ワーカー",

  "system_prompt": "設定ファイルの構文変換とバリデーションを専門に行います。作業が終わったら結果の要約を報告してください。",

  "enable_write_tools": true,

  "enable_mcp_tools": false,

  "enable_subagent_tools": false,

  "toolSummary": "Data migrator definition",

  "toolAction": "Defining subagent"

}

もちろん、人間がこのJSONコードを手書きする必要は一切ありません！ 親エージェントが裏側で自律的にこのJSONを組み立てて一時ワーカーを生成してくれます（裏側の仕組みを知っておくと、AIが何をしているのか透明性が高まるので安心です）。

3. 複数ワーカーを一斉に走らせる（invoke_subagent）

準備ができたら、invoke_subagent ツールを使ってワーカーたちを一斉に起動します。1回の指示で複数のワーカーを同時に走らせるのが最大の醍醐味です。

{

  "Subagents": [

    {

      "TypeName": "research",

      "Role": "Payment API Researcher",

      "Model": "flash_lite",

      "Workspace": "inherit",

      "Prompt": "docs/payment-spec.md を確認して、外部決済APIのレート制限と必須ヘッダーを簡潔に要約して報告してください。"

    },

    {

      "TypeName": "security-auditor",

      "Role": "Auth Auditor",

      "Model": "inherit",

      "Workspace": "branch",

      "Prompt": "src/auth/ 配下のJWT検証ロジックに脆弱性がないか監査し、必要なら修正パッチを当てて報告してください。"

    },

    {

      "TypeName": "self",

      "Role": "Unit Test Creator",

      "Model": "inherit",

      "Workspace": "inherit",

      "Prompt": "src/services/orderService.ts の単体テストをJestで作成し、全テストがパスするか確認して結果を報告してください。"

    }

  ],

  "toolSummary": "Dispatching 3 subagents in parallel",

  "toolAction": "Invoking subagents"

}

こちらも同様に、私たちがこのJSONを直接書く必要はありません。「外部決済APIの調査と、認証周りのセキュリティ監査と、注文処理の単体テスト作成を並列で一気にやっておいて！」とチャットで頼むだけで、親エージェントが裏側で上記のようなパラメータを自動生成し、ワーカーたちを一斉に呼び出してくれます。

調査担当（flash_lite）、監査担当（inherit / Gemini 3.8 Flash）、テスト実装担当（inherit / Gemini 3.8 Flash）という、異なる役割と頭脳を持った3つのワーカーが同時にガリガリ作業を進めてくれます。

4. 親には「要約と結果」だけを報告させる（send_message）

作業を終えたサブエージェントは、send_message で親に結果を知らせます。ここで大事なのは、作業中の膨大な試行錯誤ログや検索結果をそのまま親に渡さないことです。「何が分かったか」「どのファイルを直したか」「テストはどうだったか」という要約だけを返してもらうことで、親のコンテキストを常に綺麗な状態に保てます。

5. 作業フォルダの競合を防ぐワークスペース（Workspace）の選び方

複数のサブエージェントを同時に走らせるとき、一番怖いのが「同じファイルを2人が同時に書き換えてコードがめちゃくちゃになる事故」です。これを防ぐために、Antigravityには3つのワークスペースモード（Workspace）が用意されています。

【実践Tips】大きなリファクタリングは「branch」一択！

例えば認証周りのロジックをごっそり書き換えるようなタスクを親のフォルダで直接やらせると、途中でエラーが出たときに手元の開発環境全体が動かなくなってしまいます。

そんなときは Workspace: “branch” を指定してサブエージェントを走らせます。裏で作られた隔離空間の中でコードを直し、テストを実行させます。テストが綺麗に通ったときだけ成果物を親に取り込み、もし失敗して収拾がつかなくなったら、そのワーカーごと破棄してしまえば手元のコードは傷ひとつ付きません。この安心感は一度味わうと手放せなくなります。

「裏で何人もエージェントが動いていると、今何をしているのか分からなくて不安…」という心配もあると思います。AntigravityはGUIでもCLIでも、進行状況が手に取るように分かる仕組みが整っています。

デスクトップアプリ（Antigravity 2.0）の場合

サブエージェントを起動すると、チャット入力欄のすぐ真上に「〇 subagents running」というバーがリアルタイムで出現します。何体のワーカーが今どんな役割で動いているかが、スピナーアニメーション付きで一目で分かる非常にスマートなUIです。

▲ 実際の実行画面：チャット欄のすぐ上に稼働中ワーカーが並び、リアルタイムで進行状況を把握できる

並んでいるワーカー名をクリックすると、チャット画面がそのワーカー専用のスレッドへとシームレスに切り替わります。そこでワーカーが今何を考えているか（Thinking）や、実行中のツール・コマンドのログをリアルタイムでじっくり確認できるので、裏で勝手に変なことをしていないか見守るのも簡単です。

ターミナル（Antigravity CLI / agy）の場合

ターミナル（CLI）でも、サブエージェントの動きが驚くほど分かりやすく可視化されます。ワーカーが起動すると、プロンプト入力欄のすぐ下に 黄色い丸アイコン（●）付きで各ワーカーの現在の作業内容と経過秒数がリアルタイム表示 されます。

▲ CLIでの通常実行画面：入力欄の下にワーカーごとの作業概要と経過時間（16s）がリアルタイムに流れる

さらに全体の進捗や各ワーカーのログを詳しく見たいときは、チャット欄で /agents コマンドを入力します。

▲ /agents コマンドで表示されるTUI管理画面：指示ごとのツリー一覧からサブエージェントを選んで個別セッションに潜入できる

するとターミナル上に専用のTUI管理画面が立ち上がります。指示ごとにワーカーがツリー形式で整理されており、見たいワーカーの [view details] を選んでEnterキーを押すだけで、そのサブエージェントの個別セッション（ログ・Thinking）へ一瞬で潜り込んで見守ることができます。

ここからは、自分が実際に使ってみて「うわ、やられた…」と痛感した落とし穴と、その解決策をシェアします。

1. 終わったのに何も言ってこない（サイレント終了問題）

【現象】サブエージェントが目的のファイルを直して満足したのか、親に何も報告せずにそのままスッと終了してしまい、親エージェントが「あれ？終わったの？どうなったの？」と待ちぼうけを食らうパターンです。

【対策】ワーカーへの指示プロンプトの中に、「作業が終わったら、修正したファイルとテスト結果の要約を必ず親エージェントにメッセージで報告してください」と明確に書いておきます。この一言をプロンプトの最後に添えておくだけで、サイレント終了はほぼ100%防げます。

2. 何でもかんでもサブエージェントを立ち上げて逆に遅くなる問題

【現象】マルチエージェントが便利だからといって、「変数名を1箇所変えるだけ」「関数の引数を1つ増やすだけ」といった数秒で終わる作業までサブエージェントを呼んでしまい、エージェントを起動・通信するオーバーヘッドでかえって時間がかかってしまうパターンです。

【対策】使い分けの目安を持っておくと迷いません。

• 親がその場で直す：直す場所が分かっていて、対象ファイルが1〜2個程度、特別な調査もいらない軽い修正
• サブエージェントに投げる：コードベース全体の検索が必要、何百行ものテストログが出る、別のアプローチと並行して試したい、インフラやDBなど別の領域の作業

3. エージェント同士の指示は「英語」で書かせると超快適

個人的に一番効果を実感しているのが、親エージェントからサブエージェントへの指示文や、内部の報告メッセージを「英語」に統一することです。

• 日本語と比べてトークン消費量が半分から3分の1程度で済むため、APIコストが劇的に浮く
• プログラミングの指示やエラーの解釈は、英語の方がモデルの推論精度が安定してキビキビ動く
• 親エージェントに「サブエージェントへの指示と内部のやり取りは英語で行い、自分（人間）への最終報告だけ日本語でまとめて」と頼んでおくだけでOK

4. 前回の「Skill」と組み合わせるとさらに効果的

「サブエージェントを呼び出すたびに、長いデプロイ手順やレビュー手順をプロンプトに書くのは面倒…」という場合は、前回紹介した Skillを組み合わせるのがおすすめです。

サブエージェントへの指示に「skills/cloud-run-deploy/SKILL.md の手順に沿って作業して」と添えるだけで、サブエージェントが必要なときだけ手順書を動的に読み込み、最小限のトークンで複雑な手順をミスなくこなしてくれます。

今回は、Antigravityのサブエージェントを使って、コンテキストのパンクを防ぎながら開発を爆速化する実践テクニックを紹介しました。

• メインエージェントは司令塔に専念させ、重たい作業は専門ワーカーに切り離す
• タスクの難易度に合わせてPro、Flash、Flash-Liteを賢く使い分け、速度とコストを両立する
• よく使うワーカーは .agents/agents/*.md に書いてGit管理し、チームの共有資産にする
• 壊れると困るリファクタリングは branch モードで隔離して作業させる
• チャット上部の稼働インジケーターやCLIの /agents コマンドで、裏で動くワーカーの思考ログをいつでも確認できるようにしておく

1つのチャット画面に向かって長文の指示を試行錯誤していた頃と比べると、複数の専門ワーカーを率いてプロジェクトを進める感覚は、まさに「開発チームのテックリード」になったような面白さがあります。まだ試したことがない方は、まずは小さな調査やテスト作成からサブエージェントに任せてみてください。

次回は、こうした自律エージェントが暴走しないように制御する「Agent Hooks機能とガードレール設定」を取り上げます。お楽しみに！

システムサポートでは、Google Cloudの導入や活用を支援しております。

Google Cloudを導入したい・導入したけど使いこなせていない…という方は、お気軽にご相談ください！