The Orchestrator Agent

Agentic Handbook

Central thesis: One agent to rule them all — a single, specialized orchestrator that CRUDs and commands a fleet of primary agents, backed by real-time observability, is how you scale compute to scale impact.

Overview

There are hard limits to the current interface of agents. You cannot scale by hopping into one terminal at a time, writing one prompt at a time. In the generative AI age, the rate at which you can create and command your agents becomes the constraint on your engineering output. When your agents are slow, you are slow. When your agents have a problem, you have a problem.

Every engineer sits at one of these levels: base agents, better agents, more agents, custom agents. At each step you scale compute to scale impact. This lesson adds one giant leap on top: multi-agent orchestration. The Orchestrator Agent (the "OA") is the single-interface pattern — a decades-old engineering paradigm — applied to your fleet of agents.

Orchestration is not just the OA. It is three pillars combined: the Orchestrator Agent as your unified interface, CRUD for agents (create/command/delete on the fly) which gives you agents at scale, and observability for real-time monitoring of every agent's performance, cost, and results. If you cannot measure it, you cannot improve it or scale it. Ten agents doing the wrong thing is not progress.

Critically, the orchestrator commands PRIMARY agents, not blind sub-agents. It takes your high-level prompt, writes out the concrete detailed work, spins up focused agents, commands them, checks on them, and reports back — while protecting its own context window. This is an out-of-the-loop (Peter) system: prompt in, HTTP trigger, agents execute in an environment, observability surfaces the results.

Key concepts

The Orchestrator Agent ("one agent to rule them all")

The OA is a custom agent: its system prompt is completely overwritten and its tools are specialized to manage other agents. You talk only to the orchestrator. Using the single-interface pattern, it creates, commands, updates, and deletes your agents on your behalf. It does not do the application work itself — its one job is to conduct. This is why it sits last in the scale ladder: base → better → more → custom → orchestrator.

Orchestration = OA + CRUD-for-agents + observability

Three design elements unlock the next scale of agentic engineering:

• Orchestrator — unified interface to your fleet.
• CRUD for agents — create, command, and delete agents on the fly, giving you agents at scale with a single prompt.
• Observability — a live interface showing responses, tool calls, thinking, hooks, models, and costs for every agent, filterable per-agent and per-event-type.

Orchestrator commands PRIMARY agents, not sub-agents

A common objection: "aren't these just sub-agents?" No. Sub-agents are locked in, too narrow, ephemeral — context is blown away and you cannot re-prompt them. By pulling agents up one level into full primary agents (blowing away the system prompt, giving custom tools), the orchestrator can tap into each one repeatedly to command it or read from it until the job is done. You can re-prompt, run continuation prompts, and reference other files. The orchestrator becomes glue for the workflow — superior to blind agent handoffs.

Agents as deletable temporary resources

Every engineer's journey: read code, create code, update code, then learn the best code is no code — you learn to delete. Agents are the same. Treat every agent as a deletable temporary resource that serves a single purpose. Build agents to do specific work; when the job is done, they are gone. delete all agents and the OA blows them away. This enforces one agent, one prompt, one purpose and sidesteps context rot, pollution, and toxic context. A 200K window is plenty — you are just stuffing a single agent with too much work.

The sleep/poll pattern

When the OA needs to stay involved, it enters an agentic loop: fire off agents, sleep, then wake to check agent status (e.g., every 15 seconds) via a custom status tool. It reads a tail of each agent's logs — it does not continuously watch every log, which would flood its context. It verifies, chains the next phase, and reports. This is how the orchestrator monitors a multi-agent workflow while keeping its own context minimal.

Every agent produces a concrete result

Each agent must produce a document, diff, or report that can be handed off, inspected, and reviewed. Otherwise, what was the point? Observability differentiates consumed assets (files read) from produced assets (files written), one click away from the editor.

graph TD
    U[You] -->|single prompt| OA[Orchestrator Agent]
    OA -->|create + command| P1[Primary Agent: Planner]
    OA -->|create + command| P2[Primary Agent: Builder]
    OA -->|create + command| P3[Primary Agent: Reviewer]
    P1 -->|plan file| OA
    P2 -->|git diff| OA
    P3 -->|review| OA
    OA -->|sleep / poll status| P1
    OA -->|sleep / poll status| P2
    OA -.->|events| OBS[Observability UI]
    P1 -.->|responses / tools / cost| OBS
    P2 -.->|responses / tools / cost| OBS
    P3 -.->|responses / tools / cost| OBS
    OA -->|delete all when done| X[Agents deleted]

