Source Code

The runnable TypeScript source for this lesson is in lessons/17-multi-agent/

Lesson 17: Multi-Agent Coordination¶

Multiple specialized agents working together as a team

What You'll Learn¶

Agent Roles: Specialization through defined roles
Communication: Inter-agent message passing
Consensus Protocols: Reaching agreement when agents disagree
Orchestration: Coordinating task execution
Coordination Patterns: Common team structures

Why This Matters¶

Single agents struggle with complex tasks:

Single Agent:
  One agent tries to be an expert at everything
  - Writes code
  - Reviews its own code
  - Tests its own code
  Problem: Self-review bias, context switching overhead

Multi-Agent Team:
  Specialized agents collaborate
  Architect --> Coder --> Reviewer --> Tester

  Benefits:
  - Fresh perspectives (no self-review bias)
  - Specialized prompts for each role
  - Parallel execution possible
  - Checks and balances

Key Concepts¶

Agent Roles¶

interface AgentRole {
  name: string;           // "Coder", "Reviewer", etc.
  description: string;
  capabilities: string[]; // ["write_code", "review_code"]
  systemPrompt: string;   // Role-specific instructions
  tools: string[];        // ["read_file", "write_file"]
  authority: number;      // For decision-making priority
}

Communication Channel¶

interface Message {
  from: string;           // Sender agent ID
  to: string;             // Recipient or "all"
  type: MessageType;      // "task_assignment", "opinion", etc.
  content: string;
  timestamp: Date;
}

// Message types
type MessageType =
  | 'task_assignment'
  | 'task_complete'
  | 'opinion'
  | 'vote'
  | 'review_request'
  | 'review_feedback';

Consensus Strategies¶

Strategy    | How it works              | Best for
------------+---------------------------+--------------------
Authority   | Highest authority decides | Clear hierarchy
Voting      | Majority wins             | Democratic teams
Unanimous   | All must agree            | Critical decisions
Debate      | Discuss until agreement   | Complex tradeoffs
Weighted    | confidence x authority    | Balanced decisions

Files in This Lesson¶

File	Purpose
`types.ts`	Agent, team, and coordination types
`agent-roles.ts`	Predefined roles (Coder, Reviewer, etc.)
`communication.ts`	Inter-agent messaging
`consensus.ts`	Agreement protocols
`orchestrator.ts`	Task coordination
`main.ts`	Demonstration of all concepts

Running This Lesson¶

npm run lesson:17

Code Examples¶

Creating Agents¶

import { createAgent, CODER_ROLE, REVIEWER_ROLE } from './agent-roles.js';

const coder = createAgent(CODER_ROLE);
const reviewer = createAgent(REVIEWER_ROLE);

console.log(coder.role.capabilities); // ['write_code', 'refactor', ...]

Building a Team¶

import { TeamBuilder, createAgentsFromRoles, DEV_TEAM_ROLES } from './orchestrator.js';

const team = new TeamBuilder()
  .setName('Development Team')
  .addAgents(createAgentsFromRoles(DEV_TEAM_ROLES))
  .setConsensusStrategy('voting')
  .setParallelExecution(true)
  .build();

Communication¶

import { createChannel, createTaskAssignment } from './communication.js';

const channel = createChannel();

// Subscribe to messages
channel.subscribe((msg) => {
  console.log(`${msg.from} -> ${msg.to}: ${msg.content}`);
});

// Send task assignment
await channel.send(
  createTaskAssignment('orchestrator', 'agent-coder-1', 'task-1', 'Implement login')
);

Reaching Consensus¶

import { ConsensusEngine, createOpinion } from './consensus.js';

const engine = new ConsensusEngine('voting');

const opinions = [
  createOpinion('coder', 'Use React', 'Popular framework', 0.8),
  createOpinion('reviewer', 'Use Vue', 'Simpler API', 0.7),
  createOpinion('tester', 'Use React', 'Better testing tools', 0.6),
];

const decision = await engine.decide(opinions, team.agents);

console.log(decision.decision);  // 'Use React'
console.log(decision.support);   // 0.7 (support level)
console.log(decision.dissent);   // [{ agentId: 'reviewer', ... }]

Orchestrating Tasks¶

import { createOrchestrator, createTeamTask } from './orchestrator.js';

const orchestrator = createOrchestrator('voting');

const task = createTeamTask('Implement authentication', {
  requiredCapabilities: ['write_code', 'review_code'],
  priority: 'high',
  subtasks: [
    'Design auth flow',
    'Implement endpoints',
    'Write tests',
  ],
});

// Assign to appropriate agents
await orchestrator.assignTask(task, team);

// Execute with coordination
const result = await orchestrator.coordinate(task, team);

console.log(result.success);
console.log(result.agentResults);

Coordination Patterns¶

Pipeline (Sequential)¶

