Chapter 5: Coordination

• If you imagine multiple persistent agents negotiating with each other, you will look for emergent social behavior where there is only context routing.
• If you think multi‑agent systems are a fundamentally new paradigm, you will miss that they reuse software patterns you already know—classification, dispatch, message passing—around an LLM.
• If you underestimate coordination, you will split too early and drown in overhead. If you ignore it, you will cram everything into one context and drown in interference.

1. Context economy. Each agent gets a focused context: a specialized system prompt, a curated tool set, a smaller slice of history. One mega-context with everything leads to interference—instructions ignored, tools misused, phases bleeding into each other. Splitting buys you back focus.
2. Parallelization. Like the actor model in distributed systems, independent agents can work simultaneously on different subtasks. Research five competitors in parallel, then synthesize. The total latency is the longest single task, not the sum. When subtasks are independent, parallelism is free performance.

1. Multi‑agent systems in practice.
2. Routing work to the right components.
3. State sharing between components.
4. Evaluating coordination overhead.

​

5.1 Multi‑Agent Systems in Practice

type Role = 'researcher' | 'writer';

const SYSTEM_PROMPTS: Record<Role, string> = {
  researcher: `
You are a research specialist. Your job is to gather factual information
and present concise findings with sources. Do not write narrative prose;
only return bullet-point findings.`,
  writer: `
You are a writing specialist. Your job is to take research findings and
turn them into clear, well-structured prose for a non-expert reader.
Do not perform new research; rely only on the provided findings.`
};

interface Message {
  role: 'user' | 'assistant';
  author: Role;
  content: string;
}

async function callAgent(role: Role, sharedLog: Message[], userInput: string) {
  const system = SYSTEM_PROMPTS[role];
  const conversation = [
    { role: 'system', content: system },
    // Flatten shared log into a single transcript string
    { role: 'user', content: renderSharedLog(sharedLog, role, userInput) }
  ];

  const reply = await llm.complete(conversation);

  const message: Message = {
    role: 'assistant',
    author: role,
    content: reply
  };

  return message;
}

• A fixed system prompt describing the role.
• A shared log of prior messages.
• A function callAgent(role, sharedLog, userInput) that reconstructs the agent on demand.

1. Append the user’s initial task to the shared log.
2. Call the researcher with its system prompt and the log; append its reply.
3. Call the writer with its system prompt and the updated log; append its reply.
4. Optionally loop, alternating roles based on some rule.

• Agents do not own memory. The shared log (and any external storage) does.
• Agents do not run autonomously. Your code decides when to invoke which system prompt.
• Agents do not negotiate in some hidden channel. They only influence each other through text you explicitly pass along.

• Focused instructions. A researcher prompt can devote all of its tokens to research norms and tools. A writer prompt can devote all of its tokens to tone, structure, and audience. They do not have to share.
• Focused tools. You can expose search and retrieval tools only to the researcher, and editing tools only to the writer. Each call considers a small tool set instead of every tool you have ever defined.
• Focused history. You can decide what parts of the shared log each role sees. The writer does not need to see every search query; the researcher does not need to see every draft revision.

• You do not get emergent organizational behavior just by adding avatars. If you want specific patterns—debate, critique, refinement—you encode them in routing and call order.
• You debug multi‑agent systems by looking at call graphs and logs, not by psychoanalyzing agents. The system behaves the way your orchestration makes it behave.
• You can often replace an “agent talking to agent” chat with a simpler pipeline: researcher call → writer call. The chat UI is optional; the underlying mechanism is function composition.

​

5.2 Routing Work to the Right Components

• Given this incoming request, which component should handle it first?
• If the first component only solves part of the problem, who gets the next turn?
• When specializations overlap, how do you avoid both duplication (two components doing the same work) and gaps (every component assuming someone else will handle a part)?

type Mode = 'general' | 'research' | 'writing' | 'coding';

interface Component {
  handle(input: string): Promise<string>;
}

