AgentTeams: Autonomous Multi-Agent Orchestration for AI Coding Agents

Run coordinated AI agent teams that write cleaner code and save 40%–80% in token costs. Built for Google Antigravity, Claude Code, and any autonomous LLM agent.

📑 Table of Contents

• What is AgentTeams?
• The Problem: Why Unstructured Multi-Agent Fails
• Architecture & How It Works
• ⚡ Quick Install
• 🎯 When to Use AgentTeams (Decision Guide)
• 📊 Empirical Benchmarks & Costs
• 🥊 AgentTeams vs. Alternatives
• 📋 Task Contract Example
• ❓ Frequently Asked Questions (FAQ)
• 📄 License & Attribution

💡 What is AgentTeams?

AgentTeams is an open-source orchestration protocol that turns autonomous AI coding assistants into a coordinated, specialized engineering team. Instead of letting multiple agents converse endlessly in a shared chat room, AgentTeams structures work like a high-performing software engineering organization:

1. The Captain: Decomposes user goals into a strict, dependency-aware Directed Acyclic Graph (Task DAG).
2. Specialized Subagents: Spawns isolated workers (e.g., QA Engineer, Implementer, Reviewer) with bounded file scopes (inScope).
3. Machine-Verifiable Quality Gates: Enforces automated test verification (verify commands with exit code 0) and structured code reviews before tasks can close.
4. Context Isolation: Workers execute in fresh, clean contexts—eliminating token bloat and preventing hallucination.

Works with any agent framework: Google Antigravity, Claude Code, AutoGen, CrewAI, LangGraph, OpenHands, or custom Python LLM loops.

⚠️ The Problem: Why Unstructured Multi-Agent Fails

Most multi-agent systems suffer from two major problems:

• The Multi-Agent Tax (Token Explosion): In conversational multi-agent setups (e.g., chat rooms or open handoffs), every agent sees the entire conversation history. As turn count grows, billed tokens explode quadratically ($O(N^2)$), driving up API costs by 5x–10x.
• Chaotic Handoffs & Hallucinations: Agents without scoped file permissions overwrite each other's code, introduce circular repair loops, and claim tasks are "done" without running verifiable unit tests.

How AgentTeams Solves This

🏗️ Architecture & How It Works

flowchart TD
    User["User Request"] --> Captain

    subgraph Team ["AgentTeams Autonomous Protocol"]
        Captain["Captain Agent (Orchestrator)"]
        DAG["1. Task DAG Generation<br/>(Dependencies, inScope Globs, Acceptance Criteria)"]
        
        T1["2. QA Engineer<br/>(Write Failing Pytest Suite)"]
        G1{"Quality Gate 1<br/>Tests Fail as Expected?"}
        
        T2["3. Implementer<br/>(Implement Code in Scope)"]
        G2{"Quality Gate 2<br/>pytest exit code == 0?"}
        
        T3["4. Code Reviewer<br/>(Independent Audit & Verification)"]
        ReviewVerdict{"Review Verdict?"}
        Repair["Acyclic Repair Task"]
        Merge["Integrate & Close Task"]

        Captain --> DAG
        DAG --> T1
        T1 --> G1
        G1 -->|Yes| T2
        T2 --> G2
        G2 -->|Yes| T3
        T3 --> ReviewVerdict
        ReviewVerdict -->|pass| Merge
        ReviewVerdict -->|needs_revision| Repair
        Repair --> T2
    end

    Merge --> UserSuccess["Verified Solution Delivered"]

⚡ Quick Install

1. Download the Single Skill File (1-Line Command)

# For Google Antigravity:
mkdir -p ~/.gemini/config/skills/agent-teams && curl -fsSL https://raw.githubusercontent.com/sanad-source/agent-teams/main/skills/agent-teams/SKILL.md -o ~/.gemini/config/skills/agent-teams/SKILL.md

# For Claude Code, Cursor, or any other agent:
curl -fsSL https://raw.githubusercontent.com/sanad-source/agent-teams/main/skills/agent-teams/SKILL.md -o AGENT_TEAMS.md

2. Or Clone as a Full Plugin