How to apply it

1. Talk only to the orchestrator. Send one high-level prompt; let the OA translate it into concrete work and spin up the needed agents. Do not micromanage individual agents.
2. Divide work by focus. Split tasks (front end, back end, QA) so each agent has one focused context window. Use fast models (e.g., Haiku) for simple work and a stronger model for synthesis/QA.
3. Stand up observability first. Ensure every agent's core four (context, model, prompt, tools) plus responses, tool calls, hooks, cost, and produced/consumed files are visible and filterable. You cannot scale what you cannot measure.
4. Use the sleep/poll pattern for long jobs. Have the OA fire agents, sleep, poll status on a fixed interval, verify, and only advance phases when work completes.
5. Chain phased workflows. Model serious work as plan → build → review with a final report — this is the ADW shape applied through the orchestrator.
6. Keep the OA's context protected. Do not let it read raw logs continuously or do application work. Prime it sparingly, only for high-level codebase understanding.
7. Delete agents when the job is done. Run clear all / delete all agents. Let the OA reclaim them. Start fresh for the next task.
8. Specialize relentlessly. Build domain-specific prompts and tools that only your custom agents can run. If your work is one to four prompts away with zero effort, it is not defensible.

Commands & conventions

Command / prompt	What it does
ping	Quick health check to the orchestrator.
list agents / check status of our agents	OA runs status tools, reads log tails, reports state.
command all agents ...	Broadcasts a prompt (e.g., "enable thinking") to every live agent.
create an agent ...	OA crafts and prompts a new primary agent (optionally from a template).
delete agent / delete all agents / clear all	Tears down one or all agents.
/question	Reusable prompt run by an agent to answer a codebase question.
/prime (and specialized primes)	User-activated memory prompt that focuses an agent on specific files.

Conventions and architecture:

• Core four, always: context, model, prompt, tools. Every feature, UI, and experience reduces to these four leverage points. Know their state for every agent at every critical moment.
• Built on the Claude Agent SDK. The system is interoperable with the entire Claude Code ecosystem — slash commands, skills, hooks, reusable prompts, agent templates.
• Agent templates live in .claude/agents/ (e.g., agents/scout-fast). A sub-agent template is promoted to a primary agent by overwriting its system prompt and giving it custom tools.
• Data layer: a Postgres database (Neon or local Docker Postgres) with concrete structure holds agent commands, communications, and logs — because this is an out-of-the-loop system observing work from outside.
• Transport: front end (Pinia store) talks to the backend over HTTP + WebSocket; the orchestrator service uses the Claude Agent SDK. The orchestrator is deliberately separated from command-level agents.
• Out-of-loop by design: prompt input → HTTP trigger → environment → multi-agent observability. Deployable across multiple codebases and devices.
• Template your engineering. Encode how you plan, build, and report into system prompts, reusable prompts, and ADWs. Specialization is the differentiating edge.

Key takeaways

• Multi-agent orchestration is the next step after base, better, more, and custom agents — it is how you command compute at scale.
• The orchestrator is a specialized custom agent with an overwritten system prompt whose only job is to CRUD and command other agents.
• It commands primary agents, not sub-agents, so agents are re-promptable, less ephemeral, and can be tapped repeatedly until the job is done.
• Observability is non-negotiable: if you cannot measure your agents, you cannot improve or scale them.
• Protect context windows everywhere — use the sleep/poll pattern so the OA monitors without drowning in logs.
• Treat agents as deletable temporary resources: one agent, one prompt, one purpose, then let them go home.
• Every agent must produce a concrete, inspectable result.
• The real trade-off is upfront investment: plumbing, database, WebSocket connections, and ongoing maintenance of your agentic layer — worth it to gain an out-of-loop mode of engineering.

Notable quotes

"The rate at which you can create and command your agents becomes the constraint of your engineering output."

"You must treat your agents as deletable temporary resources that serve a single purpose."

"If you can't measure it, you can't improve it. And if you can't measure it, you can't scale it."

"One agent, one prompt, one purpose. Focus your agent on one task and let it go home back to the data center."