agent-orchestration

name: agent-orchestration description: Agent orchestration capability pack. Gives AI agents the judgment rules for building reliable multi-agent systems — framework selection (LangGraph / CrewAI / AutoGen v0.4+ / OpenAI Agents SDK / Claude Agent SDK), Supervisor vs Swarm topology, durable execution with Temporal event sourcing, human-in-the-loop interrupt/resume patterns, and tool-permission models. Research-grounded rules from framework docs, Temporal durable-execution patterns, and production complexity-cliff analysis. Use for any multi-agent architecture, orchestration framework choice, checkpoint/recovery design, HITL gating, or agent tool-permission task. keywords: ["agent orchestration", "智能体编排", "multi-agent", "多智能体", "LangGraph", "CrewAI", "AutoGen", "Microsoft Agent Framework", "OpenAI Agents SDK", "Claude Agent SDK", "Temporal", "durable execution", "持久化执行", "supervisor", "swarm", "orchestrator-worker", "fan-out", "checkpoint", "检查点", "human-in-the-loop", "failure mode", "MAST", "失败模式", "状态机", "agent 框架"] type: reference-based

CONSUMES: User multi-agent / orchestration task + target workflow description + step count / duration estimate + optional existing framework choice PRODUCES: Applied orchestration judgment rules + framework selection rationale + topology decision (supervisor/swarm) + durability/checkpoint plan + HITL interrupt design + tool-permission audit

Agent Orchestration Capability Pack

Version: 0.1.0 Compatibility: Claude Code (Phase 1); Codex / Cursor / Gemini in Phase 3 License: Apache 2.0

What This Pack Does

AI agents wire up multi-agent systems by copying a framework's quickstart. They pick LangGraph because it is popular, not because the workflow needs deterministic state. They build swarms with 8 peer agents and never reason about the O(n²) failure surface. They run 300-step agents on bare retry loops, then are surprised when step 280 crashes and restarts from step 1 — re-sending the emails it already sent. They auto-approve every tool call because adding a human gate "later" never happens.

This pack embeds the judgment rules that orchestration engineers apply automatically — rules from framework documentation, Temporal durable-execution patterns, and production reliability data.

Pack = orchestration judgment. Your workflow system = process constraints. No overlap.

Cross-Cutting Rule: The Complexity Cliff — Reliability Decays Exponentially with Step Count

Cumulative agent reliability is P(fail) = 1 - (1 - p)^s, where p is per-step failure probability and s is the number of sequential steps. A 99% per-step success rate (p = 0.01) gives a 63.4% cumulative failure probability at 100 steps and 99.3% at 500 steps. State-management failures (lost context, repeated expensive steps, crash with no recovery path) are a leading, often-dominant source of production agent incidents. Therefore: once cumulative failure becomes material, decouple the orchestration/state layer from the agent reasoning loop — via durable checkpointing or event-sourced execution. As a derived heuristic from the cited figures (NOT a research-reported threshold): at p = 0.01, P(fail) crosses ~40% by ~50 steps (1 - 0.99^50 ≈ 0.395), ~63% at 100 steps, and ~99% at 500 steps — so treat workflows of a few tens of sequential steps and up as candidates for durable execution, and compute P(fail) against your own per-step p. Bare retry scripts are a fragile pattern above the cliff: they do not preserve the execution stack and re-run side-effecting steps on restart.

This rule applies to: framework selection, topology choice, durability design, and every "we'll just add retries" decision. It is surfaced here because burying it in one reference file causes agents to under-build durability and then ship agents that fail statistically.

Source: findings.md "Exponential Failure Mechanics" [2] (formula + 63.4%@100 / 99.3%@500), "Complexity Cliff" [2,4]. The ~40%@50-steps figure is DERIVED from the same 1 - (1-p)^s model at p=0.01, not separately reported by research; the "few tens of steps" durability trigger is an authored heuristic, not a research-stated threshold.

Step 0: Context Detection

When the user mentions orchestration / multi-agent work, detect the context and load the right reference:

Step 1: Apply Rules

After loading the relevant reference file(s):

1. Read the reference completely — do not skim
2. Apply each rule as a judgment check against the user's architecture, framework choice, or workflow description
3. For each violated rule: state the violation clearly, then give the specific fix
4. Enforce the Complexity Cliff cross-cutting rule — compute P(fail) for the user's stated step count and decide whether durable execution is mandatory. Delegate the arithmetic to the validation script instead of doing it by hand: bash scripts/pfail-calc.sh pfail <steps> [p] (cumulative failure), bash scripts/pfail-calc.sh swarm <agents> (n(n-1) directed-handoff surface, SUP3), bash scripts/pfail-calc.sh trigger <steps> [p] (durability-band verdict). Run bash scripts/pfail-calc.sh selftest to confirm the anchor numbers (63.4%@100, 99.3%@500, swarm 10 = 90)
5. Check determinismLevel annotations — they tell you how reproducible the decision is:
   • deterministic: architectural decision, byte-stable (framework choice, topology, permission policy)
   • semi-deterministic: config is fixed but runtime behavior varies (checkpoint cadence, interrupt placement)
   • non-deterministic: outcome depends on agent reasoning / conversation dynamics (swarm drift, multi-turn routing)

Output format per finding:

[P0] Rule SUP3 (orchestration-patterns): 10-agent fully-connected swarm = 90 directed handoff pathways (n(n-1)), untestable.
→ Switch to a Supervisor topology or constrain handoff edges; do not ship a peer-to-peer swarm above ~5 agents.

[P1] Rule DUR1 (durable-execution): 300-step workflow on a bare retry loop — P(fail) ≈ 95% at p=0.01.
→ Wrap LLM/tool calls as Temporal Activities so a crash resumes from the event log, not from step 1.

Step 2: Output

Produce a structured orchestration review:

## Orchestration Review: [system reviewed]

### Complexity Cliff Audit
- Stated step count: [s] | per-step p assumption: [p] | P(fail) = 1 - (1-p)^s = [%]
- Verdict: [bare retry OK / durable execution MANDATORY]

### P0 — Blocking (must fix before building)
- [finding + specific fix]

### P1 — Required (fix before production)
- [finding + specific fix]

### P2 — Advisory (improves robustness)
- [finding + specific fix]

### Framework / Topology Recommendation
[LangGraph / CrewAI / AutoGen / OpenAI Agents SDK / Claude Agent SDK + Supervisor/Swarm, with rationale tied to a rule]

Anti-Skip Table

Tool / Framework Quick Reference