git clone https://github.com/sanad-source/agent-teams.git ~/.gemini/config/plugins/agent-teams

🎯 When to Use AgentTeams (Decision Guide)

Not every task requires a multi-agent team. Use this guide to choose the optimal architecture:

📊 Empirical Benchmarks & Costs

Empirical testing conducted on Gemini 3.8 Flash ($0.075/1M input tokens, $0.30/1M output tokens):

1. Cost per 20-Turn Engineering Task (USD)

2. Token Scaling Over Conversation Turns

3. Empirical Live Antigravity Test (Untruncated Transcripts)

We evaluated all three architectures on the exact same task (build a thread-safe TokenBucket rate-limiter, write comprehensive tests, and review). Measured directly from transcript_full.jsonl:

The Honest Engineering Truth: For small, self-contained tasks (1–2 files), multi-agent is 5x more expensive because each subagent incurs tool definitions and system prompt overhead. Multi-agent is an architectural tool for complex codebases, multi-file features, and strict TDD, NOT for 10-line scripts.

Verify the raw untruncated transcripts yourself in live_test/real_comparison.json.

🥊 AgentTeams vs. Alternatives

📋 Task Contract Example

Tasks are declared in structured YAML contracts that define dependencies, bounded scopes, and verification commands:

id: "task-token-bucket-impl"
subject: "Implement thread-safe TokenBucket rate limiter"
kind: "implementation"
assignee: "implementer"
dependencies: ["task-token-bucket-tests"]
inScope:
  - "src/rate_limiter/token_bucket.py"
acceptanceCriteria:
  - "Thread-safe consumption using threading.Lock"
  - "Refills tokens monotonically based on elapsed time"
  - "Raises ValueError on non-positive capacity or refill rate"
verify:
  - "pytest tests/test_token_bucket.py"

🚀 How to Use

In Google Antigravity:

• "Use the agent-teams skill to implement <feature>"
• "/goal use agent-teams to refactor the payment gateway"
• /teamwork-preview

In Claude Code, Cursor, or Other LLM Agents:

Include skills/agent-teams/SKILL.md in your project instructions (e.g., in CLAUDE.md, .cursorrules, or system prompt):

Follow the AgentTeams protocol in AGENT_TEAMS.md for all multi-step engineering tasks.

❓ Frequently Asked Questions (FAQ)

What is AgentTeams?

AgentTeams is an open-source orchestration protocol designed for autonomous AI coding agents. It coordinates specialized subagents (such as QA engineers, implementers, and reviewers) using a Captain-orchestrated Directed Acyclic Graph (DAG), strict delivery contracts, and automated quality gates.

Does multi-agent orchestration reduce or increase token costs?

It depends on task size:

• For small tasks (< 10 turns): Multi-agent systems have higher overhead (tool definitions + system prompts) and are more expensive than a single agent.
• For medium-to-large tasks (> 10 turns): AgentTeams cuts token costs by 20% to 57% compared to a monolithic agent, and 80%+ in long conversations, because subagents execute in clean, isolated contexts rather than dragging a 100k-token conversation history through every turn.

How is AgentTeams different from CrewAI, AutoGen, or LangGraph?

• Framework Agnostic: AgentTeams is a lightweight, zero-dependency protocol defined in Markdown and JSON. It runs inside existing agent tools like Google Antigravity or Claude Code without installing heavyweight Python orchestration runtimes.
• No Group Chat Noise: AutoGen and CrewAI rely on conversational turns between agents. AgentTeams uses structured task contracts and isolated execution, preventing context pollution and circular chat loops.
• Enforced Quality Gates: Tasks cannot complete based on an agent saying "I'm done." They require machine-verified automated tests (exit code 0) and structured JSON review verdicts.

Can I use AgentTeams with any LLM?

Yes. AgentTeams is model-agnostic. It has been empirically tested with Gemini 3.8 Flash, but works identically with Claude 3.7 Sonnet, GPT-4o, DeepSeek-R1, or local models.

📄 License & Attribution

• License: MIT
• Author: Sanad Al-Bahar
• Inspiration: Directly inspired by dsh-agent-teams by NanmiCoder.