Multi-Agent Architecture

Real-world tasks often require multiple areas of expertise. Rather than building one monolithic agent that tries to do everything, ThePopeBot supports a multi-agent architecture where specialized agents collaborate as a team.

The multi-agent system consists of three key components:

Orchestrator — Receives the initial task, breaks it down, and assigns subtasks
Specialist Agents — Domain experts that handle specific subtasks
Communication Bus — The message passing system that connects agents

                    ┌──────────────┐
  User Request ───▶ │ Orchestrator │
                    └──────┬───────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │  Coder   │ │ Reviewer │ │ Tester   │
        └──────────┘ └──────────┘ └──────────┘
              │            │            │
              └────────────┼────────────┘
                           ▼
                    ┌──────────────┐
                    │   Response   │
                    └──────────────┘

Role Assignment

Each agent in the team has a clearly defined role. Define your team in config/teams.yaml:

teams:
  development:
    name: "Development Team"
    orchestrator: "lead"
    agents:
      lead:
        role: "Team Lead & Orchestrator"
        responsibilities:
          - Break down complex tasks into subtasks
          - Assign work to specialist agents
          - Aggregate results and resolve conflicts
          - Make final decisions on approach
        model: "gpt-4"
        temperature: 0.3

      coder:
        role: "Implementation Specialist"
        responsibilities:
          - Write production-quality code
          - Implement features and fix bugs
          - Follow coding standards and patterns
        tools: ["filesystem", "git", "search"]

      reviewer:
        role: "Code Quality Guardian"
        responsibilities:
          - Review code for bugs and security issues
          - Enforce coding standards
          - Suggest improvements
        tools: ["git", "filesystem"]

      tester:
        role: "Quality Assurance"
        responsibilities:
          - Write unit and integration tests
          - Verify edge cases and error handling
          - Report test coverage metrics
        tools: ["filesystem", "test-runner"]

Role Design Principles

When defining roles, follow these guidelines:

Single Responsibility: Each agent should have one primary area of expertise
Clear Boundaries: Define what each agent should and should not do
Complementary Skills: Agents should cover different aspects of the task
Minimal Overlap: Reduce redundancy between agent responsibilities

Task Delegation Patterns

The orchestrator uses several patterns to delegate work effectively:

Sequential Pipeline

Tasks flow from one agent to the next in order:

const pipeline = {
  pattern: 'sequential',
  steps: [
    { agent: 'coder', task: 'Implement the feature' },
    { agent: 'reviewer', task: 'Review the implementation' },
    { agent: 'coder', task: 'Address review feedback' },
    { agent: 'tester', task: 'Write and run tests' },
  ],
};

Parallel Fan-Out

Multiple agents work simultaneously on independent subtasks:

const parallel = {
  pattern: 'fan-out',
  tasks: [
    { agent: 'coder', task: 'Implement the API endpoint' },
    { agent: 'coder', task: 'Implement the database schema' },
    { agent: 'tester', task: 'Prepare the test plan' },
  ],
  merge: 'orchestrator',  // The orchestrator merges results
};

Iterative Review Loop

Agents iterate until a quality threshold is met:

const iterative = {
  pattern: 'review-loop',
  maxIterations: 3,
  steps: {
    produce: { agent: 'coder', task: 'Write the code' },
    review: { agent: 'reviewer', task: 'Review the code' },
    exitCondition: 'review.approved === true',
  },
};

Inter-Agent Communication

Agents communicate through a structured message bus. Each message includes context, data, and metadata:

interface AgentMessage {
  from: string;         // Sending agent ID
  to: string;           // Receiving agent ID
  type: 'task' | 'result' | 'feedback' | 'question';
  payload: {
    content: string;    // The main message
    files?: FileRef[];  // Referenced files
    data?: any;         // Structured data
  };
  metadata: {
    taskId: string;
    priority: 'low' | 'medium' | 'high';
    timestamp: number;
  };
}

Communication Patterns

Direct Messaging: One agent sends a message directly to another:

await bus.send({
  from: 'reviewer',
  to: 'coder',
  type: 'feedback',
  payload: {
    content: 'The error handling in auth.ts needs improvement',
    files: [{ path: 'src/auth.ts', lines: [42, 58] }],
  },
});

Broadcast: An agent sends a message to all team members:

await bus.broadcast({
  from: 'lead',
  type: 'task',
  payload: {
    content: 'New priority: security audit on all API endpoints',
  },
});

Request-Reply: An agent asks a question and waits for an answer:

const answer = await bus.ask({
  from: 'coder',
  to: 'reviewer',
  type: 'question',
  payload: {
    content: 'Should I use JWT or session-based auth for this endpoint?',
  },
});

Example: Code Review Pipeline

Let us put it all together with a practical example — a fully automated code review pipeline that triggers when a pull request is opened.

Pipeline Definition

pipelines:
  code-review:
    trigger:
      channel: webhook
      event: pull_request.opened
    team: development
    steps:
      - name: "Fetch PR Details"
        agent: lead
        action: "Fetch PR #{event.prNumber} and analyze the scope"

      - name: "Code Review"
        agent: reviewer
        action: "Review the changed files for bugs, security issues, and style"
        input: "previous.prDetails"

      - name: "Test Coverage Check"
        agent: tester
        action: "Check if tests exist for the changed code and suggest missing tests"
        input: "previous.prDetails"
        parallel: true  # Runs alongside code review

      - name: "Summarize Findings"
        agent: lead
        action: "Aggregate review and test results into a single PR comment"
        input: "all.results"

      - name: "Post Comment"
        action: "Post the summary as a GitHub PR comment"
        output:
          channel: webhook
          target: github

How It Works

A developer opens a pull request on GitHub
The webhook adapter receives the event and triggers the pipeline
The lead agent fetches the PR details and determines the scope
The reviewer and tester work in parallel — the reviewer checks code quality while the tester evaluates test coverage
The lead agent collects all findings and produces a unified summary
The summary is posted as a comment on the pull request

Expected Output

The pipeline produces a structured review comment like this:

## Automated Review Summary

### Code Review (by Reviewer Agent)
- **2 issues found**: 1 high, 1 medium severity
- High: SQL injection risk in `src/db/queries.ts:34`
- Medium: Missing null check in `src/utils/parse.ts:12`

### Test Coverage (by Tester Agent)
- **Coverage**: 73% (target: 80%)
- Missing tests for: `src/db/queries.ts`, `src/utils/parse.ts`
- 3 test suggestions attached

### Recommendation
**Request changes** -- please address the high-severity SQL injection
issue before merging.

This pipeline demonstrates the power of multi-agent collaboration: each agent contributes its specialized expertise, and the orchestrator ensures the results are coherent and actionable.

Agent Team Collaboration