Orchestrating a Team of Specialist Agents Solo: Practical Multi-Agent Design in Antigravity

Antigravity's Multi-Agent Architecture

Three Core Layers

Layer 1: Manager Surface

The orchestrator that receives user requests and delegates to sub-agents.

Responsibilities:

• Task decomposition: Break complex requests into atomic tasks
• Routing: Assign each task to the right specialist
• Dependency management: Determine execution order
• Result aggregation: Merge outputs into final deliverables

Layer 2: Sub-Agents (Specialists)

Each agent specializes in one domain. Antigravity provides these presets:

• code-gen-agent: Multi-language code generation
• design-agent: UI components and specifications
• test-agent: Automated test generation
• security-agent: Vulnerability scanning and fixes
• doc-agent: Technical documentation

You can also define custom agents for domain-specific tasks.

Layer 3: Orchestrator

Manages communication and data flow between agents.

Manager
  ↓
[Task 1, Task 2, Task 3]
  ↓
Sub-agents (parallel execution)
  ↓
[Result 1, Result 2, Result 3]
  ↓
Orchestrator (validate and merge)
  ↓
Final Output

AgentKit 2.0: The Framework

AgentKit 2.0 transforms this architecture into an opinionated framework. You define:

1. AGENTS.md: Role definitions and instructions
2. Orchestration logic: How agents collaborate

Everything else is automated.

AGENTS.md: Defining Your Agent Ecosystem

Core Structure

Place AGENTS.md at project root:

# Antigravity Agents Configuration
 
## Project Identity
project_name: "ecommerce-platform"
version: "2.0"
 
## Global Instructions
Keep outputs modular and testable.
Prefer clear naming over comments.
Always consider security.
 
## Manager Agent
name: "orchestrator"
role: "Coordinates all agents"
instructions: |
  - Analyze incoming requests
  - Decompose into sub-tasks
  - Assign to specialists
  - Validate outputs
  - Merge results
 
## Frontend Agent
name: "frontend-specialist"
role: "React + TypeScript expert"
instructions: |
  - Follow component composition patterns
  - Implement error boundaries
  - Optimize render performance
  - Use semantic HTML
dependencies: []
output_format: "TypeScript React components"
 
## Backend Agent
name: "backend-specialist"
role: "Node.js + Express expert"
instructions: |
  - Design RESTful APIs
  - Use dependency injection
  - Add comprehensive logging
  - Write defensive code
dependencies: ["database-agent"]
output_format: "Node.js/Express TypeScript"
 
## Database Agent
name: "database-specialist"
role: "SQL and schema expert"
instructions: |
  - Normalize schemas to 3NF
  - Add indexes for performance
  - Plan for scalability
dependencies: []
output_format: "SQL DDL statements"
 
## QA Agent
name: "qa-specialist"
role: "Test automation expert"
instructions: |
  - Write tests before code
  - Aim for >80% coverage
  - Test error scenarios
dependencies: ["frontend-specialist", "backend-specialist"]
output_format: "JavaScript/TypeScript tests"

Best Practices

1. Instruction Clarity

Vague:

instructions: |
  - Write good code

Precise:

instructions: |
  - Use TypeScript strict mode
  - Implement try-catch error handling
  - Add JSDoc for public APIs
  - Follow camelCase for variables, PascalCase for components

2. Dependency Declarations

dependencies: ["database-agent"]  # backend-agent needs schema first

The orchestrator uses this to determine execution order.

3. Output Format Specification

output_format: "TypeScript React components (.tsx)"
expected_files:
  - "Button.tsx (with props interface)"
  - "Form.tsx (with validation logic)"

Manager Surface Implementation

Three Phases of Task Management

Phase 1: Task Decomposition

User request:

"Build a shopping cart API with PostgreSQL backend,
React frontend, and Stripe payment integration."

Manager decomposes into:

{
  "main_task": "Build shopping cart feature",
  "sub_tasks": [
    {
      "id": "db-001",
      "agent": "database-specialist",
      "description": "Design cart schema",
      "priority": 1
    },
    {
      "id": "api-001",
      "agent": "backend-specialist",
      "description": "Implement REST endpoints",
      "priority": 2,
      "depends_on": ["db-001"]
    },
    {
      "id": "ui-001",
      "agent": "frontend-specialist",
      "description": "Build CartPage component",
      "priority": 2,
      "depends_on": ["api-001"]
    },
    {
      "id": "test-001",
      "agent": "qa-specialist",
      "description": "Write tests",
      "priority": 3,
      "depends_on": ["api-001", "ui-001"]
    }
  ]
}

Phase 2: Parallel Routing

Compute dependencies and execute in parallel:

