◉ANTIGRAVITY LABEN
記事一覧/Agents & Manager
◈ Agents & Manager/2026-03-27上級

AGENTS.md によるマルチエージェント設計 — Antigravity の協調型AI開発

AGENTS.md ファイルを使い、複数のAIエージェントの役割・通信パターン・オーケストレーションを定義する方法を完全解説。Manager Surface を活用した協調型開発で、複雑なプロジェクトを効率的に構築します。

agents-md8multi-agent21architecture13orchestration15manager-surface3

AGENTS.md とは何か

Google Antigravity エディタの強力な機能のひとつが、複数の AI エージェントを統合管理する AGENTS.md です。これは単なるドキュメントではなく、エージェント間の通信・役割分担・オーケストレーションを宣言的に定義するスキーマです。

大規模プロジェクトでは、ひとつの AI に全てを委ねるのではなく、各タスクに特化した複数のエージェントが相互に協力する設計が効果的です。AGENTS.md を使うことで、このマルチエージェント・アーキテクチャを明確に記述でき、プロジェクト全体の可視性と保守性が大幅に向上します。

AGENTS.md ファイルの構造

AGENTS.md は YAML またはマークダウン形式で、以下のセクションから構成されます。

基本形式

agents:
  - name: "requirements-analyzer"
    role: "要件分析エージェント"
    description: "プロジェクト要件を解析し、スコープと成果物を定義する"
    model: "gemini-3-pro"  # または claude-3-opus
    instructions: |
      ユーザーの要件ヒアリングを行い、
      以下を明確にします：
      - ビジネスゴール
      - 技術的な制約
      - 優先度の高いフィーチャー
      - 納期・予算
    tools:
      - name: "jira_create_issue"
        description: "Jira に課題チケットを作成"
      - name: "confluence_document"
        description: "要件ドキュメントを Confluence に記録"
 
  - name: "architecture-designer"
    role: "アーキテクチャ設計エージェント"
    description: "技術要件に基づいてシステムアーキテクチャを設計"
    model: "gemini-3-pro"
    instructions: |
      受け取った要件から、以下を設計します：
      - データベーススキーマ
      - API 設計（OpenAPI 準拠）
      - フロントエンド・バックエンド分割
      - 外部サービス連携
    dependencies:
      - "requirements-analyzer"  # 要件分析の完了を待つ
    tools:
      - name: "miro_diagram"
        description: "アーキテクチャ図を Miro に描画"
 
communication:
  - from: "requirements-analyzer"
    to: "architecture-designer"
    protocol: "async"  # 非同期通信
    format: "json"
    schema:
      type: "object"
      properties:
        requirements:
          type: "array"
          items:
            type: "object"
            properties:
              goal: { type: "string" }
              constraints: { type: "array", items: { type: "string" } }
              priority: { type: "string", enum: ["high", "medium", "low"] }
 
manager_surface:
  enabled: true
  orchestrator: "manager"  # 調整役エージェント
  decision_rules:
    - condition: "architecture_conflict"
      action: "escalate_to_human_review"
    - condition: "timeline_critical"
      action: "parallel_execution"

主要な構成要素

フィールド説明備考
agentsエージェント定義の配列name, role, model, instructions 必須
communicationエージェント間の通信パターン非同期・同期・publish-subscribe 対応
manager_surface調整役の有効化・ルール定義マルチエージェント運用の中核
tools各エージェントが使用可能な外部ツールJira, Slack, Confluence など
dependenciesエージェント実行の依存関係DAG（有向非環グラフ）で最適化

Manager Surface を活用した協調型設計

Manager Surface は、複数エージェント間の意思決定を一元管理するための仕組みです。これにより、以下の課題を解決できます：

  • 競合解決: 複数エージェントの提案が対立した時の判断
  • 優先順序: リソース制約下でのタスク優先度の決定
  • エスカレーション: 人間のレビューが必要な局面の検出

実装例：プロダクト開発フロー

agents:
  - name: "feature-requestor"
    role: "ユーザー要望インテーク"
    model: "gemini-3-flash"
 
  - name: "engineering-lead"
    role: "エンジニアリング検討"
    model: "gemini-3-pro"
    dependencies: ["feature-requestor"]
 
  - name: "product-manager"
    role: "プロダクト戦略判断"
    model: "gemini-3-pro"
    dependencies: ["feature-requestor"]
 
manager_surface:
  enabled: true
  orchestrator: "product-director"
 
  decision_workflow:
    - step: "parallel_assessment"
      agents: ["engineering-lead", "product-manager"]
      timeout_seconds: 300
 
    - step: "score_feasibility"
      template: |
        エンジニアリング実行可能性: {{ engineering_score }} / 100
        プロダクト価値: {{ product_score }} / 100
        リソース効率性: {{ efficiency_score }} / 100
 
    - step: "threshold_check"
      rules:
        - if: "total_score > 85"
          then: "approve_immediately"
        - if: "total_score between 50 and 85"
          then: "escalate_to_human_review"
        - if: "total_score < 50"
          then: "reject_with_feedback"

