Multi-Agent Patterns

Build orchestrators that delegate to specialist subagents for complex tasks.

Agent Categories#

Agents come in three flavors depending on where they live and how they're used:

Type	Location	Visibility	Purpose
Top-level agents	`agents/{name}/`	Registry + installed	User-facing agents
System agents	`agents/rush-{name}/`	Registry + installed	Infrastructure (hidden from store)
Co-located subagents	`agents/{parent}/{name}.yaml`	Same directory	Parent-specific specialists

Delegation Model#

Any agent can delegate to any other agent. Not just parent to child — an orchestrator can call a top-level agent, a system agent, or a co-located subagent. Delegation is a tool call, not a hierarchy.

delegate(agent_id: "rush-browser", task: "Navigate to example.com and screenshot")
delegate(agent_id: "rabbit-hole", task: "Research competitor pricing")
delegate(agent_id: "academic-researcher", task: "Find papers on X")

Session inheritance

Delegated agents run in the same session as the parent. They share the same messages.jsonl and the same artifacts directory. This means files saved by a subagent are immediately visible to the parent when control returns.

Child agents inherit the session context. Files saved by a subagent are visible to the parent.

System Agents#

System agents are prefixed with rush-* and hidden from the agent store. They provide reusable infrastructure that any agent can delegate to.

Agent	Purpose
`rush-browser`	Web automation — navigate, screenshot, interact
`rush-memory`	Cross-agent memory — shared knowledge base
`rush-tips`	Platform guidance — onboarding and help
`rush-images`	Image search and saving

Any agent can delegate to system agents. They exist to keep common capabilities centralized rather than re-implementing browser control or image search in every agent.

Co-located Subagents#

Subagents live alongside the parent agent in the same directory. Each subagent has its own YAML definition and prompt:

agents/rabbit-hole/
  agent.yaml                    # Orchestrator
  prompt.yaml
  academic-researcher.yaml      # Specialist
  academic-researcher-prompt.yaml
  social-researcher.yaml        # Another specialist
  social-researcher-prompt.yaml

Declare the delegate tool

Enable delegation in the parent agent by adding the delegate tool:

agent.yaml

tools:
  - name: delegate
    config:
      max_depth: 3

List subagents in the prompt

Tell the orchestrator which agents are available. Be explicit about names — the agent will use exactly what you list:

prompt.yaml

sections:
  - name: available_agents
    content: |
      You MUST delegate using exact agent names:
      - **academic-researcher**: Technical docs, papers, APIs
      - **social-researcher**: Reddit, HN, forums
      Do NOT make up agent names.

When to Use Multi-Agent#

Multi-agent setups shine when tasks are complex enough to benefit from specialization:

Complex tasks requiring specialized knowledge
Parallel research across domains
Tasks with distinct phases (analyze, plan, execute)
Sub-tasks requiring multiple sequential tool calls
Sub-tasks with specialized prompting or personality

Scenario	Use
Reusable infrastructure (browser, images)	System agent (`rush-*`)
Specialist only used by one parent	Co-located subagent
Domain expert multiple agents might use	Top-level agent

Don't use multi-agent for simple tasks. A single agent with good tools is often better than an orchestrator with subagents.

Example Pattern#

A complete orchestrator + subagent setup. The main agent handles user interaction and delegates audio composition to a specialized subagent:

agents/mindful/agent.yaml

delegate_agents:
  meditation_composer:
    runtime: harness
    prompt: meditation-composer-prompt.yaml
    tools:
      - tts
      - audio_mixer
      - user_memory

Flow

The delegation follows a clean handoff pattern:

User requests a meditation session
Main agent delegates to meditation_composer
Composer generates a script, calls TTS, mixes audio with background sounds
Composer returns the audio file path to the parent
Parent renders the audio player to the user

Generative UI

Render interactive components in agent responses.

Skills

Restrict tools and bundle domain knowledge.