DAG Workflows & Orchestration

Orchestrate multi-agent teams using directed acyclic graphs (DAGs). Define dependencies, run steps in parallel, and add governance gates for human approval.

Overview

Workflows let you chain multiple agents together in a structured pipeline. Each step in the workflow is a node in a DAG, with explicit dependencies between steps.

DAG execution — Steps run as soon as their dependencies complete
Parallel by default — Independent steps run concurrently
Governance gates — Pause for human review at critical points
Cron scheduling — Run workflows on a schedule
Cost tracking — Per-workflow budget with real-time monitoring

DAG Structure

A workflow is defined as a YAML file with nodes (steps) and edges (dependencies):

# .nestor/workflows/code-review.yaml
name: Code Review Pipeline
description: Automated code review with multiple specialists

# Steps are DAG nodes
steps:
  - id: analyze
    agent: analyzer
    prompt: "Analyze the codebase structure and identify areas for review"

  - id: security-review
    agent: security-expert
    prompt: "Review for security vulnerabilities"
    depends_on: [analyze]

  - id: perf-review
    agent: perf-expert
    prompt: "Review for performance issues"
    depends_on: [analyze]

  - id: style-review
    agent: style-checker
    prompt: "Check code style and best practices"
    depends_on: [analyze]

  - id: summarize
    agent: reviewer
    prompt: "Compile all reviews into a final report"
    depends_on: [security-review, perf-review, style-review]

In this example, the three review steps run in parallel after the analysis step completes. The summary step waits for all three reviews.

Writing Workflows

Step Configuration

Each step supports the following properties:

Property	Type	Description
`id`	string	Unique step identifier
`agent`	string	Agent name to execute this step
`prompt`	string	Task description for the agent
`depends_on`	string[]	Step IDs that must complete first
`timeout`	number	Max execution time in seconds
`retry`	number	Number of retries on failure (default: 0)
`gate`	boolean	Pause for human approval before this step
`condition`	string	Expression that must be true to run this step

Passing Data Between Steps

Each step's output is available to downstream steps via template variables:

steps:
  - id: gather
    agent: researcher
    prompt: "Find relevant documentation for the auth module"

  - id: write
    agent: coder
    prompt: "Using this research: {{steps.gather.output}}, implement the auth module"
    depends_on: [gather]

Parallel Execution

Steps without dependencies between them run in parallel automatically. You can control concurrency:

name: Batch Review
max_concurrency: 3  # max 3 agents running at once

steps:
  - id: review-1
    agent: reviewer
    prompt: "Review module A"

  - id: review-2
    agent: reviewer
    prompt: "Review module B"

  - id: review-3
    agent: reviewer
    prompt: "Review module C"

  - id: merge
    agent: lead
    prompt: "Merge all reviews"
    depends_on: [review-1, review-2, review-3]

Governance Gates

Add human-in-the-loop checkpoints at critical steps:

steps:
  - id: plan
    agent: architect
    prompt: "Create a migration plan for the database"

  - id: review-gate
    gate: true
    prompt: "Review the migration plan before execution"
    depends_on: [plan]

  - id: execute
    agent: dba
    prompt: "Execute the approved migration plan"
    depends_on: [review-gate]

When the workflow reaches a gate, it pauses and notifies you via the CLI or Studio. You can approve, reject, or modify the plan before continuing.

Built-in Templates

Nestor ships with 4 workflow templates to get started quickly:

Template	Description
`code-review`	Multi-specialist code review with security, performance, and style checks
`feature-dev`	Plan → implement → test → review pipeline
`bug-fix`	Analyze → reproduce → fix → verify workflow
`documentation`	Generate docs from code with review gate

# Create a workflow from a template
nestor workflow create --template code-review --name my-review

# This creates .nestor/workflows/my-review.yaml

Scheduling

Run workflows on a cron schedule:

# In the workflow YAML
name: Nightly Review
schedule: "0 2 * * *"  # Every day at 2 AM
steps:
  - id: review
    agent: reviewer
    prompt: "Review all PRs opened today"

# Or via CLI
nestor workflow schedule my-review --cron "0 2 * * *"

# List scheduled workflows
nestor workflow list --scheduled

CLI Commands

# Run a workflow
nestor workflow run code-review.yaml

# Run with a specific input
nestor workflow run code-review.yaml --input "Review the auth module"

# List all workflows
nestor workflow list

# Show workflow status
nestor workflow status <run-id>

# Cancel a running workflow
nestor workflow cancel <run-id>

# View workflow history
nestor workflow history