Code Agent Anatomy (16): AgentTeams — Why Is One Agent Not Enough?

Starting with a Real Dilemma

Imagine you give a code agent this task:

"Help me refactor this 5000-line Python project entirely into async style, fill in the unit tests, then run a CI verification."

What happens when a single agent receives this?

It will modify files one by one, then go write tests, then run CI after the tests are done. The whole process runs serially, with frequent file reads, file writes, and model calls along the way — just iterating over all the files might consume tens of thousands of tokens, filling the context window to the brim.

What's more problematic: refactoring files and writing tests are two things that could actually happen simultaneously. But a single agent can't parallelize — it has only one ReAct loop and can only do one thing at a time.

This is the problem AgentTeams is trying to solve.

Conclusions First

AgentTeams is an experimental multi-agent collaboration system in MyCodeAgent. Its core design philosophy is:

It provides six tools: TeamCreate, SendMessage, TeamStatus, TeamDelete, TeamFanout, TeamCollect, and supports three execution modes: in-process (in-process), tmux (dedicated terminal), auto (auto-select).

But this system was ultimately removed from the stable release. Understanding why it was designed and why it was removed is more valuable than simply learning "how to use it."

1. What Makes Multi-Agent Systems Really Hard

Many people, hearing "multi-agent" for the first time, think it sounds simple: isn't it just running a few more model instances?

In reality, once you have multiple agents, you immediately face a series of problems that simply don't exist in single-agent systems:

Problem 1: How do you provide context?

Each agent has its own context window. The primary agent can't just copy the entire conversation history for each sub-agent — that would cause context explosion. So you need to decide: how much context does each sub-agent get? Which parts? In what format?

Problem 2: How do you merge results?

Sub-agent A modified utils.py, sub-agent B also modified utils.py — they're unaware of each other's existence. How do you merge after both are done? Who decides which version is more accurate?

Problem 3: How do you handle failures?

A single agent failure means the current task fails — just retry. But if 10 sub-agents are running in parallel and 3 fail, what then? Re-run all of them? Only re-run the failed ones? Do the failed parts affect the results of other agents?

Problem 4: Who coordinates?

If a primary agent is responsible for coordinating other agents, the primary agent itself becomes a complex state machine — it needs to know which subtasks are complete, which are still running, which failed, and needs to merge all results at the right moment. This coordination logic is itself enormously complex.

AgentTeams' design is an attempt to answer these four questions.

2. The Basic Model of AgentTeams

AgentTeams abstracts multi-agent collaboration into the concept of a Team.

Primary agent (coordinator)
    │
    ├── TeamCreate: create a team
    │
    ├── TeamFanout: distribute tasks to multiple members
    │       │
    │       ├── Member agent 1 ← runs independently, has its own context
    │       ├── Member agent 2 ← runs independently, has its own context
    │       └── Member agent 3 ← runs independently, has its own context
    │
    ├── TeamCollect: wait and collect all members' results
    │
    └── TeamDelete: clean up the team after task completion

Each team has a coordinator (usually the primary agent that created the team) and several members (agents executing subtasks). Members are mutually independent and don't communicate directly — all messages are relayed through the coordinator.

This design solves the "how to merge results" problem: the coordinator is the only role with a global view, and it decides how to merge.

Member agent execution modes:

• in-process: runs in the same Python process, lightweight, but can't truly parallelize (limited by the GIL)
• tmux: runs in a dedicated tmux pane, truly parallel, but with higher startup overhead
• auto: auto-select based on environment

3. A Concrete Use Case

Using the earlier "refactor + test" example, the AgentTeams workflow looks roughly like this:

Primary agent:
1. Call TeamCreate, create a team
2. Scan the project, divide 50 Python files into 5 groups of 10 each
3. Call TeamFanout, distribute 5 "refactor these 10 files" tasks to 5 member agents
4. Wait, while also starting to write the integration test framework code
5. Call TeamCollect, collect the refactoring results from all 5 members
6. Merge results, resolve conflicts
7. Run CI verification
8. Call TeamDelete, clean up the team

5 member agents work simultaneously, each only handling 10 files, so the context window isn't filled by the entire project. The primary agent can do other work while waiting.

This flow is logically sound. The problems arise at the implementation level — which is what article 19 will cover.

4. The Difference Between Sub-Agents and Team Members

Having read this far, you might ask: how is this different from the Task sub-agent discussed in article 08?

This is an excellent question, and the answer is critical:

Task sub-agent (stable feature):

• The primary agent delegates a specific task to a sub-agent
• The sub-agent completes it and returns the result to the primary agent
• The entire process is synchronous: the primary agent waits while the sub-agent finishes, then continues
• Suited for "I'm not good at this, let an expert handle it" scenarios

AgentTeams members (experimental feature):

• The primary agent distributes multiple instances of the same type of task to multiple members
• Members run in parallel, the primary agent doesn't wait for them — it can continue doing other things
• TeamCollect eventually collects all results together
• Suited for "the same thing needs to be done many times, and can be done in parallel" scenarios

Simply put: Task is "you go do it, I'll wait"; AgentTeams is "you all go do it separately, I'll do something else first, tell me when you're done."

5. Why This Direction Matters

AgentTeams was ultimately removed, but the direction it represents — parallel multi-agent collaboration — is a real and important need in the AI agent field.

Currently almost all mature agent frameworks (LangGraph, AutoGen, CrewAI, etc.) are trying to solve similar problems, but with different approaches:

• Some use graphs (DAGs) to describe dependencies between agents
• Some use role-playing to let different agents play different roles
• Some use shared blackboards to let agents communicate through a central state

AgentTeams chose the team + coordinator model, which is the design most closely resembling human team collaboration.

Having understood the design motivation, the next article looks at how messages are passed between agents — these are the blood vessels of the entire collaboration system.

Design Highlights

1. Context Isolation Is the First Principle

Each member agent has its own context and won't be "distracted" by seeing too much irrelevant information. This solves the context pollution problem when a single agent handles long tasks.

2. Coordinator Has the Only Global View

Members don't communicate directly; all coordination goes through the primary agent. This simplifies state management — you don't need to handle the complex situation of agent A and agent B messaging each other and waiting on each other.

3. Three Execution Modes for Three Scenarios

in-process is lightweight and fast, suited for development and testing; tmux is truly parallel, suited for production use; auto lets the framework decide, lowering the barrier to use.

Summary

About the Source Code for This Series

All analysis in this series is based on the open-source project MyCodeAgent.

The AgentTeams implementation code has been removed from the stable release and is preserved in Git history (commit f497b172). You can view design traces via: docs/research-archive.md, docs/plans/2026-07-12-lean-runtime/tasks/M2-03-remove-agent-teams.md.

git clone https://github.com/chendongqi/MyCodeAgent
cd MyCodeAgent
cp .env.example .env   # Fill in your LLM API key
uv sync
uv run python main.py

Visit PrimeSkills — a curated AI Agent and skills marketplace where every piece of content is validated against real enterprise workflows. No hype, only things that actually work.

For more practical insights and interesting products, visit my homepage