Skip to content

Week 7: Multi-Agent Workflows

Teaching Goal

By the end of this session, learners should be able to explain why a multi-agent workflow exists, design a two-agent hand-off, and spot the common failure modes before they cause messy edits.

Where We Are

Weeks 1-6 built the pieces:

  • Prompts
  • Plan vs build
  • Commands
  • Skills
  • Custom agents
  • Permissions

This week combines them into a workflow.

The New Idea

Do not build one giant agent.

Build one primary agent that delegates to smaller specialists.

That pattern is called primary-agent-as-orchestrator.

Why Not One Agent?

A single agent can get overloaded by:

  • Too much context
  • Too many responsibilities
  • Too many permissions
  • Too many files changing at once

Multi-agent workflows reduce those risks by splitting the work.

Three Reasons To Split Agents

  1. Context isolation: each agent gets a smaller job.
  2. Specialization: each agent can have a narrow role.
  3. Permission control: read-only agents stay read-only.

The split is not about making the system fancy. It is about making the work safer.

Mental Model

User
  -> Primary orchestrator
      -> Explorer subagent
      -> Reviewer subagent
      -> Fixer subagent
  <- Primary summary

The user talks to the primary. The primary talks to the subagents.

Primary Agent Responsibilities

The primary agent:

  • Understands the user's goal
  • Decides what to delegate
  • Gives each subagent a bounded task
  • Reads subagent results
  • Chooses the next action
  • Reports the final answer

The primary owns the story.

Subagent Responsibilities

A subagent:

  • Takes one focused task
  • Uses only the permissions it needs
  • Returns a concise result
  • Does not take over the whole workflow

Subagents should feel like helper functions, not co-owners of the project.

Demo Setup

We will use a small buggy app.

Goal: fix a task without letting the editing agent wander.

Agents:

  • explorer: read-only, investigates and reports
  • builder: write-enabled, implements the fix

Good Hand-Off

@explorer Inspect the todo filter bug.
Scope: src/todos only.
Do not edit files.
Return: root cause, files involved, and a 3-step fix plan.

This is specific, bounded, and has an output shape.

Bad Hand-Off

@explorer Look around and tell me what's wrong.

Problems:

  • No file scope
  • No stopping point
  • No output shape
  • Easy to drift into unrelated issues

Hand-Off Contract

A hand-off contract has four parts:

  1. Role: what lens should the subagent use?
  2. Scope: which files or behavior are in bounds?
  3. Permission expectation: read-only, test-only, or edit?
  4. Return shape: what should come back?

If the contract is vague, the workflow is fragile.

Failure Mode: Context Bleed

Context bleed happens when an agent uses context outside the intended scope.

Example:

The primary asks for src/filter.js only. The subagent reviews the whole app and suggests database changes.

Fix: name the exact files, behavior, and output limits.

Failure Mode: Conflicting Edits

Conflicting edits happen when two write-enabled agents touch the same area.

Example:

One agent reformats a file while another agent changes logic in that same file.

Fix: serialize writes or assign file ownership.

Failure Mode: Infinite Loop

An infinite loop happens when agents keep handing work back without an exit condition.

Example:

Reviewer says "ask fixer." Fixer says "ask reviewer." Repeat.

Fix: define done conditions before delegation.

Failure Mode: Noisy Output

Noisy output happens when a subagent returns too much detail.

Example:

The primary asks for one root cause and gets a 70-line essay.

Fix: require a short format such as bullets, table, or checklist.

Decision Rule

Use multiple agents when the task has at least one of these:

  • Different roles
  • Different permissions
  • Large context
  • Parallel investigation
  • A review step before edits

Do not use multiple agents for a typo fix.

Lab 7.1 Preview

Learners will build a two-agent workflow:

  • Explorer investigates in read-only mode
  • Builder implements from the explorer's report

The key artifact is the hand-off contract.

Lab 7.2 Preview

Learners will diagnose a broken run log.

They will identify:

  • Where context bled
  • Where the contract failed
  • Which agent had too much permission
  • How to rewrite the hand-off

Instructor Demo Script

  1. Start with one broad prompt and show why it is risky.
  2. Rewrite it as a bounded explorer prompt.
  3. Let the explorer return a short report.
  4. Ask the builder to implement only that report.
  5. Compare the message graph to the original broad prompt.

Check For Understanding

Ask learners:

  • What should the explorer not be allowed to do?
  • What does the builder need from the explorer?
  • What would make this workflow over-engineered?
  • Where could conflicting edits happen?

Closing Thought

Multi-agent work is not about more agents.

It is about clearer boundaries.