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

Before drawing any diagram, it is worth separating two things that sound alike: running work in parallel, and finishing sooner. Read only the depends_on fields above and compute the shortest schedule that satisfies them.

# schedule.py — derive execution levels from depends_on alone
from collections import defaultdict
 
def levels(tasks):
    dep = {t["id"]: set(t.get("depends_on", [])) for t in tasks}
    lv, placed, n = {}, set(), 0
    while len(placed) < len(dep):
        ready = [i for i, d in dep.items() if i not in placed and d <= placed]
        if not ready:
            raise SystemExit("cycle: " + str(set(dep) - placed))
        for i in ready:
            lv[i] = n
        placed |= set(ready)
        n += 1
    return lv, n
 
lv, depth = levels(sub_tasks)
by = defaultdict(list)
for task_id, level in lv.items():
    by[level].append(task_id)
 
print("levels:", depth, "/ max width:", max(len(v) for v in by.values()))
for level in sorted(by):
    print(f"  L{level}: {' '.join(sorted(by[level]))}")

Here is what it printed on my machine.

levels: 4 / max width: 1
  L0: db-001
  L1: api-001
  L2: ui-001
  L3: test-001

Max width of one. Four tasks, four levels — the decomposition above has no parallelism in it at all. Four specialist agents would spend three quarters of the run waiting, and the "parallel routing" label would be doing all the work.

The phase diagram I originally sketched for this section did not hold up either. Checking it against the same dependencies:

VIOLATION ui-001 (Phase B) depends on api-001 (Phase B)
→ 1 violation

A hand-drawn diagram lies without meaning to. Never verify a schedule by looking at the picture — derive it from depends_on. I run that check before adding another sub-agent.

So where does the parallelism come from? Not from more agents — from how the edges are drawn. What ui-001 is waiting on is not the implementation of api-001 but its contract. Have the Manager pin the contract first (the OpenAPI definition, the Zod schema, the TypeScript types), then let the frontend and the tests work against a mock.

The same script, fed the contract-first edges:

levels: 3 / max width: 3
  L0: contract-001
  L1: db-001 test-001 ui-001
  L2: api-001

One more task, one fewer level. The time spent writing the contract comes back out of the waiting.

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

Written the obvious way, this step has a trap in it. Here is the version I had first.

// the obvious version — we fix it below
async function aggregateResults(outputs) {
  const validated = {};
 
  for (const [agent, output] of Object.entries(outputs)) {
    if (!validateFormat(output)) {
      throw new Error(`${agent}: Invalid format`);   // the loop stops right here
    }
 
    if (output.includes('ERROR:')) {
      console.warn(`${agent}: Incomplete output`);   // only a warning
    }
 
    validated[agent] = {
      content: output,
      timestamp: new Date(),
      validated: true                                // true either way
    };
  }
 
  return mergeIntoProjectStructure(validated);
}

Feed it five sub-agent outputs, three of them bad — one with a leftover TODO:, one that came back null, one that returned ERROR:. This is the whole console:

threw: qa-specialist: Invalid format

One line for three failures. The TODO: output slipped through with validated: true because the content check only looks for ERROR:, and the agent that actually returned ERROR: was never inspected — the loop had already thrown. Change the insertion order of the object and a different failure is the one you see.

The point of fanning work out is that the failures come back together too. Throwing mid-loop gives that away.

const INCOMPLETE_MARKERS = [/^\s*ERROR:/m, /\bTODO:/, /\bFIXME:/, /<{7} /];
 
function inspect(agentName, output) {
  if (typeof output !== 'string' || output.trim() === '') {
    return { agent: agentName, status: 'invalid', reason: 'output was not a non-empty string' };
  }
 
  const hit = INCOMPLETE_MARKERS.find((re) => re.test(output));
  if (hit) {
    return { agent: agentName, status: 'incomplete', reason: `found unfinished marker ${hit}` };
  }
 
  return { agent: agentName, status: 'ok', content: output };
}
 
function aggregateResults(subAgentOutputs) {
  const reports = Object.entries(subAgentOutputs).map(([name, out]) => inspect(name, out));
  const accepted = reports.filter((r) => r.status === 'ok');
  const rejected = reports.filter((r) => r.status !== 'ok');
 
  return {
    ok: rejected.length === 0,
    accepted: Object.fromEntries(accepted.map((r) => [r.agent, r.content])),
    rejected
  };
}

Same input, same run:

ok = false
accepted = [ 'database-specialist', 'frontend-specialist' ]
rejected backend-specialist [incomplete] found unfinished marker /\bTODO:/
rejected qa-specialist [invalid] output was not a non-empty string
rejected payment-specialist [incomplete] found unfinished marker /^\s*ERROR:/m

All three agents that need another pass surface in one run, and the two that passed can move to the next level as they are. Aggregation is not the step that forwards what succeeded — it is the step that counts everything that did not. Building the merged tree can wait until after that.

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 error;
      }
      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. I run a few sites and several mobile apps single-handedly, and I delegate roles — 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.