Orchestration Patterns

The platform includes three governance-aware orchestration patterns for coordinating multiple agents. All patterns route every LLM call through the gateway, so the full governance chain (rate limits, cost budgets, PII scanning, model allowlists, HITL) applies to every step.

Sequential Pipeline

Ordered execution of agent stages where each stage’s output becomes the next stage’s input.


Stage 1 → Stage 2 → Stage 3 → Stage 4
  ↓         ↓         ↓         ↓
Gov Chain  Gov Chain  Gov Chain Gov Chain

Use cases: analyze-then-synthesize workflows, multi-step document processing, review chains.

Example


curl -X POST https://api.curate-me.ai/gateway/admin/runners/orchestration/pipeline \
  -H "X-CM-API-Key: cm_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_name": "Code Review Pipeline",
    "total_budget_usd": 2.0,
    "input_data": "Review this pull request...",
    "pass_output_to_next": true,
    "stages": [
      {
        "name": "Security Review",
        "agent_prompt": "Analyze this code for security vulnerabilities.",
        "model": "gpt-4o",
        "cost_budget_usd": 0.50
      },
      {
        "name": "Performance Review",
        "agent_prompt": "Analyze this code for performance issues. Previous review: {previous_output}",
        "model": "gpt-4o",
        "cost_budget_usd": 0.50
      },
      {
        "name": "Summary",
        "agent_prompt": "Synthesize these reviews into a final recommendation.",
        "model": "gpt-4o-mini",
        "cost_budget_usd": 0.25
      }
    ]
  }'

Features

Per-stage cost budgets — auto-split from total budget if not specified
Output chaining — each stage receives the previous stage’s output as context
Governance pre-flight — each stage is checked against the governance chain before execution
Automatic rollback — configurable per stage (rollback_on_failure: true)
Stage timeouts — prevent runaway execution (default: 120s per stage)

Parallel Fan-Out

Concurrent agent execution with configurable quorum voting and optional synthesis.


┌─ Branch 1 (Critic A) → Gov Chain → LLM ─┐
├─ Branch 2 (Critic B) → Gov Chain → LLM ─┤→ Quorum → Synthesis
└─ Branch 3 (Critic C) → Gov Chain → LLM ─┘

Use cases: multi-reviewer code review, A/B prompt comparison, ensemble evaluation, consensus-based decisions.

Example


curl -X POST https://api.curate-me.ai/gateway/admin/runners/orchestration/fan-out \
  -H "X-CM-API-Key: cm_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "fanout_name": "Multi-Reviewer Assessment",
    "total_budget_usd": 5.0,
    "input_data": "Evaluate this product description for accuracy...",
    "quorum": {
      "strategy": "majority",
      "cancel_remaining_on_quorum": true
    },
    "synthesis_prompt": "Combine these reviews into a single recommendation.",
    "branches": [
      {
        "name": "Reviewer A",
        "agent_prompt": "Review for factual accuracy.",
        "model": "gpt-4o",
        "weight": 1.0
      },
      {
        "name": "Reviewer B",
        "agent_prompt": "Review for clarity and tone.",
        "model": "claude-sonnet-4-6-20250918",
        "weight": 1.0
      },
      {
        "name": "Reviewer C",
        "agent_prompt": "Review for completeness.",
        "model": "gemini-2.5-pro",
        "weight": 1.0
      }
    ]
  }'

Quorum Strategies

Strategy	Description
`all`	All branches must succeed
`majority`	More than 50% must succeed
`n_of_m`	Exactly N successes required (`required_count`)
`first`	First successful branch wins

Features

Weighted voting — branches can have different weights
Early cancellation — cancel remaining branches once quorum is reached
Per-branch cost caps — prevent any single branch from overspending
Optional synthesis — combine branch outputs into a final result

Hierarchical Delegation

A manager agent produces a delegation plan and specialist agents execute the tasks.


           Manager Agent
          ┌──────┼──────┐
          ↓      ↓      ↓
        Eng   Design    PM
     (depth 1) (depth 1) (depth 1)

Use cases: project planning, task decomposition, expert routing, multi-discipline analysis.

Example


curl -X POST https://api.curate-me.ai/gateway/admin/runners/orchestration/delegate \
  -H "X-CM-API-Key: cm_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "delegation_name": "Feature Planning",
    "total_budget_usd": 10.0,
    "max_delegation_depth": 2,
    "manager_prompt": "You are a technical PM. Break this feature request into tasks for Engineering, Design, and QA specialists.",
    "manager_model": "gpt-4o",
    "specialist_specs": [
      {"name": "Engineer", "prompt": "Provide technical implementation plan.", "model": "gpt-4o"},
      {"name": "Designer", "prompt": "Provide UX recommendations.", "model": "claude-sonnet-4-6-20250918"},
      {"name": "QA", "prompt": "Provide test plan.", "model": "gpt-4o-mini"}
    ]
  }'

Features

Depth limiting — prevent infinite delegation chains (max_delegation_depth: 1-10)
Transitive governance — cost budget inherited from manager, tracked per-specialist
Tree structure — full delegation tree persisted to MongoDB for replay
Recursive delegation — specialists can delegate to sub-specialists within depth limits

Listing Executions


# List all orchestration executions
curl "https://api.curate-me.ai/gateway/admin/runners/orchestration/executions?limit=20" \
  -H "X-CM-API-Key: cm_sk_xxx"
 
# Get a specific execution
curl "https://api.curate-me.ai/gateway/admin/runners/orchestration/executions/pipe_abc123def456" \
  -H "X-CM-API-Key: cm_sk_xxx"

Execution IDs are prefixed by pattern type: pipe_* for pipelines, fan_* for fan-outs, del_* for delegations.

Status Lifecycle

All patterns follow the same status lifecycle:

Status	Meaning
`pending`	Created, not yet started
`running`	In progress
`completed`	Finished successfully
`failed`	Encountered an error
`cancelled`	Cancelled (fan-out branches only)
`rolled_back`	Rolled back after failure (pipeline stages only)

Audit Trail

Every orchestration action is recorded to the runner_orchestration_events collection with timestamps, costs, governance decisions, and error details. Use the compliance export to extract these events for review.

Backend Implementation

File	Purpose
`src/services/runner_control_plane/orchestration_patterns.py`	Three orchestrators + base class
`src/gateway/gateway_runner_orchestration.py`	Gateway admin API routes