Agent Design Patterns in TypeScript: Chaining to Evaluator-Optimizer

import Anthropic from "@anthropic-ai/sdk";
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
import type { z } from "zod";
 
export const client = new Anthropic();
 
type Options = { system?: string; model?: Anthropic.Model; effort?: "low" | "medium" | "high" };
 
export async function ask(prompt: string, o: Options = {}): Promise<string> {
  const message = await client.messages.create({
    model: o.model ?? "claude-opus-5-5",
    max_tokens: 8192,
    ...(o.effort ? { output_config: { effort: o.effort } } : {}),
    ...(o.system ? { system: o.system } : {}),
    messages: [{ role: "user", content: prompt }],
  });
  return message.content.flatMap((b) => (b.type === "text" ? [b.text] : [])).join("");
}
 
export async function askJson<T extends z.ZodType>(schema: T, prompt: string, o: Options = {}): Promise<z.infer<T>> {
  const message = await client.messages.parse({
    model: o.model ?? "claude-opus-5-5",
    max_tokens: 8192,
    output_config: { effort: o.effort ?? "low", format: zodOutputFormat(schema) },
    ...(o.system ? { system: o.system } : {}),
    messages: [{ role: "user", content: prompt }],
  });
  if (message.parsed_output == null) throw new Error(`No structured output (stop_reason: ${message.stop_reason})`);
  return message.parsed_output;
}

import { z } from "zod";
import { ask, askJson } from "./lib/llm.ts";
 
const Outline = z.object({ title: z.string(), sections: z.array(z.string()) });
 
export async function writeReleaseNotes(changelog: string): Promise<string> {
  // Step 1: outline as structured data.
  const outline = await askJson(Outline, `Outline customer-facing release notes for this changelog:\n<changelog>\n${changelog}\n</changelog>`);
 
  // Gate: plain code decides whether to continue.
  if (outline.sections.length < 1 || outline.sections.length > 6) {
    throw new Error(`Outline has ${outline.sections.length} sections; expected 1 to 6`);
  }
 
  // Step 2: draft from the validated outline only.
  const draft = await ask(`Write release notes titled "${outline.title}" with sections: ${outline.sections.join(", ")}.\nSource:\n${changelog}`);
 
  // Step 3: a narrow polishing task, so a faster model is enough.
  return ask(`Edit for clarity and a friendly tone. Keep all facts. Return only the edited text.\n\n${draft}`, {
    model: "claude-sonnet-5-5",
    effort: "low",
  });
}
 
console.log(await writeReleaseNotes("- feat: CSV export for invoices\n- fix: timezone bug in reports\n- perf: dashboard loads 2x faster"));

import { z } from "zod";
import { ask, askJson } from "./lib/llm.ts";
 
const Route = z.object({ route: z.enum(["refund", "technical", "general"]) });
 
const handlers: Record<z.infer<typeof Route>["route"], (q: string) => Promise<string>> = {
  refund: (q) => ask(q, { system: "You handle refund requests. Explain the refund policy: full refunds within 30 days." }),
  technical: (q) => ask(q, { system: "You are a senior support engineer. Ask for logs when needed and give exact steps." }),
  general: (q) => ask(q, { system: "You answer general product questions briefly.", model: "claude-haiku-4-5" }),
};
 
export async function handle(question: string): Promise<string> {
  // The router is a cheap, fast call that only classifies.
  const { route } = await askJson(Route, `Route this customer message:\n<message>\n${question}\n</message>`, {
    model: "claude-sonnet-5-5",
  });
  console.log("route:", route);
  return handlers[route](question);
}
 
console.log(await handle("The app crashes when I upload a PDF larger than 10 MB."));

import { z } from "zod";
import { askJson } from "./lib/llm.ts";
 
const Finding = z.object({ issues: z.array(z.string()), severity: z.enum(["none", "low", "high"]) });
 
// Sectioning: each reviewer checks one aspect, all at once.
export async function reviewCode(diff: string) {
  const aspects = ["security vulnerabilities", "performance problems", "missing error handling"];
  const results = await Promise.all(
    aspects.map((aspect) => askJson(Finding, `Review this diff only for ${aspect}.\n<diff>\n${diff}\n</diff>`)),
  );
  return aspects.map((aspect, i) => ({ aspect, ...results[i]! }));
}
 
// Voting: three independent judgments; flag only when a majority agrees.
const Verdict = z.object({ isSpam: z.boolean() });
export async function isSpam(text: string): Promise<boolean> {
  const votes = await Promise.all([1, 2, 3].map(() => askJson(Verdict, `Is this message spam?\n<message>\n${text}\n</message>`)));
  return votes.filter((v) => v.isSpam).length >= 2;
}
 
console.log(await reviewCode(`+ const user = await db.query("SELECT * FROM users WHERE id = " + req.params.id);`));
console.log(await isSpam("Congratulations! You won a $500 gift card. Click here to claim."));

import { z } from "zod";
import { ask, askJson } from "./lib/llm.ts";
 
const Plan = z.object({
  subtasks: z.array(z.object({ file: z.string(), instructions: z.string() })).describe("At most 5 subtasks"),
});
 
export async function planAndExecute(request: string, files: Record<string, string>) {
  // The orchestrator plans with knowledge of the codebase.
  const plan = await askJson(
    Plan,
    `Request: ${request}\nFiles: ${Object.keys(files).join(", ")}\nPlan one subtask per file that must change.`,
    { effort: "medium" },
  );
 
  // Workers run in parallel, each seeing only its own file.
  const changes = await Promise.all(
    plan.subtasks.slice(0, 5).map(async (t) => ({
      file: t.file,
      code: await ask(`${t.instructions}\nReturn only the full updated file.\n<file path="${t.file}">\n${files[t.file] ?? ""}\n</file>`),
    })),
  );
 
  // Synthesis: check the pieces fit together.
  const summary = await ask(
    `Summarize these changes for a pull request description and flag any inconsistencies between files:\n${changes
      .map((c) => `<file path="${c.file}">\n${c.code}\n</file>`)
      .join("\n")}`,
  );
  return { changes, summary };
}
 
const result = await planAndExecute("Rename the 'qty' field to 'quantity' everywhere", {
  "src/cart.ts": "export type Item = { id: string; qty: number };",
  "src/checkout.ts": "export const total = (items: { qty: number; price: number }[]) => items.reduce((s, i) => s + i.qty * i.price, 0);",
});
console.log(result.summary);

import { z } from "zod";
import { ask, askJson } from "./lib/llm.ts";
 
const Review = z.object({
  approved: z.boolean(),
  problems: z.array(z.string()).describe("Specific, actionable problems; empty if approved"),
});
 
export async function writeWithReview(task: string, criteria: string[], maxRounds = 3) {
  let draft = await ask(task);
  for (let round = 1; round <= maxRounds; round++) {
    const review = await askJson(
      Review,
      `Evaluate the draft against every criterion.\nCriteria:\n- ${criteria.join("\n- ")}\n<draft>\n${draft}\n</draft>`,
      { system: "You are a strict reviewer. Approve only if every criterion is fully met." },
    );
    if (review.approved) return { draft, rounds: round };
    draft = await ask(`${task}\n\nRevise this draft to fix these problems:\n- ${review.problems.join("\n- ")}\n<draft>\n${draft}\n</draft>\nReturn only the revised text.`);
  }
  return { draft, rounds: maxRounds, approved: false };
}
 
console.log(
  await writeWithReview("Write a 3-sentence error message shown when a payment fails.", [
    "Says what happened in plain language",
    "Tells the user exactly what to do next",
    "Does not blame the user",
    "Mentions no internal error codes",
  ]),
);