DAG Orchestration Guide

Build governance-aware multi-agent workflows using the gateway’s DAG orchestration engine. Define pipelines as directed acyclic graphs with conditional branching, parallel execution, and per-stage cost budgets.

Reference: For API details and pattern specifications, see Orchestration Patterns.

When to Use Each Pattern

Pattern	Use When	Example
Sequential	Output of one agent feeds the next	Summarize -> Translate -> Format
Parallel Fan-Out	Multiple agents analyze the same input	Sentiment + Topic + Entity extraction
Hierarchical	A manager delegates to specialists	Triage -> Route to domain expert

Step 1: Define a Sequential Pipeline

A code review pipeline where each agent builds on the previous output:


curl -X POST https://api.curate-me.ai/gateway/orchestration/execute \
  -H "X-CM-API-Key: cm_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "sequential",
    "agents": [
      {
        "agent_id": "code_reviewer",
        "model": "gpt-4o",
        "system_prompt": "Review this code for bugs and security issues.",
        "max_cost": 0.50
      },
      {
        "agent_id": "style_checker",
        "model": "gpt-4o-mini",
        "system_prompt": "Check this code review for style and formatting issues.",
        "max_cost": 0.10
      },
      {
        "agent_id": "summary_writer",
        "model": "gpt-4o-mini",
        "system_prompt": "Summarize the code review findings into a concise report.",
        "max_cost": 0.05
      }
    ],
    "input": {
      "code": "def fetch_user(id):\n  return db.query(f\"SELECT * FROM users WHERE id={id}\")"
    }
  }'

Each agent receives the previous agent’s output as input. The max_cost field sets a per-stage budget — if an agent exceeds it, the pipeline stops.

Step 2: Build a Parallel Fan-Out

Multiple agents analyze the same input concurrently:


curl -X POST https://api.curate-me.ai/gateway/orchestration/execute \
  -H "X-CM-API-Key: cm_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "parallel",
    "agents": [
      {
        "agent_id": "sentiment",
        "model": "gpt-4o-mini",
        "system_prompt": "Analyze the sentiment of this text. Return: positive, negative, or neutral."
      },
      {
        "agent_id": "topics",
        "model": "gpt-4o-mini",
        "system_prompt": "Extract the main topics from this text as a JSON array."
      },
      {
        "agent_id": "entities",
        "model": "gpt-4o-mini",
        "system_prompt": "Extract named entities (people, places, organizations) as a JSON array."
      }
    ],
    "input": {
      "text": "OpenAI released GPT-5 yesterday in San Francisco. Analysts are optimistic."
    },
    "aggregation": "merge"
  }'

Results from all agents are merged into a single response. Use "aggregation": "vote" for quorum-based decision making.

Step 3: Conditional Branching

Route to different agents based on a previous agent’s output:


{
  "pattern": "sequential",
  "agents": [
    {
      "agent_id": "classifier",
      "model": "gpt-4o-mini",
      "system_prompt": "Classify this support ticket. Return JSON: {\"category\": \"billing|technical|general\"}"
    },
    {
      "agent_id": "billing_expert",
      "model": "gpt-4o",
      "system_prompt": "You are a billing support expert.",
      "condition": "$.category == 'billing'"
    },
    {
      "agent_id": "tech_expert",
      "model": "gpt-4o",
      "system_prompt": "You are a technical support expert.",
      "condition": "$.category == 'technical'"
    },
    {
      "agent_id": "general_agent",
      "model": "gpt-4o-mini",
      "system_prompt": "You handle general inquiries.",
      "condition": "$.category == 'general'"
    }
  ]
}

Condition Syntax

Syntax	Example	Description
`$.field == 'value'`	`$.category == 'billing'`	Exact match
`$.field != 'value'`	`$.status != 'resolved'`	Not equal
`$.score > N`	`$.confidence > 0.8`	Numeric comparison
`$.tags contains 'X'`	`$.tags contains 'urgent'`	Array contains
`$.field exists`	`$.metadata exists`	Field is present

Per-Stage Cost Budgets

Each agent in the pipeline can have its own cost ceiling:


{
  "agents": [
    {
      "agent_id": "analyzer",
      "model": "gpt-4o",
      "max_cost": 1.00,
      "system_prompt": "..."
    },
    {
      "agent_id": "summarizer",
      "model": "gpt-4o-mini",
      "max_cost": 0.10,
      "system_prompt": "..."
    }
  ]
}

If a stage exceeds its budget, the pipeline returns a partial result with the stages that completed successfully. The org-level daily budget still applies across all stages.

Monitoring in the Dashboard

Orchestration runs appear in the dashboard under Workflow Builder:

Pipeline view — see each stage’s status, cost, and duration
DAG visualization — visual graph of agent dependencies and conditional branches
Cost breakdown — per-stage and total pipeline cost
Error details — which stage failed and why

Listing Executions


# List recent orchestration runs
curl https://api.curate-me.ai/gateway/orchestration/executions \
  -H "X-CM-API-Key: cm_sk_xxx"
 
# Get details for a specific run
curl https://api.curate-me.ai/gateway/orchestration/executions/{execution_id} \
  -H "X-CM-API-Key: cm_sk_xxx"

Error Handling

Scenario	Behavior
Agent exceeds `max_cost`	Stage stops, partial result returned
Agent returns invalid JSON (for conditions)	Next stage receives raw text
Rate limit hit mid-pipeline	Pipeline pauses, retries after cooldown
Governance blocks a stage	Pipeline stops, blocked stage’s error returned
Network error to provider	Upstream resilience retries with exponential backoff

Python SDK


from curate_me import CurateMe
 
client = CurateMe(api_key="cm_sk_xxx")
 
result = client.workflows.run(
    workflow_id="code_review_pipeline",
    input={"code": "def foo(): pass"},
)
 
for stage in result.stages:
    print(f"{stage.agent_id}: ${stage.cost:.4f} ({stage.duration_ms}ms)")

Next Steps

Orchestration Patterns — API reference for all three patterns
Cost Attribution — track costs by pipeline and stage
Workflow Builder — visual pipeline editor in the dashboard
Gateway Quickstart — get started with the gateway