Complete Guide To Claude Code Agent Teams
Agent Teams are one of the most advanced features inside Claude Code. Instead of using one AI agent to complete a task, you create multiple specialized AI teammates that work together in parallel under one orchestrator.
This system allows you to build:
• full stack apps
• landing pages
• APIs
• testing pipelines
• research systems
• documentation workflows
• QA automation
• multi department AI teams
The major difference is that these AI agents communicate with each other, share tasks, review each other’s work, and collaboratively solve problems.
What Agent Teams Actually Are
An Agent Team is a group of AI agents managed by one main Claude session.
The main Claude session acts like:
• a project manager
• a team lead
• an orchestrator
The orchestrator:
• creates teammates
• assigns responsibilities
• manages shared tasks
• reviews outputs
• coordinates communication
Each teammate becomes a specialized AI worker with its own responsibility.
Example:
• Frontend Developer
• Backend Developer
• QA Engineer
All of them work simultaneously instead of sequentially.
How Agent Teams Work
When you create a team, Claude:
- Creates the team
- Creates multiple specialized agents
- Assigns tasks to each agent
- Allows agents to message each other
- Maintains a shared task list
- Collects outputs from all teammates
The agents continuously collaborate during the project lifecycle.
For example:
• Backend dev finishes API work
• Sends API structure to frontend dev
• Frontend dev integrates it
• QA agent finds issues
• QA sends fixes back to frontend and backend
This creates iterative quality loops automatically.
Difference Between Agent Teams And Sub Agents
This is one of the most important concepts from the transcript.
Sub Agents
Sub agents:
• work independently
• complete isolated tasks
• return results to the main session only
They do not collaborate with each other.
Agent Teams
Agent teams:
• collaborate continuously
• communicate directly
• share dependencies
• coordinate workflows
• revise each other’s work
This makes them far more useful for complex systems.
Why Agent Teams Are Powerful
The transcript demonstrated building an AI startup landing page using:
• a frontend developer
• a backend developer
• a QA engineer
The system:
• generated copywriting
• created animations
• designed the interface
• built functionality
• tested quality
• fixed bugs automatically
All from one simple prompt.
The most important part was the QA loop:
• QA found critical issues
• Main agent reassigned work
• Frontend and backend fixed problems
• QA rechecked everything
• Final result passed validation
This mimics a real software development team.
Step 1: Enable Agent Teams
Agent Teams are disabled by default because the feature is experimental.
To enable them:
- Open your Claude Code project
- Create or edit: settings.local.json
- Add the Agent Teams environment variable from Claude’s documentation
This activates Agent Teams for the project.
Step 2: Create A Reference Guide Inside Your Project
One of the smartest workflows shown in the transcript was generating local documentation for Agent Teams.
The process:
• copy the official Agent Teams documentation URL
• ask Claude to generate a master reference guide
• store it inside a docs folder
This gives Claude:
• fast local access to documentation
• reusable references
• better planning capabilities
This technique also works for:
• APIs
• MCP servers
• frameworks
• SDKs
• internal company systems
Step 3: Understand The Prompt Structure
Prompting Agent Teams correctly is critical.
The recommended structure is:
- Define the overall goal
- Define the number of teammates
- Define each role
- Define each responsibility
- Define communication flow
- Define final deliverables
Example Team Structure
A full stack app example from the transcript included:
Backend Developer
Responsible for:
• REST API
• database logic
• server functionality
Frontend Developer
Responsible for:
• React frontend
• UI integration
• API consumption
QA Agent
Responsible for:
• testing
• bug detection
• validation
• pass/fail reporting
Why Goals Matter
Agents wake up with zero prior context.
The orchestrator only gives them:
• their task
• the project goal
• teammate information
That means goals must clearly explain:
• what is being built
• what success looks like
• what final output is expected
Example:
“Build a working full stack app with users and post functionality.”
Good goals dramatically improve coordination.
How Agent Communication Works
One major advantage is direct teammate messaging.
Example:
• Backend dev finishes APIs
• Sends endpoints to frontend dev
• Frontend dev updates UI
• QA agent validates integration
The orchestrator does not need to manually relay every message.
This creates faster workflows and more realistic collaboration.
Step 4: Assign Clear Ownership
Every agent should own:
• separate files
• separate responsibilities
• separate outputs
This prevents:
• overwriting work
• conflicts
• duplicated effort
Bad setup:
• all agents editing the same files
Good setup:
• frontend owns UI files
• backend owns server files
• QA owns reports and tests
Step 5: Use Parallel Execution Properly
Agent Teams work best when agents operate simultaneously.
Good use cases:
• frontend and backend developing together
• research and analysis running simultaneously
• QA validating while implementation happens
Bad use cases:
• purely sequential workflows
• simple step by step automations
If tasks must happen strictly one after another, sub agents are often better.
Step 6: Use TMUX For Maximum Visibility
The transcript strongly recommended using TMUX terminals.
TMUX allows you to:
• view all agents simultaneously
• watch reasoning live
• inspect conversations
• manually message teammates
• approve tasks directly
Instead of only seeing the orchestrator, you can monitor:
• frontend agent
• backend agent
• QA agent
• strategist
• researcher
• critic
all independently.
This gives much deeper control over the workflow.
Step 7: Understand Team Status Updates
The orchestrator continuously monitors:
• task completion
• teammate communication
• QA results
• dependencies
The main agent updates the user during execution.
Example:
“Backend dev sent work to QA.”
“QA found three critical issues.”
“Sending work back for revision.”
This creates transparent multi agent workflows.
Step 8: Use QA Agents Aggressively
QA agents were one of the strongest patterns demonstrated.
The QA agent:
• reviews deliverables
• identifies issues
• validates outputs
• enforces quality standards
Without QA agents:
• mistakes pass through
• bugs remain unresolved
• outputs become inconsistent
QA agents create automatic refinement loops.
Step 9: Use Plan Approval Mode
Plan Approval Mode allows:
• agents to propose plans first
• orchestrator to review plans
• humans to approve execution
This dramatically improves:
• reliability
• structure
• coordination
Especially for large projects.
Step 10: Understand Shared Resources
All teammates inherit:
• project permissions
• MCP servers
• files
• local documentation
• environment settings
This means all teammates can:
• access tools
• use APIs
• read project files
• reference docs
without needing reconfiguration.
Step 11: Avoid Common Mistakes
Mistake 1: Too Many Agents
Large swarms:
• cost more
• slow execution
• create confusion
Recommended:
• 2 to 5 teammates maximum
Mistake 2: Shared File Ownership
Multiple agents editing identical files creates:
• conflicts
• overwritten work
• inconsistent outputs
Always define ownership.
Mistake 3: Weak Deliverables
Vague prompts create vague outputs.
Always specify:
• exact deliverables
• reports
• documentation
• tests
• outputs
Mistake 4: Missing Dependencies
If an agent appears idle:
• assign explicit responsibilities
• create teammate dependencies
• define communication requirements
Step 12: Understand Shutdown Behavior
At project completion:
• orchestrator shuts teammates down cleanly
• agents save work
• unfinished tasks are finalized
This prevents:
• lost outputs
• corrupted state
• incomplete files
The shutdown process is collaborative, not forced.
When To Use Agent Teams
Agent Teams work best for:
• large systems
• collaborative workflows
• high quality outputs
• iterative refinement
• multi department tasks
Perfect examples:
• SaaS apps
• AI startups
• research systems
• enterprise automation
• testing pipelines
When NOT To Use Agent Teams
Avoid Agent Teams for:
• simple tasks
• sequential workflows
• tiny scripts
• single file edits
• low complexity automations
In those situations:
• sub agents
or
• one Claude session
are usually more efficient.
Cost Considerations
Every active teammate consumes tokens independently.
Example:
• 3 agents = roughly 3x token usage
• 5 agents = roughly 5x token usage
This is why smaller focused teams work best.
The transcript specifically recommended:
• 2 to 5 teammates maximum
for most workflows.
Best Team Patterns
Software Team
- Frontend Dev
• Backend Dev
• QA Engineer
Research Team
- Researcher
• Strategist
• Critic
Content Team
- Writer
• Editor
• Fact Checker
Product Team
- Product Manager
• UX Designer
• QA Reviewer
Final Workflow Pattern
A strong Agent Team workflow usually looks like this:
- Define project goal
- Create teammates
- Assign responsibilities
- Enable communication
- Run work in parallel
- Validate through QA
- Revise issues
- Finalize deliverables
- Shutdown teammates cleanly
Final Takeaway
Agent Teams transform Claude Code from:
• a single AI assistant
into:
• a coordinated AI workforce
The biggest advantages are:
• parallel execution
• teammate collaboration
• iterative QA loops
• higher quality outputs
• specialized expertise
When used correctly, Agent Teams can simulate:
• engineering teams
• research departments
• QA pipelines
• startup workflows
inside a single Claude Code session.
This guide breaks down the exact workflow used in the transcript to build a production ready AI voice agent using:
- 11Labs
• Twilio
• Make.com
• GPT prompts
• Knowledge bases
• Webhooks
The final result:
An AI receptionist that:
• answers calls
• sounds natural
• captures leads
• handles FAQs
• sends emails automatically
• works 24/7
Step 1: Create Your 11Labs Agent
Go to 11Labs and create an account.
Inside the dashboard:
Agents → Create New Agent
Choose:
• Business Agent
• Customer Support Template
If you already have a business website, paste the URL into the setup field.
11Labs will scrape the website and generate:
• a starter system prompt
• company information
• FAQs
• business context
This saves a lot of setup time.
Example:
If you are building a gym receptionist, the AI will automatically learn:
• membership plans
• gym timings
• services
• location details
Step 2: Define The Agent Goal
Give the agent a simple objective.
Example:
“I want you to answer after hours calls, help customers with gym questions, and collect lead information for new memberships.”
Keep this short and specific.
The clearer the goal, the better the responses.
Step 3: Enable Expressive Voice Mode
This is one of the biggest reasons the voice sounded realistic in the transcript.
Inside Voice Settings:
Enable:
• Expressive Mode
• V3 Conversational Alpha
This unlocks:
• emotional tone
• breathing sounds
• laughter
• pauses
• realistic pacing
Recommended voices from the transcript:
• Amy
• Jonathan
These voices sound more natural than standard AI voices.
Step 4: Configure The AI Brain
The LLM controls how smart and responsive the voice agent feels.
Inside Model Settings:
Option 1: Fastest Response
Use:
11Labs Ultra Low Latency Model
Best for:
• fast conversations
• customer support
• natural interruptions
Latency:
~187ms
This makes conversations feel instant.
Option 2: Smarter Responses
Use:
GPT 4.1
Best for:
• tool calling
• CRM workflows
• advanced logic
Slightly slower, but smarter.
Step 5: Build A Strong System Prompt
A good prompt makes the difference between:
• robotic AI
• production ready AI
The transcript uses a 4 part structure:
1. Role
Tell the AI who it is.
Example:
“You are Amy, a friendly gym receptionist for Victory Fitness.”
2. Personality
Define tone and behavior.
Example:
• warm
• calm
• conversational
• concise
Avoid long robotic answers.
3. Goals
Tell the AI what success looks like.
Example:
• greet callers
• answer questions
• explain memberships
• collect contact details
• help book consultations
4. Rules
Prevent hallucinations.
Example:
“If information does not exist in the knowledge base, politely say you do not know.”
This is critical.
Without this, AI starts inventing answers.
Step 6: Make The Agent Sound Human
This was one of the biggest optimizations shown in the transcript.
Add instructions like:
- use filler words naturally
• pause occasionally
• use conversational speech
• avoid overexplaining
Example additions:
“Use phrases like:
• uh
• hmm
• you know
naturally during conversation.”
Also add:
“Use exhale and clears throat tags occasionally.”
This creates:
• breathing sounds
• realistic pauses
• human imperfections
Which dramatically improves realism.
Step 7: Configure The First Message
Default greetings usually sound robotic.
Instead of:
“Hello, how may I assist you today?”
Use something natural:
“Thanks for calling Victory Fitness. I’m Amy. How can I help you today?”
You can even add:
[clears throat]
This small detail makes the interaction feel much more human.
Step 8: Add A Knowledge Base
The system prompt alone is not enough.
You need a proper knowledge base.
Inside 11Labs:
Add Document → Website URL
Then:
• crawl the website
• enable RAG
• set crawl depth around 3
This allows the AI to search real business information during calls.
Example:
The AI can answer:
• pricing
• opening hours
• services
• policies
• membership details
without hallucinating.
Step 9: Enable Multilingual Support
11Labs supports multiple languages extremely well.
Inside Language Settings:
Add:
• Spanish
• Japanese
• Armenian
• Greek
• Chinese
• others
Then enable:
Detect Language
Now the AI automatically switches languages mid conversation.
This is useful for:
• local businesses
• international support
• multilingual customer service
Step 10: Connect A Real Phone Number
To make the agent callable from a real phone:
Use Twilio.
Inside 11Labs:
Phone Numbers → Import Number
Assign the number to your AI agent.
Now anyone can call the AI directly.
Step 11: Connect Make.com For Automation
This is how the AI triggers actions after calls.
Inside Make.com:
Create:
Webhook → Copy URL
Paste the webhook URL into:
11Labs → Post Call Webhook
This creates a live connection between:
• 11Labs
• Make.com
Step 12: Extract Important Caller Data
Inside 11Labs:
Add Data Points
Examples:
• caller name
• phone number
• membership interest
Example instruction:
“Extract the caller’s exact email address.”
11Labs runs AI extraction after the call ends.
Step 13: Send Automated Emails
Inside Make.com:
Add Gmail Module
Create an automated email containing:
• caller name
• phone number
• request summary
Example:
“New membership request from Mark Tomlin.”
This instantly notifies the business owner.
Step 14: Add Filters
You do not want emails after every call.
Add filters inside Make.com.
Example:
Only send email if:
Membership Interest = Yes
This keeps workflows clean.
Step 15: Test Everything
11Labs includes testing tools for:
- conversation testing
• simulation testing
• workflow testing
• tool testing
Test:
• FAQs
• lead capture
• multilingual switching
• interruptions
• call transfers
This step is important before production deployment.
Final Tech Stack
Core stack used in the transcript:
- 11Labs → voice AI
• GPT 4.1 → intelligence
• Twilio → phone system
• Make.com → automation
• Knowledge Base → business information
• Webhooks → integrations
