Multi-Agent Orchestration
Antigravity's defining capability is running multiple autonomous agents in parallel on independent tasks. This is not sequential AI assistance — it is concurrent engineering execution. This module covers how parallel agents work, how to dispatch them effectively, how they communicate, and how to aggregate their results.
How Multi-Agent Execution Works
When you dispatch multiple agents, each one operates in a fully isolated environment. Understanding this isolation model is essential for using multi-agent effectively — it explains why agents can work simultaneously without stepping on each other, and why merge conflicts are rare but possible. Here is the four-step process:
Snapshot at Dispatch Time
Each agent receives a snapshot of your codebase at the moment it is dispatched. This means all agents start from the same baseline. If Agent 1 modifies checkout.py, Agent 2 does not see that change — it works from the original version. This isolation prevents agents from interfering with each other during execution.
Isolated Branch Execution
Under the hood, Antigravity creates a lightweight branch for each agent. The agent makes all its changes on this branch. File locking is managed automatically — two agents writing to different files never block each other. If two agents try to modify the same file, Antigravity detects this at dispatch time and warns you.
Independent Verification
Each agent runs tests independently against its own branch. Agent 1's test results do not affect Agent 2. This means each agent's diff is self-contained and verifiable on its own — you do not need to merge all agents' work before validating any single one.
Sequential Merge into Working Tree
When you accept an agent's diff, its changes merge into your working tree. Subsequent accepted diffs must merge cleanly with the updated working tree. Antigravity handles straightforward merges automatically. If a conflict arises, it presents the conflict to you for manual resolution — just like a git merge conflict.
Without isolation, concurrent agents would constantly interfere with each other — one agent's half-finished changes would confuse another agent reading the same file. Antigravity's branch isolation is what makes parallel execution reliable. Think of it like git branches, but managed automatically and invisibly.
Core Multi-Agent Concepts
Parallel Execution
Dispatch up to 8 agents simultaneously. Each agent has its own context, plan, and execution thread. They do not interfere with each other — Antigravity manages file locking and merge conflicts automatically.
The practical limit is usually 3-5 concurrent agents. Beyond that, your review bandwidth becomes the bottleneck — you simply cannot review diffs faster than they arrive. Start with 2-3 parallel agents and increase as you build confidence.
Independent Context
Each agent gets a copy of the codebase context at dispatch time. They work in isolated branches under the hood, so agents writing to different parts of the codebase never block each other.
Context is not shared between agents. Agent 1 cannot "ask" Agent 2 what it changed. This is by design — it prevents cascading dependencies between concurrent tasks and ensures each diff is independently reviewable.
Dependency Awareness
Antigravity detects when two tasks share a file and warns you before dispatching. You can choose to sequence them or accept that the second agent will rebase on the first agent's output.
The dependency check looks at file-level overlap. If your task description mentions checkout.py and another running agent is already modifying checkout.py, you see a yellow warning. You can override the warning, but be prepared for a merge conflict during review.
Merge & Review
When agents complete, their changes queue for your review in the Manager Surface. Accept, reject, or merge individual agent outputs independently — you are never forced to accept all or nothing.
The order in which you accept diffs matters. If Agents 1 and 2 both modify nearby code, accepting Agent 1's diff first may cause Agent 2's diff to need rebasing. Antigravity handles simple rebases automatically and flags complex ones for your attention.
Mission Control — Dispatching Multiple Agents
The Mission Control view (accessed via the Manager Surface) lets you dispatch and monitor multiple agents from a single interface. Here is the workflow:
Open Mission Control
Press Ctrl+Shift+M (Windows/Linux) or Cmd+Shift+M (macOS) to open the Manager Surface. Click the "Mission Control" tab at the top. This shows all active, queued, and completed agents in a single dashboard.
Write Multiple Tasks
Click "New Agent" for each task. Write each task description independently. You can choose a different model for each agent — for example, Gemini 3 Pro for a straightforward test fix, Claude Sonnet 4.6 for a complex business logic change.
Check for Conflicts
Before dispatching, Mission Control shows a conflict analysis: which files each agent plans to touch, and whether any overlap exists. Green means no overlap. Yellow means potential overlap — review the warning. Red means definite conflict — consider sequencing instead.
Dispatch All
Click "Dispatch All" to start all agents simultaneously, or dispatch them individually. Each agent begins executing its plan immediately. The Mission Control dashboard updates in real time with progress bars, status indicators, and agent timelines.
Understanding Agent Isolation in Depth
The isolation model is central to understanding how multi-agent works reliably. Here are the key details:
| Aspect | How It Works | Why It Matters |
|---|---|---|
| File system | Each agent works on a virtual copy of your files. Changes are staged in memory until you accept the diff. | No agent can corrupt your working tree. Rejected diffs simply vanish. |
| Git state | Agents do not create real git branches. Isolation is managed internally by Antigravity. | Your git history stays clean. No leftover agent branches to clean up. |
| Terminal commands | Each agent gets its own virtual terminal. Commands run in the agent's isolated file system view. | Agent 1 running pytest does not see Agent 2's changes. Test results are accurate per-agent. |
| Environment variables | All agents share the same environment variables from your shell. | Sensitive env vars are visible to all agents. Use protected_files in .antigravity to prevent agents from reading .env. |
| Network access | All agents share the same network. Two agents starting a dev server on the same port will conflict. | If agents need to run servers, assign different ports in the task description. |
Three Agents Running — ThreadCo Release Prep
Agent Communication and Coordination
Agents in Antigravity do not communicate directly with each other. This is a deliberate design choice — direct inter-agent communication would create coupling between tasks that are meant to be independent, and it would make individual diffs harder to review in isolation. Instead, coordination happens through you (the developer) and through shared conventions in the .antigravity config file.
Here are four coordination patterns, ordered from safest to most advanced:
Sequential Chaining
When Task B depends on Task A's output, do not dispatch them in parallel. Dispatch Agent A, review and accept its diff, then dispatch Agent B. Agent B starts from the updated codebase that includes Agent A's accepted changes. This is the safest pattern for dependent tasks.
Shared Context via .antigravity
If multiple agents need to follow the same conventions, put those conventions in your .antigravity config file. All agents read this file before starting. This is indirect coordination — agents do not talk to each other, but they follow the same rules.
Human as Router
You are the coordination layer. When Agent 1 finishes and you see that its output affects Agent 2's task, you can pause Agent 2, update its task description with new context, and resume. The Manager Surface supports mid-task instruction updates for running agents.
Rebase on Accept
When you accept Agent 1's diff, the working tree updates. If Agent 2 is still running, it continues from its original snapshot. When Agent 2 finishes, its diff is automatically rebased against the updated working tree. Simple rebases happen automatically; complex ones flag you for manual resolution.
With 2 agents, coordination is trivial. With 3, it is manageable. With 5+, coordination becomes the dominant cost. This is the same principle that makes large engineering teams slower per-person than small teams. Keep your concurrent agent count in the sweet spot (2-4) and you avoid most coordination overhead.
Result Aggregation and Review Order
When multiple agents complete, you need a strategy for reviewing and accepting their diffs. The order matters:
| Strategy | When to Use | How It Works |
|---|---|---|
| First-finished first-reviewed | Default. Tasks are truly independent. | Review and accept diffs in the order they complete. Since tasks are independent, merge order does not matter. |
| Priority-based | One task is more critical than others. | Review and accept the highest-priority diff first, regardless of completion order. Other diffs rebase against the updated tree. |
| Smallest-diff first | Minimizing merge conflict risk. | Accept the smallest, most surgical diffs first. Larger diffs rebase more easily against small changes than vice versa. |
| All-at-once review | Related tasks that need holistic review. | Wait for all agents to finish. Review all diffs side by side before accepting any. Useful when changes need to be coherent as a group. |
When to Use Multi-Agent vs Single Agent
| Use multi-agent when... | Use single agent when... |
|---|---|
| Tasks are independent (different files/features) | Tasks depend on each other's output |
| You have a deadline and multiple outstanding items | One large, complex task needs full context |
| Different parts of the codebase need attention simultaneously | Tasks share core files (risk of conflicts) |
| You want to compare approaches (run two agents with different strategies) | You are still learning the codebase |
| Writing feature code, tests, and docs simultaneously | Architectural refactoring that touches every module |
| Bug triage — dispatch one agent per bug report | Debugging a single complex, cross-cutting issue |
Parallel Execution Patterns
Here are proven multi-agent patterns that work well in practice:
Feature + Test + Docs
Dispatch three agents for one feature: Agent 1 writes the implementation, Agent 2 writes the test suite, Agent 3 updates the documentation. All three read the same codebase snapshot and the same task spec. Accept Agent 1's diff first, then Agent 2 (tests may need rebasing against the new code), then Agent 3.
Bug Swarm
When you have multiple independent bug reports, dispatch one agent per bug. Each bug agent gets the specific bug report as its task: file name, reproduction steps, expected behaviour. Review diffs as they come in. This pattern turns a full day of sequential debugging into 1-2 hours of concurrent review.
A/B Implementation
Dispatch two agents with the same task but different constraints: "Implement the search feature using ElasticSearch" vs "Implement the search feature using PostgreSQL full-text search." Compare their implementations side by side. Accept the one you prefer, reject the other.
Migration Batch
For large migrations (e.g., updating an API across 20 files), batch the files into groups of 4-5 and dispatch one agent per group. Each agent handles its batch independently. This parallelises a tedious migration while keeping each agent's scope manageable.
Multi-agent does not mean less review — it means more concurrent review. Each agent's diff must be read carefully before accepting. Two agents can make individually correct but mutually incompatible changes. You are the integration layer. Never batch-accept multiple agent diffs without reading each one.
The multi-agent model fundamentally changes your role as a developer. Instead of spending 80% of your time writing code and 20% reviewing, you spend 20% writing task descriptions and 80% reviewing agent output. The quality of your review work becomes the primary determinant of code quality. This is not a reduction in skill — it is a shift in which skill matters most.
Most developers find that 3 concurrent agents is the practical sweet spot. Fewer than 3 underutilises the parallelism. More than 5 creates a review backlog — diffs pile up faster than you can read them. Start with 2-3 agents and scale up only when your review speed keeps pace with agent output.
Real-World Multi-Agent Scenario — ThreadCo Release Day
Here is a concrete example of how ThreadCo's developer uses multi-agent orchestration on a release day. This scenario illustrates the patterns in practice:
9:00 AM — Triage
The developer reviews the release blockers: 3 bugs (checkout null reference, missing error message on failed payment, wrong currency symbol on international orders), 1 feature (gift wrapping), and 1 documentation update (API changelog). She writes precise task descriptions for all 5.
9:15 AM — First Batch
She dispatches 3 agents for the 3 bugs — all independent, touching different files. The gift wrapping feature and documentation update go into the queue. Total agents running: 3.
9:25 AM — First Agent Completes
Agent 3 (currency symbol fix) finishes first — it was a one-line change. She reviews the diff (correct), checks the test report (passing), and accepts. She commits: fix: international currency symbol display (agent-assisted). The documentation agent auto-dispatches from the queue.
9:35 AM — Clarification
Agent 1 (checkout null reference) surfaces a question: "Should I also add null checks for the shipping address fields, or only the cart total?" She answers: "Only the cart total for now — the shipping address validation is a separate ticket." Agent 1 continues.
9:50 AM — All Bugs Fixed
Agents 1 and 2 complete. She reviews both diffs, accepts them, and commits each one separately. The gift wrapping feature agent dispatches from the queue. By 10:00 AM, all 3 bugs are fixed, committed, and the feature work is underway — a process that would have taken most of the day sequentially.
Performance Considerations
| Factor | Impact on Performance | Recommendation |
|---|---|---|
| Number of concurrent agents | Each agent consumes model API bandwidth. More agents = slower per-agent response. | Keep to 3-5 concurrent agents. Beyond 5, individual agent speed degrades. |
| Project size | Larger projects take longer to index and load into context. | Use .antigravityignore to exclude build artifacts, dependencies, and binary files. |
| Task complexity | Complex tasks with many iterations consume more time and tokens. | Break complex tasks into focused sub-tasks. One concern per agent. |
| Model choice | Gemini 3 Pro is fastest. Claude Sonnet 4.6 is slower but more thorough. | Use Gemini for simple tasks, Claude for complex reasoning. |
| Test suite speed | Agents run tests after changes. A slow test suite slows every agent. | Ensure your test suite runs quickly. Consider using test filtering to run only relevant tests. |
Handling Conflicts Between Agents
Conflicts happen when two agents modify overlapping code. Here is how to handle them:
Prevention: Check the conflict analysis
Before dispatching, Mission Control shows which files each agent plans to touch. If you see overlap, either rewrite tasks to avoid the shared file, or sequence the agents instead of running them in parallel.
Detection: Automatic rebase
When you accept Agent 1's diff and then review Agent 2's diff, Antigravity automatically rebases Agent 2's changes against the updated working tree. If the rebase succeeds cleanly, you see the rebased diff with no further action needed.
Resolution: Manual merge
If the automatic rebase fails, Antigravity presents the conflict in a standard merge conflict view (with <<<< and >>>> markers). Resolve it as you would any git merge conflict — choose the correct version, edit the merged result, and accept.
Post-merge verification
After resolving a conflict, run your test suite manually to ensure the merged result is correct. Antigravity offers a "Verify merge" button that runs your test command against the current working tree.