Multi-Agent Architecture with AGENTS.md — Collaborative AI Development in Antigravity

What is AGENTS.md?

AGENTS.md is a powerful feature in Google Antigravity IDE that enables you to define and manage multiple AI agents in a single system. It's more than documentation—it's a declarative schema for specifying agent roles, inter-agent communication, dependencies, and orchestration strategies.

For complex projects, delegating everything to a single AI is inefficient. Instead, breaking work into specialized agents that collaborate naturally leads to better outcomes. AGENTS.md gives you the structure to make this collaboration explicit, improving visibility and maintainability across your entire project.

AGENTS.md File Structure

AGENTS.md uses YAML or Markdown format with these core sections:

Base Format

agents:
  - name: "requirements-analyzer"
    role: "Requirements Analysis Agent"
    description: "Parses project requirements and defines scope and deliverables"
    model: "gemini-3-pro"  # or claude-3-opus
    instructions: |
      Conduct requirement interviews and clarify:
      - Business goals
      - Technical constraints
      - High-priority features
      - Timeline and budget
    tools:
      - name: "jira_create_issue"
        description: "Create issue tickets in Jira"
      - name: "confluence_document"
        description: "Document requirements in Confluence"
 
  - name: "architecture-designer"
    role: "Architecture Design Agent"
    description: "Designs system architecture based on technical requirements"
    model: "gemini-3-pro"
    instructions: |
      From received requirements, design:
      - Database schema
      - API structure (OpenAPI-compliant)
      - Frontend/backend separation
      - External service integrations
    dependencies:
      - "requirements-analyzer"  # Awaits requirement completion
    tools:
      - name: "miro_diagram"
        description: "Render architecture diagrams in Miro"
 
communication:
  - from: "requirements-analyzer"
    to: "architecture-designer"
    protocol: "async"  # asynchronous communication
    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"  # coordination agent
  decision_rules:
    - condition: "architecture_conflict"
      action: "escalate_to_human_review"
    - condition: "timeline_critical"
      action: "parallel_execution"

Key Components

Field	Purpose	Notes
`agents`	Agent definitions array	name, role, model, instructions required
`communication`	Inter-agent messaging patterns	async, sync, publish-subscribe supported
`manager_surface`	Orchestration and decision rules	Core of multi-agent coordination
`tools`	External integrations available to agents	Jira, Slack, Confluence, etc.
`dependencies`	Agent execution dependencies	Optimized as DAG (directed acyclic graph)

Manager Surface: Orchestrating Agent Collaboration

Manager Surface is the central coordination mechanism that manages decision-making across multiple agents. It solves critical problems:

Conflict Resolution: When agents propose conflicting solutions
Priority Ordering: Deciding task sequence under resource constraints
Escalation Detection: Identifying when human review is necessary

Case Study: Product Development Workflow