Phase A (Parallel)
├─ db-001 ✓ Schema complete

Phase B (After A)
├─ api-001 ✓ APIs ready
└─ ui-001 ✓ Components ready

Phase C (After B)
└─ test-001 ✓ Tests ready

Phase 3: Result Aggregation

Merge outputs:

src/
├─ schemas/
│   └─ cart.sql
├─ api/
│   └─ cart.controller.ts
├─ components/
│   └─ CartPage.tsx
└─ tests/
    └─ cart.test.ts

Delegating to Sub-Agents

Instruction template passed to specialists:

{
  "task_id": "api-001",
  "context": {
    "project": "ecommerce-platform",
    "tech_stack": ["Node.js", "Express", "TypeScript"],
    "schema": "cart table with id, user_id, created_at, updated_at"
  },
  "requirements": [
    "Create POST /api/cart",
    "Create GET /api/cart/:cartId",
    "Create PUT /api/cart/:cartId/items",
    "Create DELETE /api/cart/:cartId/items/:itemId",
    "Validate input with Zod",
    "Handle errors (404, 400, 500)"
  ],
  "output_requirements": {
    "format": "TypeScript Express routes",
    "file_name": "cart.controller.ts",
    "includes_tests": false
  }
}

Result Validation and Merging

async function aggregateResults(outputs) {
  const validated = {};
 
  for (const [agent, output] of Object.entries(outputs)) {
    // 1. Format validation
    if (!validateFormat(output)) {
      throw new Error(`${agent}: Invalid format`);
    }
 
    // 2. Content validation
    if (output.includes('ERROR:')) {
      console.warn(`${agent}: Incomplete output`);
    }
 
    validated[agent] = {
      content: output,
      timestamp: new Date(),
      validated: true
    };
  }
 
  // 3. Merge into project structure
  const project = mergeIntoProjectStructure(validated);
  return project;
}

Common Design Patterns

Real projects use a limited set of orchestration patterns. Master these three.

Pattern 1: Map-Reduce (Parallel Independence)

Multiple independent tasks executed in parallel, results merged.

Use case: Multiple API endpoints, parallel test suites, concurrent database schemas.

Example: Five API endpoints

Manager: Implement GET /products, POST /products,
         GET /products/:id, PUT /products/:id, DELETE /products/:id

↓ Map Phase (Parallel)

