[AI Library] Chapter 26: Agent Teams: Agents Working in Conversation
Mastering Claude Code
Chapter 26: Agent Teams: Agents Working in Conversation
Kim Kyung-jin
Mastering Claude Code
The Core Difference Between Subsidiary Agents and Agent Teams
You enter a single prompt: "Create a landing page for a fictional AI startup." A moment later, the screen splits. Three agents wake up simultaneously: a frontend developer agent marked in blue, a backend developer agent in green, and a QA agent in yellow. Each of the three agents begins work in its own domain. But something different happens compared with subsidiary agents.
The frontend developer sends a message to the backend developer. The QA agent sends revision requests to both developers. The agents are communicating with one another.
This is an agent team.
The difference between subsidiary agents and agent teams lies in their communication structure. Subsidiary agents are one-way. When the main session sends a prompt, a subsidiary agent performs the task and returns the result to the main session. In this process, subsidiary agents cannot communicate with one another. Even if they run in parallel, each works in isolation.
Agent teams are two-way. Team members can exchange messages with each other. They can assign tasks to one another. They manage a shared task list together. Direct communication among team members is possible without passing through the main session.
[Figure 26-1] Comparison of communication structure between subsidiary agents and agent teams: Subsidiary agents have only one-way arrows between the main session and themselves. Agent teams have two-way arrows among team members and a shared task list.
The consequences of this structural difference are dramatic.
In a subsidiary agent structure, when you request "Refactor the code and write tests," the main session sends tasks to the refactor agent and the test-writing agent separately. Both agents complete their work independently and send their respective results back to the main session. The main session synthesizes the two results.
The problem is that the refactor agent may have changed the function signature, but the test-writing agent may have written tests based on the original signature. Since they cannot communicate with each other, there is no way to detect such mismatches.
In an agent team structure, the situation is different. When the refactor agent changes a function signature, it can send a message to the test-writing agent: "This function's signature has changed, so please take note." The test-writing agent writes tests reflecting the changed signature. If the QA agent discovers a problem, it requests the fix directly from the relevant agent. There is no need to route through the main session as an intermediary.
An agent team has a main orchestrator that serves as the team lead, much like a project manager. It creates agents, initializes the task list, monitors overall progress, and confirms the quality of results. However, not all communication goes through this orchestrator. Team members communicate directly when necessary.
The Shared Task List and Mutual Task Assignment
The core infrastructure that makes collaboration possible in an agent team is the shared task list.
When the main orchestrator creates an agent team, the first action is to construct a task list. Items such as frontend development, backend API implementation, test writing, and QA verification are listed, and each item is assigned to an owner.
The fact that this task list is shared is crucial. Every team member can see the entire task list. When a member completes their work, they update the status. They can check other team members' progress. And here is the decisive difference from subsidiary agents: a team member can assign new tasks to another team member.
This mechanism came vividly to life in one demonstration. The frontend and backend developers each completed their work and sent their results to the QA agent. The QA agent's verification revealed three critical issues. The QA agent returned these issues to both the frontend and backend developers, assigning each of them a fix task.
After the two developers completed their revisions and sent them back to the QA agent, the second round of verification resulted in a pass. All three critical issues had been resolved.
[Figure 26-2] Detailed flow of collaboration based on a shared task list: frontend and backend work complete → QA agent verification → 3 issues identified → fix tasks assigned to respective developers → revalidation → pass.
Throughout this process, the main orchestrator monitored the entire flow and provided status updates, but the communication between the QA agent and the developer agents regarding requested fixes happened directly. This is direct team member-to-member communication, bypassing the main orchestrator.
Team members use a send message tool to communicate with one another. If the prompt specifies "When your work is done, send a message to the frontend developer," the agent delivers that message directly to the team member.
The Collaboration Scenario Between the Refactor Agent and the Test-Writing Agent
Let us trace the workings of an agent team through a concrete scenario.
A user makes a request to the main session: "Refactor this module and add tests."
The main session analyzes the request. Two specialist domains are needed: refactoring and test writing. The main session searches for agents and locates the refactor agent and the test-writing agent.
In the subsidiary agent approach, it would proceed as follows. The main session sends the refactor agent a prompt: "Refactor this module." Simultaneously, it sends the test-writing agent a prompt: "Write tests for this module." The two agents work in parallel. Their respective results return to the main session. The main session combines the two results.
The tests may need to be updated to match the refactored code. This revision would either be done by the main session directly or require calling the test-writing agent again.
In the agent team approach, the flow is different. The main orchestrator assembles a refactor plus tests team. A shared task list is created.
The refactor agent begins work first. It performs function extraction, variable renaming, interface cleanup, and other operations. When the work is complete, it sends a message to the test-writing agent: "Refactoring is complete. The changed function signatures are as follows." The test-writing agent writes tests based on this information. The resulting tests accurately reflect the changed interface.
If some tests fail when executed, the test-writing agent can send a message to the refactor agent: "This function's return type differs from the documentation. Please verify." The refactor agent checks and makes corrections. The tests are run again. This iteration happens within the team itself.
[Figure 26-3] Detailed flow of agent team collaboration scenario: Refactor agent completes work → Conveys changes to test agent → Test writing → If tests fail, test agent sends feedback to refactor agent → Refactor agent fixes → Retest → Pass → Reports completion to main orchestrator.
Using a T-Mux terminal, you can observe this process visually. The screen is split to show each agent's work in real time. You can see the blue agent refactoring code while the green agent waits, and the moment it receives a message, it begins writing tests. You can even send direct messages to a specific agent to provide additional instructions if needed.
Architecture Principles to Consider When Building an Agent Team
Agent teams are powerful, but if misconfigured, you may end up with high costs and confusing results. Here are the principles to follow when assembling a team.
Role Clarity: Assign Each Agent a Distinct Domain
Each agent on the team should have its own files and its own deliverables. If multiple agents modify the same file, there is a risk that they will overwrite one another's work. Specify clearly in the prompt that the frontend developer modifies only frontend files and the backend developer modifies only backend files.
Deliverables must also be defined concretely. "Write good code" is vague. "Implement REST API endpoints and create a test file for each endpoint in the /tests/ folder" is clear. Make it explicit to agents what they must create and where to save it.
Communication Protocol: Design Who Speaks to Whom and When
The fact that agents can communicate freely does not mean you can skip designing a communication structure. Defining the communication flow explicitly in the prompt yields much better results.
"When backend development is complete, deliver the API specification to the frontend developer." "When all development is complete, send the results to the QA agent." "If issues are found in QA, request fixes from the responsible agent for that file." Specifying this explicitly helps agents understand dependencies and proceed through tasks in the correct order.
It is also important to specify the recipient by name. "Send this to another agent" is vague. "Send this to the frontend developer agent" is precise.
Preventing Conflict: Agents Don't Interfere with Each Other
We've already covered file ownership. Beyond that, several conflict prevention strategies exist.
Preapproved Permissions: If agents halt their work each time they need permission checks, the entire workflow slows down. By preapproving specific commands in your project settings or local machine settings, work flows without interruption. Team members inherit permissions from the main session, so setting Bypass Mode in the main session gives all team members the same permissions.
Plan Approval Mode: You can configure team members to draft plans before starting work, then execute only after the main orchestrator approves the plan. Initially, you approve each plan directly, but as you grow familiar with how the team operates, it's practical to delegate approval to the main session. You can also designate one team member to handle plan review and approval exclusively.
Graceful Shutdown: When work ends, the main orchestrator sends a shutdown request to each team member: "Save your work and shut down." A team member can respond "I'm not finished yet" if work is still in progress. The team dissolves only after all members confirm completion. Forcing a shutdown may leave work in a disorganized state, so going through a graceful shutdown procedure is safer.
Team Size and Cost
Each team member in an agent team runs an independent session. With three agents, costs are roughly triple. With five, they're five times higher.
We recommend team sizes of 3 to 5 members. Large agent swarms of 10 or more see costs rise sharply, and coordination complexity increases proportionally.
[Table 25-1] Criteria for Determining Agent Team Suitability
For work that can be processed sequentially, helper agents suffice. If agents don't need to communicate, helper agents are better. If multiple agents must edit the same file, you need to redesign your structure, whether with agent teams or helper agents.
How to Set Up Agent Teams
Agent teams are an experimental feature and are disabled by default. To activate them, add environment variables to your project's .claude/settings.local.json file. Copy the relevant JSON from the Agent Teams page in the Claude Code official documentation and paste it into your settings file.
Prompts that invoke agent teams follow this structure pattern:
1. Set the goal: Specify the goal the entire team must achieve. Since team members wake up with no context, the main session must communicate the goal clearly. 2. Form the team: Specify team size and model, as in "Create a three-member team using the Sonnet model." 3. Define roles: Describe each team member's role, responsibilities, and communication partners in detail. 4.
Define the final deliverable: Specify the final output the main session will receive from the team's work.
[Figure 26-4] Agent Team Prompt Structure: Goal → Team Formation → Role-Specific Instructions (Including Communication Partners) → Final Deliverable Definition]
Running agent teams in a T-Mux terminal lets you observe each agent's work in real time with split-screen views. You can spot agents heading in the wrong direction early and terminate them, preventing wasted costs. Since IDE extensions can't show agents' internal thinking in detail, T-Mux environments are better suited for complex agent team work.
Helper agents are specialists who work independently under the main session's direction. Agent teams are groups that communicate and collaborate toward a shared goal. Both are powerful tools, but they apply to different contexts. Choose helper agents for fast, efficient delegation; choose agent teams when complex interdependencies and high quality are required.
Combining these two structures appropriately for your situation is what makes an effective Claude Code operator, and it forms the foundation for moving to the next stage: designing workflows by weaving skills and agents together.
Attorney Kim Kyung-jin, AI Expert
Specialist in AI Policy and Law · Former Member of the National Assembly · Author of Multiple Books
If this book stayed with you even for a moment, please support it so the next story can reach the world.
(Voluntary support account: NH Bank 302-1096-0948-81 Account holder: Kim Kyung-jin)
Kim Kyung-jin
Attorney · Former Member of the National Assembly · AI Policy Researcher
© 2026 Kim Kyung-jin. All rights reserved.