agents:
  - name: "feature-requestor"
    role: "User Request Intake"
    model: "gemini-3-flash"
 
  - name: "engineering-lead"
    role: "Engineering Feasibility Review"
    model: "gemini-3-pro"
    dependencies: ["feature-requestor"]
 
  - name: "product-manager"
    role: "Product Strategy Assessment"
    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 Feasibility: {{ engineering_score }} / 100
        Product Value: {{ product_score }} / 100
        Resource Efficiency: {{ 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"

Multi-Agent Architecture Patterns

Pattern 1: Sequential Pipeline

Agents process tasks in order, with each agent's output feeding the next agent's input.

agents:
  - name: "input-validator"
    role: "Input Validation"
 
  - name: "data-processor"
    role: "Data Preprocessing"
    dependencies: ["input-validator"]
 
  - name: "analysis-engine"
    role: "Analysis & Inference"
    dependencies: ["data-processor"]
 
  - name: "report-generator"
    role: "Report Generation"
    dependencies: ["analysis-engine"]
 
execution_order: "sequential"

Use Cases: Workflow automation, ETL pipelines, document processing

Pattern 2: Consensus (Voting)

Multiple agents independently evaluate a decision, then consensus is reached via voting or scoring.

agents:
  - name: "code-reviewer-a"
    role: "Code Review (Security Focus)"
 
  - name: "code-reviewer-b"
    role: "Code Review (Performance Focus)"
 
  - name: "code-reviewer-c"
    role: "Code Review (Maintainability Focus)"
 
consensus_rules:
  voting_method: "weighted_score"
  weights:
    security: 0.5
    performance: 0.3
    maintainability: 0.2
  approval_threshold: 2  # 2 of 3 agents must approve

Use Cases: Code review, quality assessment, decision committees

Pattern 3: Fan-Out/Fan-In (Scatter-Gather)

One task is distributed to multiple agents working in parallel, with results aggregated.

agents:
  - name: "task-distributor"
    role: "Task Decomposition"
 
  - name: "worker-a"
    role: "API Documentation"
    dependencies: ["task-distributor"]
 
  - name: "worker-b"
    role: "Frontend Implementation Guide"
    dependencies: ["task-distributor"]
 
  - name: "worker-c"
    role: "Test Suite Generation"
    dependencies: ["task-distributor"]
 
  - name: "integrator"
    role: "Artifact Integration"
    dependencies: ["worker-a", "worker-b", "worker-c"]
 
execution_mode: "parallel"

Use Cases: Large-scale parallel development, multi-document generation, multimodal processing

Real-World Example: SaaS Product Development

Here's a complete multi-agent system for automating SaaS product development:

agents:
  - name: "requirements-intake"
    role: "Requirements Capture"
    model: "gemini-3-pro"
    instructions: |
      Gather user stories and record them as
      Jira tickets with acceptance criteria.
    tools:
      - jira_create_issue
      - slack_notify
 
  - name: "schema-designer"
    role: "Database Schema Design"
    dependencies: ["requirements-intake"]
    instructions: |
      Design PostgreSQL schema from requirements.
      Define tables, relationships, indexes.
    tools:
      - dbdiagram_export
      - github_create_pr
 
  - name: "api-designer"
    role: "API Specification"
    dependencies: ["requirements-intake"]
    instructions: |
      Generate OpenAPI 3.1 specification.
      Define endpoints, request/response schemas, status codes.
    tools:
      - github_create_pr
      - postman_export
 
  - name: "frontend-architect"
    role: "Frontend Architecture"
    dependencies: ["api-designer"]
    instructions: |
      Design React/Next.js component structure.
      Define pages, state management, routing.
    tools:
      - figma_update
      - github_create_pr
 
  - name: "integration-tester"
    role: "Integration Test Planning"
    dependencies: ["schema-designer", "api-designer", "frontend-architect"]
    instructions: |
      Create E2E test scenarios.
      Implement Playwright scripts.
    tools:
      - github_create_pr
      - playwright_run
 
  - name: "documentation-writer"
    role: "User Documentation"
    dependencies: ["api-designer", "frontend-architect"]
    instructions: |
      Auto-generate README, API docs, setup guides.
    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"

Execution Flow:

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

Best Practices

1. Clear Responsibility Separation

Each agent should follow the Single Responsibility Principle, specializing in one domain.

# Good: Clear responsibility
- name: "schema-designer"
  role: "Database schema design only"
 
# Bad: Blurred responsibility
- name: "architect"
  role: "Design, implement, test everything"

2. Explicit Timeouts

Set clear timeout values to prevent deadlocks and runaway processes.

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

3. Fallback Strategies

Define backup agents when primary agents fail.

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. Comprehensive Logging

Track all agent interactions for debugging and auditing.

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

Troubleshooting

Common Issues and Solutions

Q1: Agent communication times out

# Solution: Adjust timeout values
communication:
  - from: "slow-analyzer"
    to: "next-agent"
    timeout_seconds: 1200  # Extend to 20 minutes

Q2: Conflicting proposals from agents

# Solution: Set explicit priorities in Manager Surface
manager_surface:
  conflict_resolution: "priority_based"
  priorities:
    - agent: "security-auditor"
      score: 100  # Security always wins
    - agent: "performance-optimizer"
      score: 80

Q3: Some agents not responding

# Solution: Enable periodic health checks
health_check:
  interval_seconds: 300
  timeout_seconds: 30
  on_failure:
    action: "restart_agent"
    max_restarts: 3

Looking back

AGENTS.md gives you:

Declarative Agent Definition — Understand your entire multi-agent system from one config file
Explicit Dependencies — Optimize execution order using DAG structure
Coordinated Decision-Making — Manager Surface automates conflict resolution and escalation
Production-Ready Operations — Integrated logging, failover, and monitoring

The larger your project, the more you benefit from multi-agent architecture. AGENTS.md ensures scalability and maintainability as your team grows.