マルチエージェント・アーキテクチャの設計パターン

パターン1：パイプライン型

複数のエージェントが順序立てて処理を進める設計。前のステップの出力が次のステップの入力になります。

# パイプラインの実装例
agents:
  - name: "input-validator"
    role: "入力値検証"
 
  - name: "data-processor"
    role: "データ前処理"
    dependencies: ["input-validator"]
 
  - name: "analysis-engine"
    role: "分析・推論"
    dependencies: ["data-processor"]
 
  - name: "report-generator"
    role: "結果レポート生成"
    dependencies: ["analysis-engine"]
 
execution_order: "sequential"

用途: ワークフロー型の自動化、ETL パイプライン、ドキュメント処理

パターン2：投票型（Consensus）

複数のエージェントが独立して判断し、多数決やスコアリングで決定を下す設計。

agents:
  - name: "code-reviewer-a"
    role: "コードレビュー（セキュリティ視点）"
 
  - name: "code-reviewer-b"
    role: "コードレビュー（パフォーマンス視点）"
 
  - name: "code-reviewer-c"
    role: "コードレビュー（保守性視点）"
 
consensus_rules:
  voting_method: "weighted_score"
  weights:
    security: 0.5
    performance: 0.3
    maintainability: 0.2
  approval_threshold: 2  # 3人中2人以上の承認で OK

用途: コードレビュー、品質評価、意思決定委員会

パターン3：ファンアウト・ファンイン（分散集約）

ひとつのタスクを複数のエージェントが並列に処理し、結果を統合する設計。

agents:
  - name: "task-distributor"
    role: "タスク分割"
 
  - name: "worker-a"
    role: "APIドキュメント作成"
    dependencies: ["task-distributor"]
 
  - name: "worker-b"
    role: "フロントエンド実装ガイド作成"
    dependencies: ["task-distributor"]
 
  - name: "worker-c"
    role: "テストケース作成"
    dependencies: ["task-distributor"]
 
  - name: "integrator"
    role: "成果物統合"
    dependencies: ["worker-a", "worker-b", "worker-c"]
 
execution_mode: "parallel"

用途: 大規模プロジェクトの並列開発、複数ドキュメント生成、マルチモーダル処理

実装例：SaaS アプリ開発フロー

以下は、SaaS プロダクト開発全体をマルチエージェントで自動化する実例です。

agents:
  - name: "requirements-intake"
    role: "要件ヒアリング"
    model: "gemini-3-pro"
    instructions: |
      ユーザーストーリーを収集し、
      Jira チケットとして記録します。
    tools:
      - jira_create_issue
      - slack_notify
 
  - name: "schema-designer"
    role: "DBスキーマ設計"
    dependencies: ["requirements-intake"]
    instructions: |
      要件から PostgreSQL スキーマを設計。
      テーブル定義、リレーション、インデックス戦略を提案します。
    tools:
      - dbdiagram_export
      - github_create_pr
 
  - name: "api-designer"
    role: "API仕様書作成"
    dependencies: ["requirements-intake"]
    instructions: |
      OpenAPI 3.1 仕様書を生成。
      エンドポイント、入出力スキーマ、レスポンスコード定義。
    tools:
      - github_create_pr
      - postman_export
 
  - name: "frontend-architect"
    role: "フロントエンド設計"
    dependencies: ["api-designer"]
    instructions: |
      React/Next.js のコンポーネント設計書を作成。
      ページ構成、ステート管理、ルーティング。
    tools:
      - figma_update
      - github_create_pr
 
  - name: "integration-tester"
    role: "統合テスト計画"
    dependencies: ["schema-designer", "api-designer", "frontend-architect"]
    instructions: |
      E2E テストシナリオを作成。
      Playwright スクリプトを実装。
    tools:
      - github_create_pr
      - playwright_run
 
  - name: "documentation-writer"
    role: "ユーザードキュメント作成"
    dependencies: ["api-designer", "frontend-architect"]
    instructions: |
      README、API ドキュメント、セットアップガイドを自動生成。
    tools:
      - github_create_pr
      - confluence_update
 
manager_surface:
  orchestrator: "project-manager"
 
  quality_gates:
    - phase: "pre-implementation"
      checks:
        - "schema_consistency_check"
        - "api_spec_validation"
        - "component_design_review"
 
    - phase: "post-implementation"
      checks:
        - "integration_test_pass_rate"
        - "documentation_completeness"
        - "security_audit"
 
decision_matrix:
  conflict_resolution:
    - between: "schema-designer" and "api-designer"
      rule: "data-integrity-first"
    - between: "frontend-architect" and "api-designer"
      rule: "api-contract-first"

