Immutable. This exact content is served forever at /api/v1/blob/528cf11e3071f681.
--- name: agent-orchestration-architecture description: "Resolve agent ownership and handoff design." --- # Agent Orchestration Architecture ## Design in escalating complexity Choose the lightest design that satisfies the outcome: 1. Deterministic program or promptless automation. 2. One agent with bounded tools and structured output. 3. One manager agent that calls specialists as bounded tools. 4. Handoffs only when a specialist should own the rest of the interaction. 5. Durable workflow runtime only when work survives interruptions, waits, or external callbacks. Do not use an agent swarm as a substitute for an owned workflow. ## Define the operating contract Before implementation, record: - outcome, success evidence, and named final-output owner; - inputs, output schema, permitted tools, and forbidden actions; - model and reasoning choice by decision difficulty, not task size; - state owner, memory lifetime, tenant boundary, and source of truth; - approval checkpoints, budgets, timeouts, stop conditions, and escalation; - retry, idempotency, compensation, and human-handoff behavior. Parallelize only independent work whose outputs can be reconciled without conflicting writes. ## Make control explicit - Use a manager when one agent must enforce shared policy, combine specialist work, or own the user-facing answer. - Use a handoff when the specialist needs a focused interaction and clear transfer of responsibility. - Pass structured task packets, not vague conversation history. Minimize context to the specialist's need. - Delegate only a concrete, independent workstream with a defined output. Parallelism can reduce latency, but every subagent performs separate model and tool work and therefore increases usage. - Designing a delegation architecture does not authorize spawning agents. Follow current global and native tool constraints: preserve the selected parent model/effort and apply the current global child-model and reasoning policy. Do not freeze a session-specific model or effort into this specialist. Use only supported context controls and sufficient task context; do not override native inheritance constraints for a preferred packet format. - Give each specialist the exact sources, constraints, output schema, stopping condition, and useful result-size limit. Ask for distilled findings instead of raw logs or copied source material. - Keep the parent thread as the canonical decision owner. Do not spawn several agents to reread the same corpus, and do not use subagents merely to avoid doing a bounded task locally. - Use inherited authorization for routine reversible in-scope writes, drafts and configuration. Require explicit authorization for actual sends, spending, binding commitments, publication and materially irreversible actions at their real boundaries; do not reopen an already clear authorization. - Design every loop with a maximum attempt count and a useful terminal state. ## Required outputs For a material architecture request, produce the smallest useful combination of an execution diagram, role/tool matrix, state/approval map, operating limits, and evaluation plan. Do not create every artifact for a simple routing decision. Route persistent-context design to `$agent-memory-provenance`; route quality and release testing to `$agent-evaluation-operations`; route external events to `$integration-contract-reliability`. ## Optional specialists For external events, integration-contract-reliability is optional. Without it, define typed inputs/outputs, authentication, idempotency, retries, duplicate handling, uncertain-effect reconciliation and the actual success boundary in the project contract.