Multi-Agent Patterns

✓ Fresh · 2026-02-24

Pi supports multiple multi-agent patterns through extensions. These enable sophisticated orchestration where multiple agent instances collaborate to solve complex tasks.

Pattern Overview

Agent Teams (Dispatcher Pattern)

The agent-team.ts extension implements a dispatcher pattern where a primary agent evaluates requests and delegates to specialists.

How It Works

1. The primary agent receives the user's request
2. It evaluates which specialist is best suited
3. It delegates via the dispatch_agent tool
4. The specialist completes the work and returns the result
5. The primary agent presents the final answer

Configuration

Teams are defined in .pi/agents/teams.yaml:

teams:
  - name: "fullstack"
    agents:
      - name: "frontend"
        system: "You are a frontend specialist. Expert in React, CSS, and accessibility."
        triggers:
          - "UI"
          - "component"
          - "CSS"
          - "styling"
      - name: "backend"
        system: "You are a backend specialist. Expert in APIs, databases, and server architecture."
        triggers:
          - "API"
          - "database"
          - "server"
          - "endpoint"
      - name: "devops"
        system: "You are a DevOps specialist. Expert in CI/CD, Docker, and infrastructure."
        triggers:
          - "deploy"
          - "Docker"
          - "CI/CD"
          - "infrastructure"

Running

pi -e extensions/agent-team.ts

Agent Chains (Sequential Pipeline)

The agent-chain.ts extension implements sequential pipelines where each agent's output feeds into the next.

How It Works

1. Agent 1 receives the initial prompt
2. Agent 1's output becomes $INPUT for Agent 2
3. Agent 2's output becomes $INPUT for Agent 3
4. And so on through the chain

Variables

Variable	Contains
$INPUT	Output from the previous agent in the chain
$ORIGINAL	The original user prompt (available to all agents)

Configuration

Chains are defined in .pi/agents/agent-chain.yaml:

chains:
  - name: "plan-build-review"
    steps:
      - agent: "planner"
        system: "You are a software architect. Create a detailed implementation plan."
      - agent: "builder"
        system: "You are a senior developer. Implement the plan from $INPUT."
      - agent: "reviewer"
        system: "You are a code reviewer. Review the implementation from $INPUT against the original request: $ORIGINAL."

Running

pi -e extensions/agent-chain.ts

Sub-Agents (Background Workers)

The subagent-widget.ts extension spawns background Pi agent instances with live progress tracking.

Usage

/sub Refactor the auth module to use JWT tokens
/sub Write integration tests for the payment service
/sub Update the API documentation

Each /sub command spawns a background agent that works independently. Live progress widgets appear above the editor showing each sub-agent's status.

Running

pi -e extensions/subagent-widget.ts

Pi-Pi (Meta-Agent)

The pi-pi.ts extension is a meta-agent that uses parallel expert researchers to build Pi extensions collaboratively.

How It Works

1. You describe the extension you want to build
2. Pi-Pi spawns multiple expert researcher agents in parallel
3. Each expert focuses on a different aspect (API design, event handling, UI, testing)
4. Results are synthesized into a complete extension

Running

pi -e extensions/pi-pi.ts

Expert Agents

Located in .pi/agents/pi-pi/:

.pi/agents/pi-pi/
├── api-expert.md       # Extension API patterns
├── events-expert.md    # Event system knowledge
├── ui-expert.md        # TUI widget patterns
└── testing-expert.md   # Extension testing

Agent Personas

Define agent personas as Markdown files in .pi/agents/:

<!-- .pi/agents/code-reviewer.md -->
# Code Reviewer

You are a meticulous code reviewer. Focus on:
- Security vulnerabilities
- Performance bottlenecks
- Code maintainability
- Test coverage gaps

Always provide specific line references and actionable suggestions.

Switch between personas using the system-select.ts extension:

pi -e extensions/system-select.ts
# Then use /system to switch personas

Project Structure

.pi/
├── agents/
│   ├── pi-pi/              # Meta-agent expert definitions
│   │   ├── api-expert.md
│   │   ├── events-expert.md
│   │   └── ui-expert.md
│   ├── agent-chain.yaml    # Pipeline definitions
│   ├── teams.yaml          # Team configurations
│   ├── code-reviewer.md    # Agent persona
│   └── architect.md        # Agent persona
├── skills/                  # Skills available to all agents
└── settings.json

Choosing a Pattern

Pattern	Best For	Complexity
Agent Teams	Diverse tasks needing different expertise	Medium
Agent Chains	Sequential workflows (plan > build > review)	Medium
Sub-Agents	Parallel independent tasks	Low
Pi-Pi	Building extensions collaboratively	High
Persona Switching	Changing agent behavior mid-session	Low