実行フロー:

requirements-intake
├─→ schema-designer
├─→ api-designer
│   └─→ frontend-architect
│       └─→ integration-tester
└─→ documentation-writer

ベストプラクティス

1. 明確な責任分離

各エージェントは単一責任の原則に従い、ひとつの専門分野に特化させます。

# Good: 責任が明確
- name: "schema-designer"
  role: "データベーススキーマ設計のみ"
 
# Bad: 責任が曖昧
- name: "architect"
  role: "全体アーキテクチャ設計、実装、テスト"

2. タイムアウト設定

エージェント間の待機時間を明示的に設定し、デッドロックを防止します。

communication:
  - from: "designer"
    to: "implementer"
    timeout_seconds: 600
    retry_policy: "exponential_backoff"
    max_retries: 3

3. フォールバック戦略

主要エージェントが失敗した場合のフォールバックを定義します。

manager_surface:
  failover_rules:
    - primary: "advanced-analyzer"
      fallback: "basic-analyzer"
      trigger: "timeout_exceeded"
 
    - primary: "gemini-3-pro"
      fallback: "gemini-3-flash"
      trigger: "rate_limit_exceeded"

4. ログとトレーシング

全エージェント間の通信を記録し、問題発生時の追跡を容易にします。

logging:
  enabled: true
  level: "DEBUG"
  backends:
    - type: "gcs"  # Google Cloud Storage
      bucket: "project-agent-logs"
    - type: "slack"
      on_error: true

トラブルシューティング

よくある問題と対処法

Q1: エージェント間の通信がタイムアウトする

# 対処: タイムアウト値を調整
communication:
  - from: "slow-analyzer"
    to: "next-agent"
    timeout_seconds: 1200  # 20分に延長

Q2: 競合する提案が発生する

# 対処: Manager Surface で優先度を明示
manager_surface:
  conflict_resolution: "priority_based"
  priorities:
    - agent: "security-auditor"
      score: 100  # セキュリティが最優先
    - agent: "performance-optimizer"
      score: 80

Q3: 一部エージェントが応答しない

# 対処: ヘルスチェックを定期実行
health_check:
  interval_seconds: 300
  timeout_seconds: 30
  on_failure:
    action: "restart_agent"
    max_restarts: 3

全体を振り返って

AGENTS.md を活用することで：

  1. 複数エージェントを宣言的に定義 — 設定ファイルで全体像を把握
  2. 依存関係を明確化 — DAG で実行順序を最適化
  3. Manager Surface で協調 — 競合解決とエスカレーションを自動化
  4. 本番運用に対応 — ログ、フェイルオーバー、監視機能を統合

大規模プロジェクトほど、マルチエージェント・アーキテクチャの恩恵は大きいです。チームの規模が増えても、AGENTS.md で定義した構造により、スケーラビリティと保守性を保証できます。

シェア

お読みいただきありがとうございます

Antigravity Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • ✦コピー&ペーストで使える実装コード付き
  • ✦毎日新しい上級ガイドを追加
  • ✦¥580/月 または ¥1,480 の永久アクセス
メンバーシップを見る →

もしこの記事がお役に立ちましたら、チップ（¥150）で応援いただけると大変励みになります。広告なしでの運営を続けるため、皆さまのご支援が大きな力になっています。

関連記事

◈ Agents & Manager2026-03-26
Antigravity マルチエージェント開発 実践設計パターン — AgentKit で構築する自律型AIチーム
AgentKit 2.0 のマルチエージェント設計パターンを深掘り。5つのオーケストレーション戦略、暴走防止、コスト管理の具体的な実装例。
◈ Agents & Manager2026-06-19
並列にするか、順番に残すか — 複数エージェントを束ねるときの損益分岐
複数のエージェントを並列で走らせるべきか、直列のまま残すべきか。調整コストと待ち時間短縮の損益分岐をざっくり見積もる式と、4サイト運用での実際の線引き、判定を自動化する小さなスクリプトまでまとめました。
◈ Agents & Manager2026-06-15
Antigravity のマルチエージェントを本番で壊さない封じ込め設計 — 連鎖障害を止める3つの境界の実装メモ
Antigravity のマルチエージェント構成は単体では綺麗に動くのに、本番では小さな失敗が全体に波及します。連鎖障害を止めるための制御の階層化・信頼境界・観測と冪等性という3つの境界を、TOML 設定と相関IDラッパーの実装まで含めて整理しました。
📚RECOMMENDED BOOKS
大規模言語モデル入門
山田育矢
LLM開発
生成AIプロンプトエンジニアリング入門
我妻幸長
プロンプト
Claude CodeによるAI駆動開発入門
平川知秀
AI駆動開発
※ アフィリエイトリンクを含みます
もっと見る →