Pattern Matrix/White Paper/C6

Problem

The Orchestrate pattern has a central conductor that commands each agent in turn: "do this step, then that step." This structure is correct in most scenarios, but it has two hard constraints that eventually hit a ceiling. The central conductor is itself a single point: if it fails, the whole flow stops. And every new agent added requires going back to change the conductor's logic. As the number and variety of agents keep growing and business boundaries fall under different teams, this central point turns from a coordinator into a bottleneck.

Choreography solves exactly this coupling problem at scale. It removes the central conductor and makes each agent an autonomous unit: it subscribes only to the events it cares about, reacts when an event arrives, and emits its result as a new event back onto the shared event stream, reporting to no center. The system's overall behavior is no longer written into a flowchart in one place; it emerges from every agent's local "subscribe–react–publish" rules. Adding a new agent only requires subscribing it to the events it should subscribe to, with no other agent changing a single line.

This deserves to be a pattern of its own because it is not a parameter variant of Orchestrate but the other pole of the collaboration topology: control shifts from centralized to distributed. In structural orientation it is the opposite of centralized collaboration patterns such as fan-out/gather and hierarchical delegation.

Classification: Collaboration × Choreography

This is the first pattern in the Collaboration module that does not fall on one of the six core topology columns, so it needs to be spelled out explicitly, just as the Action module's minimal tool set (A5) falls on "constraint" rather than a concrete topology column.

• Vertical axis · Collaboration: Choreography describes how multiple agents coordinate; there is no single-agent version, so the vertical axis sits firmly in the Collaboration module.
• Horizontal axis · Choreography (emerging topology, not one of the six core columns): The six core topologies (Chain, Route, Parallel, Loop, Hierarchy, Orchestrate) share an implicit premise—there is a designable control point. Chain has order, Route has a router, Parallel has fan-out/gather, Loop has an iterator, Hierarchy has a manager, Orchestrate has a conductor. The defining feature of Choreography is the removal of this control point. So it is not a seventh value on the core axis but the negative pole of the dimension "is control at the center or not." It and Orchestrate are a pair of twins: Orchestrate is coordinated by a conductor, Choreography is coordinated by events.

The reason it remains in the extension ring is methodological: a core topology should recur across several cognitive functions. Choreography is clearest in Collaboration, with adjacent echoes in event-sourced memory, blackboard reasoning, and event-based governance. The current evidence is not yet broad enough to make it a core column. ADPS can revisit that decision when attributed production cases show the topology recurring beyond collaboration.

Solution and mechanics

Choreography is built from four engineering elements:

1. A shared event medium: an event bus (pub/sub), a shared blackboard, or a trace-leaving mechanism (stigmergy). All agents communicate through it indirectly, never calling each other point to point.
2. Autonomous subscribe–react units: each agent declares which events it subscribes to, decides on arrival whether and how to act, and publishes the result back as a new event. It does not know, and does not need to know, who picks up next.
3. Emergent global behavior: no single place holds the full flow. The overall collaboration is the result of all local rules running on the event stream. This is the entire power of Choreography, and the source of all its trouble.
4. Explicit termination and observability: because no center declares "the task is done," boundaries must be defined with an explicit terminal event or with an orchestrated saga's compensation chain. At the same time, every event must carry a correlation ID, or the causal chain cannot be traced when something goes wrong.

Applicability

• Ecosystems with many agent types, owned by different teams, evolving independently: each team owns its own agents and joins by subscribing to the bus, with no need to change a company-wide central orchestrator.
• High-throughput event streams where central orchestration becomes a bottleneck or single point: systems such as risk control, content moderation, and monitoring alerts, where events flow in continuously and high availability is required.
• Highly dynamic environments where the flow cannot be fixed in advance: you cannot enumerate "which steps to take" ahead of time, and can only let agents react to the events at hand.
• Scenarios that require resilience and cannot have a central point of failure: there is no central conductor to fail, and a single agent's failure loses only its share of the function.

Known failure modes