const components: Record<Mode, Component> = {
  general: new GeneralAssistant(),
  research: new Researcher(),
  writing: new Writer(),
  coding: new Coder()
};

async function classify(input: string): Promise<Mode> {
  const { text } = await llm.complete({
    system: `
You are a router. Classify the user's request as one of:
- research: wants information gathered or verified
- writing: wants content drafted or edited
- coding: wants code written, explained, or modified
- general: wants a direct answer or conversation

Respond with only the category name.`,
    user: input
  });

  const label = text.trim().toLowerCase();
  if (label === 'research' || label === 'writing' || label === 'coding') {
    return label;
  }
  return 'general';
}

export async function handleUserRequest(input: string): Promise<string> {
  const mode = await classify(input);        // classification
  const component = components[mode];        // dispatch
  return component.handle(input);
}

1. Ask the model to classify an input into one of a fixed set of modes.
2. Use the classification label to dispatch to a component.

• The research component can assume that its input always requires external information. It can aggressively call search tools and focus on sources, citations, and coverage.
• The writing component can assume it is turning structured input (like research findings) into prose. It can ignore tool calls entirely and optimize for clarity and tone.
• The coding component can assume it sees code or specifications and can load language‑specific tools and style guides.

• Latency: you add at least one extra model call to classify before doing the work.
• Failure modes: misclassification sends a task to the wrong component, which can be worse than a mediocre answer from a generalist.
• Complexity: you now have more pieces to reason about (router plus components) instead of one.

• Start with a simple model‑based router like the one above.
• Log input, chosen mode, and eventual success or failure.
• Train a lightweight classifier on those logs once you see enough data.
• Fall back to the model for ambiguous cases, or ask the model to choose between only two likely options.

• “If the research handoff has zero high‑confidence sources, route to human review.”
• “If the writing stage produced more than N tokens, route to compression instead of review.”
• “If the user explicitly clicked ‘Run Code’, route directly to the executor.”

​

5.3 State Sharing Between Components

1. Direct handoffs: serialize the information one component produced into a structure and feed it to the next component as input.
2. Shared artifacts: maintain a persistent object that all components read and write, and reconstruct context from that object on each call.

interface ResearchFinding {
  content: string;
  source: string;
  confidence: 'high' | 'medium' | 'low';
}

interface ResearchHandoff {
  topic: string;
  findings: ResearchFinding[];
  gaps: string[];
  summary: string;
}

async function researcher(topic: string): Promise<ResearchHandoff> {
  // ...call LLM + tools, then compress into this structure...
}

async function writer(handshake: ResearchHandoff): Promise<string> {
  const prompt = `
Write a clear article on "${handshake.topic}".
Base your writing only on the findings below.
Highlight any gaps explicitly.

Findings:
${handshake.findings.map(f => `- (${f.confidence}) ${f.content} [${f.source}]`).join('\n')}

Gaps:
${handshake.gaps.map(g => `- ${g}`).join('\n')}
`;
  const { text } = await llm.complete({ system: WRITER_SYSTEM_PROMPT, user: prompt });
  return text;
}

• The topic.
• A curated list of findings with sources and confidence.
• Explicitly named gaps.

• Failed search queries.
• Raw snippets that were filtered out.
• The researcher’s own chain‑of‑thought.

interface Task {
  id: string;
  title: string;
  status: 'todo' | 'in_progress' | 'done' | 'needs_review';
  notes: string[];
}

class TaskBoard {
  @field tasks: Task[] = [];

  @action()
  addTask(title: string) {
    this.tasks.push({
      id: crypto.randomUUID(),
      title,
      status: 'todo',
      notes: []
    });
  }

  @action()
  updateTask(id: string, patch: Partial<Task>) {
    const task = this.tasks.find(t => t.id === id);
    if (!task) return;
    Object.assign(task, patch);
  }
}

async function plannerStep(board: TaskBoard) {
  const pending = board.tasks.filter(t => t.status === 'todo');
  const prompt = `
You are a planning assistant. Here are the current tasks:

${pending.map(t => `- [${t.id}] ${t.title}`).join('\n')}

Propose any additional tasks that are missing.
`;
  // ...use LLM to propose new tasks, then board.addTask(...)
}

