Multi-Agent Orchestration Patterns

Design and implement multi-agent workflows in OpenCode. Learn routing strategies, delegation patterns, and how to coordinate multiple agents for complex tasks.

Why Multi-Agent?

Single agents work well for simple tasks, but complex projects benefit from specialized agents working together.

Pattern	Use Case	Benefit
Router	Direct tasks to specialists	Better accuracy
Pipeline	Sequential processing	Clear workflow
Parallel	Independent tasks	Faster execution
Hierarchical	Complex delegation	Scalability

Router Pattern

The router pattern directs tasks to the most appropriate agent based on content.

json

{
  "agents": {
    "default": {
      "model": "gpt-4o",
      "description": "Routes tasks to specialists"
    },
    "frontend": {
      "model": "gpt-4o",
      "description": "React, CSS, TypeScript, UI/UX"
    },
    "backend": {
      "model": "claude-sonnet-4-20250514",
      "description": "APIs, databases, server logic"
    },
    "devops": {
      "model": "gpt-4o",
      "description": "Docker, CI/CD, deployment, infrastructure"
    }
  },
  "agentRouting": {
    "mode": "auto",
    "defaultAgent": "default",
    "rules": [
      {
        "pattern": "react|css|component|ui|frontend",
        "agent": "frontend"
      },
      {
        "pattern": "api|database|sql|endpoint|backend",
        "agent": "backend"
      },
      {
        "pattern": "docker|deploy|ci/cd|pipeline|kubernetes",
        "agent": "devops"
      }
    ]
  }
}

Pipeline Pattern

Chain agents for sequential processing:

💡 Tip: Use Ctrl + Mouse Wheel to zoom, or click the fullscreen icon

Implementation

json

{
  "agents": {
    "requirements": {
      "model": "gpt-4o",
      "description": "Analyzes requirements and creates specifications"
    },
    "design": {
      "model": "claude-sonnet-4-20250514",
      "description": "Creates technical design from specifications"
    },
    "implement": {
      "model": "gpt-4o",
      "description": "Writes code based on design documents"
    },
    "test": {
      "model": "gpt-4o-mini",
      "description": "Generates and runs tests"
    },
    "review": {
      "model": "claude-sonnet-4-20250514",
      "description": "Reviews code quality and security"
    }
  }
}

Parallel Pattern

Execute independent tasks simultaneously:

💡 Tip: Use Ctrl + Mouse Wheel to zoom, or click the fullscreen icon

When to Use Parallel

Task Type	Parallel?	Reason
Independent modules	✅	No dependencies
Cross-cutting concerns	❌	Need coordination
Sequential logic	❌	Order matters
Multiple test suites	✅	Independent execution

Hierarchical Pattern

Use subagents for complex delegation:

json

{
  "agents": {
    "lead": {
      "model": "gpt-4o",
      "description": "Project lead that coordinates work",
      "subagents": {
        "frontend-lead": {
          "model": "gpt-4o",
          "description": "Manages frontend team"
        },
        "backend-lead": {
          "model": "gpt-4o",
          "description": "Manages backend team"
        }
      }
    }
  }
}

Agent Communication

Via Files

Agents can communicate through shared files:

python

# Agent 1 writes
with open("tmp/design.json", "w") as f:
    json.dump(design_spec, f)

# Agent 2 reads
with open("tmp/design.json") as f:
    design_spec = json.load(f)

Via Context

The primary agent passes context to subagents:

> Have the backend agent implement the API, then have the test agent write tests for it

Best Practices

Agent Specialization

Agent Type	Model	Temperature	Use Case
Architect	Claude	0.3	Design decisions
Coder	GPT-4o	0.7	Implementation
Reviewer	Claude	0.2	Code review
Tester	GPT-4o-mini	0.5	Test generation

Permission Isolation

json

{
  "permissions": [
    {
      "tool": "write",
      "allow": ["src/frontend/**"],
      "agent": "frontend"
    },
    {
      "tool": "write",
      "allow": ["src/backend/**"],
      "agent": "backend"
    }
  ]
}