Architect -> Coder -> Reviewer -> Tester

Best for: Waterfall-style workflows

Parallel with Merge¶

+- Coder A -+
             +-> Reviewer
+- Coder B -+

Best for: Parallelizable subtasks

Hub and Spoke¶

         +- Coder
Manager -+- Reviewer
         +- Tester

Best for: Centralized coordination

Consensus Strategies¶

Authority¶

Highest authority agent decides:

const engine = new ConsensusEngine('authority');
// Architect (authority: 5) overrides Coder (authority: 3)

Voting¶

Majority wins:

const engine = new ConsensusEngine('voting');
// 2 votes for React, 1 for Vue -> React wins

Weighted¶

Votes weighted by confidence x authority:

const engine = new ConsensusEngine('weighted');
// Higher confidence + higher authority = more influence

Debate¶

Agents can change opinions based on others' reasoning:

const engine = new ConsensusEngine('debate', 3); // 3 rounds max
// Lower confidence agents may be persuaded by higher confidence ones

Trade-offs¶

Aspect	Single Agent	Multi-Agent
Quality	Self-review bias	Fresh perspectives
Speed	No coordination overhead	Parallel execution possible
Cost	1 LLM call	Multiple LLM calls
Complexity	Simple	Coordination needed
Robustness	Single point of failure	Redundancy

Best Practices¶

Define Clear Roles¶

Each role should have distinct capabilities
Avoid overlapping responsibilities
Set appropriate authority levels

Minimize Communication¶

Only essential messages
Batch related communications
Use efficient message formats

Choose Right Consensus¶

Authority for speed
Voting for buy-in
Debate for complex decisions

Handle Failures¶

Agents can fail or timeout
Have fallback strategies
Log decisions for debugging

Advanced: Agent Registry¶

The production agent implements a full AgentRegistry system for managing spawnable agents. This goes beyond static roles to support user-defined agents, hot-reloading, and natural language-based routing.

Agent Definition¶

interface AgentDefinition {
  name: string;              // Unique identifier
  description: string;       // Human-readable description
  systemPrompt: string;      // Role-specific instructions
  tools?: string[];          // Whitelist of tool names (all if omitted)
  model?: 'fast' | 'balanced' | 'quality' | string;
  maxTokenBudget?: number;
  maxIterations?: number;
  capabilities?: string[];   // Keywords for NL matching
  tags?: string[];           // Tags for discovery
}

Built-in Agents¶

const BUILTIN_AGENTS: AgentDefinition[] = [
  {
    name: 'researcher',
    description: 'Explores codebases and gathers information',
    systemPrompt: `You are a code researcher. Your job is to:
- Explore codebases thoroughly
- Find relevant files and functions
- Summarize code structure and patterns`,
    tools: ['read_file', 'list_files', 'glob', 'grep'],
    model: 'fast',
    maxTokenBudget: 50000,
    capabilities: ['explore', 'search', 'find', 'understand'],
  },
  {
    name: 'coder',
    description: 'Writes and modifies code',
    tools: ['read_file', 'write_file', 'edit_file', 'bash'],
    model: 'balanced',
    capabilities: ['write', 'implement', 'fix', 'create'],
  },
  {
    name: 'reviewer',
    description: 'Reviews code for quality, bugs, and security',
    tools: ['read_file', 'list_files', 'glob', 'grep'],
    model: 'quality',
    capabilities: ['review', 'check', 'audit', 'verify'],
  },
  // ... more built-in agents
];

User-Defined Agents¶

Users can define custom agents in .agents/ directory using YAML:

# .agents/security-reviewer.yaml
name: security-reviewer
description: Reviews code for security vulnerabilities
systemPrompt: |
  You are a security expert. Focus on:
  - Injection vulnerabilities (SQL, XSS, command)
  - Authentication/authorization issues
  - Sensitive data exposure
  - Known CVEs in dependencies
tools: [read_file, grep, glob, list_files]
model: quality
maxTokenBudget: 80000
capabilities: [security, vulnerability, audit, cve]
tags: [security, review, audit]

Auto-Routing by Query¶

// Route task to best agent based on description
async function routeToAgent(task: string, registry: AgentRegistry) {
  const matches = registry.findMatchingAgents(task);

  if (matches.length === 0) {
    // Default to coder agent
    return registry.getAgent('coder');
  }

  // Use top match
  return matches[0];
}

// Example usage
const agent = await routeToAgent('review this code for security issues', registry);
// -> Returns security-reviewer (matches 'review' and 'security' capabilities)

const agent2 = await routeToAgent('explore the authentication module', registry);
// -> Returns researcher (matches 'explore' capability)

Next Steps¶

In Lesson 18: ReAct Pattern, we'll explore how agents can think explicitly: - Structured reasoning traces - Thought -> Action -> Observation loops - Better tool use decisions