Lesson 47: Agent Teams and Collaboration

Day 47 of 50 · ~7 min read · Phase 6: Mastery

The Opening Question

So far, you've learned to build individual agents. One agent, one task, one context window.

But some problems are too big or complex for a single agent. Imagine this:

• You need to review code for bugs, security issues, and performance problems
• Each kind of review benefits from different expertise and focus
• Doing them sequentially wastes time
• Trying to do them all in one agent's context dilutes focus

Here's the question: What if you could create multiple specialized agents and have them work together? A bug-reviewer agent, a security-reviewer agent, and a performance-reviewer agent — all working in parallel on your code, then comparing notes?

That's agent teams.

Discovery

Question 1: What's the difference between subagents and agent teams?

You learned about subagents in Lesson 35. Let's clarify the difference.

Subagents (from Claude Code):

• Created on-demand from the main session
• Work autonomously on a task
• Return a summary to the main session
• Hierarchical: parent → children

Agent teams (with the Agent SDK):

• Multiple independent agent instances
• Can be peers (not hierarchical)
• Can communicate with each other
• Share a task list or shared goal
• Coordinate without a "parent" directing them

Think of it like this:

Subagent model: Manager asks worker to do something. Worker does it alone. Worker reports back.

Team model: Three specialists work on the same problem in parallel, discuss findings, synthesize results.

Pause and think: When would you want peer collaboration vs. hierarchical delegation?

Question 2: How do agents in a team communicate?

Agents in a team need a way to share information and coordinate. Here are common patterns:

Pattern 1: Shared message log

All agents write to a shared file or database. Each agent:

• Reads the current state
• Does its work
• Writes findings to the log
• Other agents see the updates

Shared Log:
[09:00] BugReviewer: Started reviewing auth.js
[09:05] SecurityReviewer: Found SQL injection risk in db.js line 42
[09:10] BugReviewer: Completed. Found 3 logical errors in auth.js
[09:15] PerformanceReviewer: Memory leak in cache.js — holding 1000s of references
[09:20] Synthesizer: Reading logs, compiling final report

Pattern 2: Peer messaging

Agents can send messages to each other directly:

// Agent A finds something and tells Agent B
await agentB.receiveMessage({
  from: "securityReviewer",
  content: "Found XSS vulnerability in templates. Check line 42 of template.js"
});

Pattern 3: Task queue

There's a shared queue of tasks. Agents pull tasks, work on them, report results:

Task Queue:
[ ] Review auth.js for bugs
[ ] Review auth.js for security
[ ] Review auth.js for performance
[ ] Review api.js for bugs
...

Agent1 pulls "Review auth.js for bugs" and works on it
Agent2 pulls "Review auth.js for security" and works on it
Agent3 pulls "Review auth.js for performance" and works on it

Question 3: What are good use cases for teams?

Some problems benefit from teams. Others don't. Here's when teams shine:

Good for teams:

• Multi-perspective review — Code review that needs bug, security, and style analysis
• Parallel research — Finding information across your codebase and external sources
• Specialization — Frontend expert, backend expert, DevOps expert reviewing a change
• Division of labor — One agent finds issues, another drafts fixes
• Brainstorming — Multiple agents suggest solutions to the same problem
• Cross-checking — One agent verifies another's findings

Not ideal for teams:

• Tightly coupled work — When every step depends on the previous one
• Sequential decisions — When you need human judgment between steps
• Low-complexity tasks — The overhead isn't worth it

The key question: Can the work be divided into independent parallel tasks that a human would coordinate?

If yes, teams. If no, stick with one agent.

Question 4: How do you orchestrate a team?

Someone (or something) needs to coordinate the agents. Here are patterns:

Pattern 1: Central orchestrator

One agent (or your code) manages the team:

// You (the coordinator) create and manage the team
const bugReviewer = new Agent({
  system: "You are a bug reviewer...",
  tools: [...codeReadingTools]
});

const securityReviewer = new Agent({
  system: "You are a security reviewer...",
  tools: [...codeReadingTools]
});

// You run them in parallel
const bugResults = await bugReviewer.run("Review this code for bugs");
const securityResults = await securityReviewer.run("Review this code for security");

// You synthesize results
console.log("Bug findings:", bugResults);
console.log("Security findings:", securityResults);

Pattern 2: Self-organizing team

Agents coordinate themselves through shared state:

// Agents read a shared goal and shared findings
const sharedGoal = "Review code in /src";
const sharedFindings = []; // All agents append here

// Each agent:
// 1. Reads the shared goal
// 2. Checks what others have already done
// 3. Does something complementary
// 4. Updates shared findings

// No central coordinator needed

Pattern 3: LLM orchestrator

A master agent directs the team:

// The orchestrator agent decides who should do what
const orchestrator = new Agent({
  system: `You are a team lead. You have 3 specialists:
    - BugReviewer (finds logical errors)
    - SecurityReviewer (finds security vulnerabilities)  
    - PerformanceReviewer (finds performance issues)
    
  For each task, delegate to the right specialists, 
  then synthesize their findings into a report.`,
  tools: [delegateToAgent]
});

await orchestrator.run("Review my codebase comprehensively");

The Insight

Agent teams extend single-agent capabilities by dividing complex problems into parallel specialized tasks. Teams communicate through shared state, messages, or task queues. The coordination style depends on your problem: central orchestration, self-organization, or LLM-directed delegation. The tradeoff is complexity for parallelism and specialization.

The mental model: An agent team is like hiring a consulting firm. Instead of one consultant, you hire three specialists (backend expert, frontend expert, DevOps expert). They work in parallel, share findings, and someone (a team lead or a structured process) synthesizes the results. More parallelism, more expertise, but more coordination overhead.

Try It

Build a team of two agents that review code together.

1. Define two agents:

   const bugReviewer = new Agent({
     system: `You are a bug reviewer. Find logical errors, off-by-one bugs, 
              null pointer issues, and incorrect algorithms in code.`,
     tools: [readFile, bash]
   });
   
   const styleReviewer = new Agent({
     system: `You are a style reviewer. Find naming inconsistencies, 
              missing documentation, and code organization issues.`,
     tools: [readFile]
   });
   

2. Create a shared log:

   const findings = [];
   
   // Both agents can append findings
   bugReviewer.addTool({
     name: "report_finding",
     description: "Report a finding to the shared log",
     handler: async (input) => {
       findings.push({ type: "bug", ...input });
     }
   });
   
   styleReviewer.addTool({
     name: "report_finding",
     description: "Report a finding to the shared log",
     handler: async (input) => {
       findings.push({ type: "style", ...input });
     }
   });
   

3. Run them in parallel:

   const [bugResults, styleResults] = await Promise.all([
     bugReviewer.run("Review src/app.js"),
     styleReviewer.run("Review src/app.js")
   ]);
   

4. Synthesize:

   console.log("All findings:", findings);
   // Agent can read shared findings and create a report
   

Key Concepts Introduced

Bridge to Lesson 48

You now understand how agents can work together. But building agents is just the technical side. The other side is sharing agents with your team.

Tomorrow's question: How do you package agents and tools so others can use them? What's the relationship between plugins, skills, and the Agent SDK?

We'll explore plugins as the distribution mechanism for agents and agent tools.

← Back to Curriculum · Lesson 48 →