---
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.