async function workerStep(board: TaskBoard) {
  const tasks = board.tasks.filter(t => t.status === 'todo');
  const prompt = `
You are an execution assistant. For each task below, either:
- mark it as in_progress or done, and add a brief note
- or mark it as needs_review if it requires human input.

Tasks:
${tasks.map(t => `- [${t.id}] ${t.title}`).join('\n')}
`;
  // ...use LLM to decide, then board.updateTask(...)
}

• You can choose how much of the artifact each component sees. A Reviewer can see all tasks, while a Worker sees only assigned tasks.
• You can enforce invariants in code (for example, a task cannot move from todo directly to done without a note).
• You can log and diff changes over time, making debugging and audits tractable.

• Information loss: a researcher’s nuanced distinctions vanish in a one‑sentence summary; the writer’s work is constrained by under‑specified input.
• Information overload: a reviewer gets flooded with raw logs and cannot see the few fields that matter.
• State inconsistency: two components operate on different versions of the artifact, and their updates conflict.

​

5.4 Evaluating Coordination Overhead

• Instructions are ignored or applied inconsistently.
• Tools are chosen incorrectly or not used when they should be.
• Multi‑step processes get muddled; earlier phases leak into later ones.

class Orchestrator {
  constructor(
    private router: (input: string) => Promise<Mode>,
    private research: (topic: string) => Promise<ResearchHandoff>,
    private write: (handoff: ResearchHandoff) => Promise<string>,
    private review: (draft: string) => Promise<{ approved: boolean; notes: string; }>
  ) {}

  async handle(task: string): Promise<string> {
    const mode = await this.router(task);

    if (mode === 'general') {
      // Single-call path: no coordination needed
      const { text } = await llm.complete({
        system: GENERAL_SYSTEM_PROMPT,
        user: task
      });
      return text;
    }

    // Coordinated path: research -> write -> review
    const researchHandoff = await this.research(task);
    const draft = await this.write(researchHandoff);
    const verdict = await this.review(draft);

    if (!verdict.approved) {
      // Simple feedback loop: revise once
      const revisedPrompt = `
Here is feedback on your draft:

${verdict.notes}

Revise the draft accordingly.
Draft:
${draft}
`;
      const { text: revised } = await llm.complete({
        system: WRITER_SYSTEM_PROMPT,
        user: revisedPrompt
      });
      return revised;
    }

    return draft;
  }
}

• Context collisions: you keep adding instructions to the prompt and see them being ignored in specific regimes (“it forgets the citation format whenever code examples appear”).
• Tool confusion: with many tools available, the model starts calling the wrong one or hallucinating tool usage entirely.
• Phase interference: earlier reasoning bleeds into later steps, or the model skips necessary stages (“it goes straight to writing without doing any research when the input is longer than N tokens”).

• Creating a specialist role with a narrower prompt and smaller tool set.
• Moving part of the process into a separate call that produces a structured artifact.
• Introducing a minimal coordinator that sequences those parts and enforces handoffs.

• Long‑running tasks: anything that must pause for hours while waiting for data, human approval, or external events.
• Human‑in‑the‑loop decisions: actions that require explicit approval or judgment.
• Parallel work: tasks that naturally split into independent subproblems.

async function parallelResearch(topics: string[]): Promise<ResearchResult[]> {
  // Each topic gets its own agent call, running in parallel
  const results = await Promise.all(
    topics.map(topic =>
      llm.complete({
        system: RESEARCHER_PROMPT,
        user: `Research: ${topic}`
      })
    )
  );

  return results.map((r, i) => ({ topic: topics[i], findings: r.text }));
}

async function researchAndSynthesize(topics: string[]) {
  // Parallel phase: N topics researched simultaneously
  const findings = await parallelResearch(topics);

  // Sequential phase: synthesize all findings into one report
  const synthesis = await llm.complete({
    system: SYNTHESIZER_PROMPT,
    user: `Synthesize these findings:\n${JSON.stringify(findings, null, 2)}`
  });

  return synthesis.text;
}

