Orchestration

Orchestration

An orchestration is a directed acyclic graph (DAG) of steps — wire agents together, add routing logic, run things in parallel, loop over datasets, and checkpoint for human review. Build them visually on the canvas, or define them in JSON.

---

Step Types

Step	What It Does
Agent	Run an agent's full ReAct loop. Pass context from shared state as input. Capture the result as an output key.
LLM	Make a direct LLM call without a full agent loop. Use for single-shot generation, summarization, classification, or prompt templating. Faster and cheaper when tool use isn't needed.
Tool	Execute a specific MCP tool directly — no agent reasoning, no loop. Pass inputs from shared state, write the raw tool output back to state. Ideal for deterministic steps (e.g., run a SQL query, read a vault file, call an API).
Evaluator	Ask an LLM to make a routing decision. Maps decision labels to next steps. Use this to branch based on analysis results.
Parallel	Run multiple branches simultaneously. Each branch runs sequentially (respects shared resources like browser).
Merge	Combine outputs from parallel branches. Strategies: list (accumulate), concat (join text), dict (merge objects).
Loop	Repeat a set of steps N times. Use with transforms to iterate over lists or refine outputs.
Transform	Execute arbitrary Python against the shared state dict. Reshape data, compute values, filter lists.
Human	Pause and ask a human for input via a generated form. Execution resumes when the user responds. Fully resumable.
End	Finalize the workflow.

---

Shared State

Every step reads from and writes to a shared state dictionary. Define the schema upfront:

"state_schema": {
  "query": { "type": "string", "description": "Initial user query" },
  "research_results": { "type": "string", "description": "Raw research output" },
  "analysis": { "type": "string", "description": "Structured analysis" },
  "approved": { "type": "boolean", "default": false }
}

Steps use input_keys to pull from state and output_key to write back. This is how agents hand off work to each other.

---

Example: Research → Report

A complete orchestration: question to published report with human approval.

User Query
    │
    ▼
[1. Research Agent]          → Browses web, parses PDFs, saves raw findings to vault
    │ output: research_raw
    ▼
[2. Parallel Step]
    ├── [3. Data Agent]      → Pulls supporting data from SQL, runs Python analysis
    └── [4. Fact Checker]    → Cross-references key claims via browser
    │ output: data_analysis, verified_facts
    ▼
[5. Merge]                   → Combines data_analysis + verified_facts
    │
    ▼
[6. Writer Agent]            → Synthesizes all inputs into structured report
    │ output: report_draft
    ▼
[7. Quality Evaluator]       → Routes: "approved" → Human Review | "needs_revision" → Writer Agent
    │
    ▼
[8. Human Review]            → Shows draft, collects approval or revision notes
    │
    ▼
[9. Publisher Agent]         → Sends report via email (Gmail MCP), posts to Drive
    │
    ▼
[END]

This orchestration:

• Runs 3 agents in parallel (saves time)
• Routes automatically based on quality assessment
• Loops the writer if revisions are needed
• Pauses for human approval before publishing
• Uses vault to pass files between agents

---

Example: Stock Analysis

[1. Portfolio Analyzer]     → Checks current positions
    │
    ▼
[2. Login Router]           → Evaluator: logged in? → continue | not logged in? → prompt user
    │
    ▼
[3. Parallel Analysis]
    ├── [NSE Stock Analyzer]        → Technical analysis on watchlist
    ├── [Beta Data Fetcher]         → Fetches beta/volatility data
    └── [Current Events Agent]      → Browses news, checks sentiment
    │
    ▼
[4. Merge + Strategy Transform]    → Python: compute risk-adjusted scores
    │
    ▼
[5. Human Approval]                → Shows recommended trades, waits for confirmation
    │
    ▼
[END]

---

Visual Canvas

Open Settings → Orchestrations and click New Orchestration to open the visual DAG editor (powered by React Flow). You can:

• Drag and drop step nodes
• Connect steps with edges
• Configure each step in the right-hand panel
• Define shared state schema
• Run orchestrations directly from the canvas

---

Run Management

• Run — execute an orchestration with an initial prompt/state
• Pause / Resume — mid-workflow pause via Human steps; resume picks up exactly where it left off
• Audit Logs — each run produces a full step-by-step audit trail in Settings → Logs
• Checkpointing — state is checkpointed after each step so runs can resume after restart

---

Tips

• Use LLM steps instead of Agent steps when you don't need tool access — much faster
• Use Transform steps for data manipulation instead of spinning up an agent
• Evaluator steps are powerful for quality checks and routing — define clear, distinct labels
• Human steps with collect_data forms let you pause and inject user decisions mid-pipeline
• Test individual steps before wiring the full DAG