[backend#1]     [backend#2]     [backend#3]     [backend#4]     [backend#5]
GET /products   POST /products  GET /products:id PUT /products:id DELETE /products:id

↓ Reduce Phase

Orchestrator merges into single products.controller.ts

Implementation tips:

• Limit parallel agents (3-5 is optimal)
• Monitor token and memory usage
• Set per-agent timeout (5 min typical)

Pattern 2: Pipeline (Sequential Transformation)

Previous step's output becomes next step's input.

Use case: Schema → Migration → Indexes, Design → Implementation → Documentation.

Example: API Development Pipeline

Step 1: API Requirements (Manager)
└─ API specification document

Step 2: Database Schema (database-agent)
Input: API spec
└─ schema.sql

Step 3: Backend Implementation (backend-agent)
Input: schema + API spec
└─ controller.ts

Step 4: Test Generation (qa-agent)
Input: controller.ts
└─ controller.test.ts

Step 5: Documentation (doc-agent)
Input: controller.ts + tests
└─ API.md

Implementation tips:

• Ensure data format consistency between steps
• Implement early failure detection
• Plan partial rollback mechanisms

Pattern 3: Supervisor (Quality Gate)

Independent agents produce output, supervisor validates and optionally fixes.

Use case: Security audit with auto-fix, code quality scoring, performance optimization.

Example: Security Review Loop

Step 1: backend-agent generates API code
└─ controller.ts

Step 2: security-agent scans vulnerabilities
Input: controller.ts
Output: "SQL Injection at line 45", "XSS at line 88"

Step 3: backend-agent fixes issues
Input: controller.ts + vulnerability list
Output: controller.ts (fixed)

Step 4: security-agent re-validates
Input: fixed code
Output: "✅ All checks passed"

→ Merge to main

Implementation tips:

• Define clear quality criteria (score ≥ 90 = OK)
• Set iteration limit (max 3 retries)
• Escalate unsolvable issues to humans

Real-World Project: Automated Code Review Pipeline

Let's build a production system: GitHub PR auto-review using multi-agents.

Scenario

On PR creation, automatically run:

1. Lint analyzer: Code quality checks
2. Security scanner: Vulnerability detection
3. Performance analyzer: Bottleneck identification
4. Review aggregator: Merge findings into GitHub comment

AGENTS.md Definition

# GitHub PR Auto-Review System
 
## Manager Agent
name: "pr-orchestrator"
instructions: |
  - Parse GitHub PR diff
  - Extract changed files
  - Assign to specialist agents
  - Aggregate results
 
## Lint Analyzer
name: "lint-analyzer"
expertise: ["ESLint", "TypeScript strict mode", "Complexity"]
instructions: |
  - Check TypeScript strict mode
  - Run ESLint rules
  - Detect circular dependencies
  - Report cyclomatic complexity > 10
 
## Security Scanner
name: "security-scanner"
expertise: ["OWASP", "Secrets", "Vulnerabilities"]
instructions: |
  - Scan for hardcoded secrets
  - Check dependency vulnerabilities
  - Detect SQL injection patterns
  - Review authentication logic
 
## Performance Analyzer
name: "perf-analyzer"
expertise: ["Rendering", "Bundle size", "Queries"]
instructions: |
  - Check React optimization (memoization)
  - Estimate bundle size impact
  - Detect N+1 queries
  - Review asset loading
 
## Aggregator
name: "review-aggregator"
dependencies: ["lint-analyzer", "security-scanner", "perf-analyzer"]
instructions: |
  - Consolidate findings
  - Categorize by severity
  - Format as GitHub markdown

Implementation

Step 1: Webhook listener

const express = require('express');
const { OrchestratorManager } = require('./orchestrator');
 
const app = express();
app.post('/webhook/github', express.json(), async (req, res) => {
  const { action, pull_request } = req.body;
 
  if (action !== 'opened' && action !== 'synchronize') {
    return res.sendStatus(200);
  }
 
  const diff = await fetchPRDiff(pull_request);
  const orchestrator = new OrchestratorManager(diff, pull_request);
  orchestrator.run().then(reviews => {
    postGitHubComment(pull_request, reviews);
  });
 
  res.sendStatus(202);
});

Step 2: Specialist agents

class LintAnalyzer extends SubAgent {
  async analyze(diff) {
    const issues = [];
    const files = this.parseFiles(diff);
 
    for (const file of files) {
      if (!file.name.endsWith('.ts') && !file.name.endsWith('.tsx')) continue;
 
      const content = await getFileContent(file.name);
      const eslintResults = await this.runESLint(content);
      issues.push(...eslintResults.map(r => ({
        type: 'lint',
        file: file.name,
        line: r.line,
        message: r.message,
        severity: r.severity
      })));
    }
 
    return { agent: 'lint-analyzer', issues };
  }
}
 
class SecurityScanner extends SubAgent {
  async analyze(diff) {
    const findings = [];
 
    const secrets = this.detectSecrets(diff);
    if (secrets.length > 0) {
      findings.push({
        type: 'critical',
        message: `Hardcoded secret detected`,
        severity: 'critical'
      });
    }
 
    const vulnDeps = await this.auditDependencies();
    findings.push(...vulnDeps.map(v => ({
      type: 'vulnerability',
      message: `${v.package} CVE: ${v.cve}`,
      severity: 'high'
    })));
 
    return { agent: 'security-scanner', findings };
  }
}

Step 3: Result aggregation

class ReviewAggregator extends SubAgent {
  async aggregate(lintResults, securityResults, perfResults) {
    const findings = [
      ...lintResults.issues,
      ...securityResults.findings,
      ...perfResults.issues
    ];
 
    const sorted = findings.sort((a, b) => {
      const severity = { critical: 3, high: 2, warning: 1, info: 0 };
      return severity[b.severity] - severity[a.severity];
    });
 
    let comment = '## 🤖 Automated Code Review\n\n';
 
    const critical = sorted.filter(f => f.severity === 'critical');
    if (critical.length > 0) {
      comment += `### 🔴 Critical (${critical.length})\n`;
      critical.forEach(issue => {
        comment += `- **${issue.file}:${issue.line}** - ${issue.message}\n`;
      });
      comment += '\n';
    }
 
    return comment;
  }
}

Debugging and Monitoring

Structured Logging

{
  "timestamp": "2026-04-07T10:15:30Z",
  "transaction_id": "mgr-001-23049",
  "phase": "task_decomposition",
  "manager_input": "Build shopping cart API",
  "sub_tasks": [
    { "task_id": "db-001", "agent": "database-specialist", "status": "queued" },
    { "task_id": "api-001", "agent": "backend-specialist", "status": "queued" }
  ],
  "duration_ms": 2000
}

Query logs:

# Trace specific transaction
cat orchestration.log | jq '.[] | select(.transaction_id == "mgr-001-23049")'
 
# Agent execution time stats
cat orchestration.log | jq 'group_by(.agent) | map({agent: .[0].agent, avg_time: (map(.duration_ms) | add / length)})'
 
# Find failures
cat orchestration.log | jq '.[] | select(.status == "failed")'

Performance Bottleneck Analysis

Task db-001 (database)     ████████░░ 8s
Task api-001 (backend)     ██████████ 10s  ← Longest
Task test-001 (qa)         ███████░░░ 7s
─────────────────────────────────────
Sequential: 25s → Parallel (optimal): 10s
Efficiency gain: 2.5×

Solution strategies:

• Task subdivision
• Caching previous results
• Optimized agent instructions
• Higher-performance models

Production Deployment Checklist

Security

• [ ] API Keys: Environment variables only, rotation plan
• [ ] Authentication: Inter-agent tokens, role-based access
• [ ] Data Protection: Encryption at rest, PII anonymization
• [ ] Audit Logs: All agent operations recorded

Cost Management

• [ ] Token Tracking: Measure per task, optimize prompts
• [ ] Budget Controls: Set monthly limit, auto-pause on exceed
• [ ] Caching: Reuse results, reduce duplicate calls

class CostManager {
  async executeWithControl(agent, task) {
    const cost = this.estimateCost(task);
    if (this.currentSpend + cost > this.budget) {
      await sendAlert(`Budget exceeded`);
      return null;
    }
    const result = await agent.execute(task);
    this.currentSpend += cost;
    return result;
  }
}

Scalability and Availability

• [ ] Parallel Limits: Cap concurrent agents (e.g., 10)
• [ ] Queuing: Queue excess requests
• [ ] Error Recovery: Retry with exponential backoff
• [ ] Monitoring: SLA enforcement (<5s response)

async function executeWithRetry(agent, task) {
  for (let attempt = 0; attempt < 3; attempt++) {
    try {
      return await agent.execute(task);
    } catch (error) {
      if (attempt === 2) {
        await escalateToHuman(agent, task, error);
        throw;
      }
      await sleep(Math.pow(2, attempt) * 1000);
    }
  }
}

Quality Assurance

• [ ] Output Validation: Schema checks, syntax verification
• [ ] Integration Tests: End-to-end workflows
• [ ] Performance Tests: Standard load profiles

Deployment

• [ ] Staging: Full test before production
• [ ] Gradual Rollout: Start with 10% of users
• [ ] Rollback Plan: Quick revert if issues arise
• [ ] API Versioning: Maintain backward compatibility

What I learned orchestrating specialist agents on my own

Let me step away from theory and share the texture of actually running several agents in parallel. At Dolice Labs I operate four technical blogs and several mobile apps single-handedly, and I delegate roles — content generation, integrity checks, deploy monitoring — to agents split by the nature of the work.

Why splitting roles immediately made things easier

At first I greedily stuffed one agent with "write the article, verify the links, and watch the deploy through." The result: it was hard to tell which stage had failed, and every fix meant re-reading the whole thing.

Once I split responsibilities into a Manager and specialist sub-agents, failures localized to "which specialist's scope did this happen in," and isolating causes got visibly faster. The value of orchestration, I have come to feel, is less about throughput and more about this clarity of responsibility.

How much you can delegate depends heavily on the kind of work

Running things in parallel, the fit for delegation became clear-cut by task type. Here is my felt sense as a table.

In rough numbers, I can hand off well over 80% of routine-check work to agents, while for anything touching billing or permissions I believe the final confirmation must stay with a human, no matter how carefully the prompt is crafted. Blur that line and you trade convenience for accidents you cannot take back.

The time delegation nearly went wrong

I once gave the deploy-monitoring agent the authority to "automatically roll back to the previous version on any anomaly." It looked clever, but the detection threshold was too loose, and it nearly reverted a perfectly healthy deploy.

What I took from that: draw the autonomy boundary by reversibility. Reversible operations are fair to delegate. But irreversible changes to production went back to a shape where the agent proposes and a human approves. When I design a Manager Surface now, I always pause to check that no sub-agent's permissions cross that line.

Summary

The essence of multi-agent orchestration, I believe, is not running many agents — it is carving up responsibility carefully. Centralize coordination in the Manager Surface, hand each sub-agent reversible work, and keep irreversible judgment with a human. Hold that one line and the system grows without strain.

If you are struggling under a single agent carrying too much right now, start by carving out just your most routine stage and standing it up as its own specialist sub-agent. The "ease of isolating causes" you gain from that will quietly teach you how to design the next step.

I am still learning as I go in daily operation, but I hope this helps anyone who, like me, holds several concerns at once on their own. Thank you for reading to the end.