class ControlledAgent {
  @field pendingAction: {
    type: string;
    payload: any;
    context: string;
  } | null = null;

  async proposeAction(type: string, payload: any, context: string) {
    // Called from LLM-driven logic when an action is needed
    this.pendingAction = { type, payload, context };
    // System stops here and waits for human input via UI
  }

  @action()
  async approve() {
    if (!this.pendingAction) return;
    await this.execute(this.pendingAction.type, this.pendingAction.payload);
    this.pendingAction = null;
  }

  @action()
  async reject(reason: string) {
    if (!this.pendingAction) return;
    this.log('Action rejected', { ...this.pendingAction, reason });
    this.pendingAction = null;
  }

  private async execute(type: string, payload: any) {
    // Implementation of side effects: send email, update CRM, etc.
  }
}

• Set pendingAction to describe what you want to do and why.
• Wait until someone clicks approve or reject.
• Resume execution.

• Start with a single capable component.
• Instrument it: log failures, context sizes, tool choices.
• When you see specific overload patterns, split along those fault lines and introduce the minimal coordination needed.
• Treat every new component as a cost that must pay for itself in clarity, quality, or safety.

​

5.5 Implementing Coordination Patterns in Idyllic

class Coordinator extends IdyllicSystem {
  @field status: 'idle' | 'routing' | 'researching' | 'writing' | 'reviewing' = 'idle';
  @field currentTask: string = '';
  @field finalOutput: string = '';

  private researcher = new Researcher();
  private writer = new Writer();
  private reviewer = new Reviewer();

  @action()
  async handle(task: string): Promise<void> {
    this.currentTask = task;
    this.status = 'routing';
    this.sync();

    const mode = await classify(task);

    if (mode === 'general') {
      const { text } = await llm.complete({
        system: GENERAL_SYSTEM_PROMPT,
        user: task
      });
      this.finalOutput = text;
      this.status = 'idle';
      return;
    }

    // Coordinated path
    this.status = 'researching';
    this.sync();
    const researchHandoff = await this.researcher.research(task);

    this.status = 'writing';
    this.sync();
    const draft = await this.writer.write(researchHandoff);

    this.status = 'reviewing';
    this.sync();
    const verdict = await this.reviewer.review(draft);

    if (!verdict.approved) {
      const revised = await this.writer.revise(draft, verdict);
      this.finalOutput = revised;
    } else {
      this.finalOutput = draft;
    }

    this.status = 'idle';
  }
}

• Coordinator is the hub, maintaining high‑level task state (status, currentTask, finalOutput).
• Researcher, Writer, and Reviewer are spokes with narrow responsibilities and prompts.
• Handoffs are typed: research returns a structured object, write takes that object, review takes a string and returns a verdict.

class FrontDoor extends IdyllicSystem {
  @field lastMode: Mode = 'general';

  private coordinator = new Coordinator();

  @action()
  async ask(input: string): Promise<void> {
    const mode = await classify(input);
    this.lastMode = mode;
    this.sync();

    await this.coordinator.handle(input);
  }
}

• A field that holds the pending request.
• An action the UI calls when a human approves or rejects.
• Coordination code that pauses until one of those actions fires.

​

Key Takeaways

• Multi‑agent systems are not multiple minds; they are multiple system prompts plus routing applied to the same underlying model. Each “agent” is reconstructed on every call.
• Routing is classification plus dispatch. It directs tasks to specialized components, trading extra complexity and latency for better performance within each specialization.
• Components do not share minds; they share state. Handoffs transfer compressed, structured context between calls, and shared artifacts provide a surface that multiple components can read and modify.
• Coordination is overhead you pay when a single context can no longer carry instructions, tools, and history reliably. You add components when specialization benefits outweigh coordination costs.
• Humans fit into the same patterns as any other component: the system surfaces state, pauses, and resumes based on their input.

​

Bridge to Chapter 6