Multi-agent systems

Coordinate

Some problems are too big for one agent’s context and instructions. Mastra’s current answer is the supervisor pattern: a lead agent is given other agents as delegates and decides which specialist handles each part of the task, then composes their results.

graph TD
  U["Request"] --> S["Supervisor agent<br/>plans + delegates"]
  S -->|delegate| A1["Research agent"]
  S -->|delegate| A2["Writer agent"]
  S -->|delegate| A3["Critic agent"]
  A1 --> S
  A2 --> S
  A3 --> S
  S --> R["Composed answer"]

The supervisor agent

Register specialist agents, then pass them to a lead agent via the agents prop. The supervisor’s instructions describe when to delegate to each.

import { Agent } from '@mastra/core/agent';
import { researchAgent } from './agents/research-agent';
import { writerAgent } from './agents/writer-agent';

export const supervisorAgent = new Agent({
  id: 'supervisor',
  name: 'Supervisor',
  instructions: `Coordinate the team. Use research-agent to gather facts,
    then writer-agent to draft. Don't answer directly — delegate.`,
  model: 'openai/gpt-4o',
  agents: { researchAgent, writerAgent },
});

Gate on task completion

A supervisor can keep delegating until the work is actually done — pass isTaskComplete with one or more scorers and a strategy.

import { createScorer } from '@mastra/core/evals';

const taskComplete = createScorer({
  id: 'task-complete',
  name: 'Task Completeness',
}).generateScore(async (context) => {
  const text = (context.run.output ?? '').toString();
  return text.includes('analysis') && text.includes('recommendation') ? 1 : 0;
});

const stream = await supervisorAgent.stream('Research AI in education', {
  maxSteps: 10,
  isTaskComplete: { scorers: [taskComplete], strategy: 'all' },
});

Choosing a pattern

Pattern	Use when
Supervisor	One lead owns the plan and delegates — the default.
Handoff	Control passes fully from one agent to another (e.g. triage → specialist).
Workflow-driven	The orchestration is deterministic — model the flow as a workflow, call agents from steps.

Caution

The older agent.network() primitive is deprecated. Use supervisor agents (the agents prop) instead — there’s a network-to-supervisor migration guide in the Mastra docs.

---

Reference: Multi-agent systems · Network → supervisor migration

Next: Evals & scorers — measure output quality instead of vibe-checking.