Multi-Agent Systems: Orchestrators, Subagents, and When to Use Them

export interface Doc {
  id: string;
  product: string;
  kind: "pricing" | "features" | "review";
  text: string;
}
 
export const DOCS: Doc[] = [
  { id: "d1", product: "Acme CRM", kind: "pricing", text: "Acme CRM: $25 per user per month, annual billing only. Free tier up to 2 users." },
  { id: "d2", product: "Acme CRM", kind: "features", text: "Acme CRM includes email sync, pipelines, and a REST API. No built-in phone dialer." },
  { id: "d3", product: "Acme CRM", kind: "review", text: "Reviewers praise setup speed; several mention slow support responses (2 to 3 days)." },
  { id: "d4", product: "Bolt CRM", kind: "pricing", text: "Bolt CRM: $39 per user per month, monthly or annual. No free tier; 14-day trial." },
  { id: "d5", product: "Bolt CRM", kind: "features", text: "Bolt CRM includes a phone dialer, call recording, pipelines, and Zapier integration." },
  { id: "d6", product: "Bolt CRM", kind: "review", text: "Reviewers like the dialer; some report the mobile app crashes on Android." },
  { id: "d7", product: "Cobalt CRM", kind: "pricing", text: "Cobalt CRM: $15 per user per month; advanced reports cost $10 more per user." },
  { id: "d8", product: "Cobalt CRM", kind: "features", text: "Cobalt CRM has pipelines, basic reports, and CSV import. API access only on the Pro add-on." },
  { id: "d9", product: "Cobalt CRM", kind: "review", text: "Reviewers call it great value for small teams but limited once you pass 20 users." },
];
 
export function searchDocs(query: string, product?: string) {
  const words = query.toLowerCase().split(/\s+/).filter((w) => w.length > 2);
  return DOCS.filter((d) => (!product || d.product === product) && words.some((w) => d.text.toLowerCase().includes(w)));
}

import Anthropic from "@anthropic-ai/sdk";
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";
import { searchDocs } from "./corpus.ts";
 
const client = new Anthropic();
 
export interface SubagentResult {
  task: string;
  summary: string;
  tokens: number;
}
 
export async function runSubagent(task: string, brief: string): Promise<SubagentResult> {
  const search = betaZodTool({
    name: "search_docs",
    description: "Search product pages and reviews. Returns matching documents with IDs to cite.",
    inputSchema: z.object({ query: z.string(), product: z.string().optional().describe("Exact product name to filter by") }),
    run: async ({ query, product }) => JSON.stringify(searchDocs(query, product)),
  });
 
  const runner = client.beta.messages.toolRunner({
    model: "claude-sonnet-5-5", // subagents do focused reading: a faster model is usually enough
    max_tokens: 8192,
    max_iterations: 6,
    system:
      "You are a research subagent. Complete only the task in your brief. Search thoroughly, then reply with a summary of at most 150 words that cites document IDs like [d4]. State clearly what you could not find.",
    tools: [search],
    messages: [{ role: "user", content: brief }],
  });
 
  let tokens = 0;
  let summary = "";
  for await (const message of runner) {
    tokens += message.usage.input_tokens + message.usage.output_tokens + (message.usage.cache_read_input_tokens ?? 0);
    summary = message.content.flatMap((b) => (b.type === "text" ? [b.text] : [])).join("");
  }
  return { task, summary, tokens };
}

import Anthropic from "@anthropic-ai/sdk";
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
import { z } from "zod";
import { runSubagent, type SubagentResult } from "./subagent.ts";
 
const client = new Anthropic();
 
const Plan = z.object({
  subtasks: z
    .array(
      z.object({
        name: z.string().describe("Short label, such as 'Bolt CRM'"),
        brief: z.string().describe("Objective, what to look for, expected output, and what is out of scope"),
      }),
    )
    .describe("2 to 5 independent subtasks"),
});
 
// Run async work with at most `limit` tasks in flight.
async function mapLimit<T, R>(items: T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]> {
  const results: R[] = new Array(items.length);
  let next = 0;
  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
    while (next < items.length) {
      const i = next++;
      results[i] = await fn(items[i]!);
    }
  });
  await Promise.all(workers);
  return results;
}
 
export async function research(question: string) {
  // 1. Plan: the lead decides how to split the work.
  const planned = await client.messages.parse({
    model: "claude-opus-5-5",
    max_tokens: 4096,
    output_config: { effort: "medium", format: zodOutputFormat(Plan) },
    system: "You are a lead researcher. Split the question into independent subtasks for parallel subagents. Each brief must stand alone: the subagent sees nothing else.",
    messages: [{ role: "user", content: question }],
  });
  const subtasks = (planned.parsed_output?.subtasks ?? []).slice(0, 5);
  if (subtasks.length === 0) throw new Error("The lead agent produced no plan");
 
  // 2. Delegate: subagents run in parallel, a few at a time. One failure does not sink the run.
  const results = await mapLimit(subtasks, 3, async (t): Promise<SubagentResult> => {
    try {
      return await runSubagent(t.name, t.brief);
    } catch (error) {
      return { task: t.name, summary: `FAILED: ${error instanceof Error ? error.message : String(error)}`, tokens: 0 };
    }
  });
 
  // 3. Synthesize from the condensed findings only.
  const final = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 8192,
    system: "You are a lead researcher. Write the final answer from your subagents' findings. Keep their citations. Point out gaps and contradictions honestly.",
    messages: [
      {
        role: "user",
        content: `Question: ${question}\n\n${results.map((r) => `<findings task="${r.task}">\n${r.summary}\n</findings>`).join("\n")}`,
      },
    ],
  });
 
  const answer = final.content.flatMap((b) => (b.type === "text" ? [b.text] : [])).join("");
  const subagentTokens = results.reduce((sum, r) => sum + r.tokens, 0);
  return { answer, subtasks: subtasks.map((t) => t.name), subagentTokens };
}

import { research } from "./lib/orchestrator.ts";
 
const result = await research(
  "We are a 12-person sales team that makes many phone calls. Compare Acme CRM, Bolt CRM, and Cobalt CRM on price, phone features, and reliability, and recommend one.",
);
console.log("subtasks:", result.subtasks.join(", "));
console.log("subagent tokens:", result.subagentTokens);
console.log(result.answer);