• Deploying Choreography without observability: emergent behavior has no central trace, and when something goes wrong there is no place to start. Choreography depends heavily on Observability (X1)—every event must carry a correlation ID and be replayable along the causal chain. Build the Observability Harness first, then deploy Choreography; reversing the order guarantees trouble.
• Event storms / infinite loops: A emits an event that triggers B, B reacts and emits an event that triggers A, and the loop does not converge. You must enforce idempotency, add event TTLs, and detect loops.
• No one declares completion: after decentralization, "is this task actually finished" becomes a question no one can answer directly. Define it with an explicit terminal event or saga compensation; do not leave it vague.
• Treating Choreography as a cure-all: the default for most systems should be Orchestrate. Choreography earns its place only when scale, coupling, or availability hit a ceiling. Deploying it for the sake of being "advanced" means solving with the hardest-to-debug topology a problem that a single orchestrator would have handled.
• Forcing global constraints onto Choreography: decentralization and governance are naturally at odds. When strongly consistent approvals, quotas, or compliance constraints are needed, either keep a thin central gate (hybrid) or admit that Choreography does not fit that segment.

Verification and metrics

• Event traceability: Test whether a complete causal chain can be reconstructed from the correlation-ID event log. A chain that cannot be replayed is not ready for production choreography.
• Convergence and event storms: Measure whether a collaboration reaches a terminal event or repeats publication until a circuit breaker fires.
• Coupling blast surface: Record which publishers, subscribers, and shared schemas must change when an agent is added or removed. A growing change set indicates that the event contract still carries hidden coupling.
• End-to-end latency: Compare against an orchestrated control and separate queueing, retry, and eventual-consistency wait time.

Reference implementation

# Orchestrate (control group): the center holds the full plan and commands one by one
            orchestrator.run(task):
                for step in plan(task):
                    result = agents[step].execute()      # central scheduling
                    state.update(result)                 # central convergence
                return state.result

            # Choreography: no center, each subscribes + reacts + emits events
            bus = EventBus()                             # shared event medium

            class ChoreographedAgent:
                subscribes_to = [...]                    # I only care about these events
                def on_event(self, e):
                    if self.should_act(e):               # autonomous decision
                        out = self.act(e)
                        bus.publish(out, correlation_id=e.cid)  # after reacting, emit a new event, no report to center

            for a in agents:
                bus.subscribe(a.subscribes_to, a.on_event)
            bus.publish(initial_event)                   # ignition, then it all runs on emergence
            # Completion = a terminal event appears; tracing = thread the full causal chain by correlation_id
            

The four engineering points map to the four elements: EventBus is the shared event medium; subscribes_to plus on_event is the autonomous subscribe–react unit; no place holding the plan is emergence; correlation_id plus the terminal event is explicit termination and observability.

Illustrative scenario

A content risk-control platform may begin with a central orchestrator that calls spam, fraud, policy, and brand detectors in sequence. As detectors and ownership boundaries grow, every new capability requires a shared orchestrator change. In a choreographed design, detection agents subscribe to content.received and publish events such as flag.spam or flag.fraud; a policy agent consumes flags, and an escalation agent publishes case.opened for high-risk cases. A new detector joins through the event contract rather than a direct call graph.

Every event carries a correlation ID and can be replayed by case. A thin orchestrated saga remains at the point that defines whether the case is complete, because pure choreography has no central owner of completion. This hybrid preserves decentralized reaction while centralizing the state that requires a single authoritative answer. Event-driven agent runtimes and interoperability protocols provide implementation references, but production claims should come from attributed deployments.

Related patterns

• Observability (X1): a hard prerequisite dependency. Choreography has no central trace and relies entirely on correlation-ID event logs to trace causality. Without X1, Choreography is undebuggable and cannot go to production.
• Orchestrate (scattered across Hierarchy / Governance): a pair of twins, each other's opposite. Orchestrate is coordinated by a conductor with centralized control; Choreography is coordinated by events with distributed control. Production systems are mostly a mix of the two rather than pure-bred.
• Fan-out/gather (C2): similar in form, different in spirit. Fan-out has a center responsible for fan-out and gather; workers run in parallel but must return to the center to converge. Choreography has no such center; reaction results enter the event stream directly. Fan-out is parallelism with a center; Choreography is collaboration without a center.
• Failure journal (Memory module M4): event sourcing records state changes as an immutable event stream and can provide historical state for a choreographed system.
• Blast-radius control (G2) / Approval gate (G1): naturally at odds with Choreography. For chains that need strong governance constraints, either keep a thin central gate or do not use Choreography in that segment.

Design conclusion

Choreography distributes collaboration control from a central coordinator to each agent's local subscription and publication rules. Events advance the global process. The structure reduces central coupling and requires explicit event contracts, causal tracing, completion criteria, and compensation.