Workflow DSL Reference

Agent Orchestrator workflows are defined in markdown. This reference covers every section and feature of the DSL.

Document Structure

A workflow document has five top-level sections. The # Title heading becomes the workflow name. Sections can appear in any order, but this is the recommended layout:

# Workflow Name

## Inputs
- parameter definitions

## Agents
- agent definitions (### headings)

## Steps
- step definitions (### headings)

## Output
- output expression

Inputs

The ## Inputs section defines the parameters users provide when running a workflow. Each bullet is one input.

## Inputs
- topic: The subject to research (string, required)
- depth: How deep to go — "shallow", "moderate", or "deep" (string, default: "moderate")
- companies: List of companies to analyze (string[], required)
- include_charts: Whether to add charts (boolean, default: false)

Supported types: string, number, boolean, string[], object. The compiler infers the type from context if not explicitly stated.

Agents

The ## Agents section defines the AI agents that run your workflow steps. Each ### Heading creates one agent.

## Agents

### Researcher
Expert at gathering and synthesizing information from multiple sources.
Produces structured summaries with citations.
Model: Sonnet
Tools: rag-engine, github

### Analyst
Data-driven analyst who identifies patterns and generates insights.
Model: Opus

### Writer
Skilled technical writer. Produces clear, well-structured reports.
Model: Haiku

Agent Properties

Available Tool Aliases

Tools refer to MCP servers connected through MCP Gateway Pro. The orchestrator connects to your gateway natively — every server you've configured is available to your agents.

Built-in (always available)

User-configured (add via dashboard)

How tool calls work at runtime

When a step runs, the orchestrator fetches tool schemas from your gateway for the agent's listed servers and passes them to the LLM. The LLM can then call tools in a multi-turn conversation — searching your knowledge base, creating issues, sending messages — before producing its final output.

Tool call failures are returned to the LLM as error results (not exceptions), so the agent can adapt its approach.

Steps

The ## Steps section defines the tasks in your workflow. Each ### Heading is one step. The body text becomes the agent's prompt.

Basic Steps (Sequential)

## Steps

### Research
Research {inputs.topic} thoroughly. Find key facts, trends, and recent developments.

### Write Report
Using the research: {steps.research.output}

Write a comprehensive report on {inputs.topic}. Include an executive summary,
key findings, and actionable recommendations.

Variable Placeholders

Parallel Steps & Fan-Out

Use keywords like "in parallel", "for each", "simultaneously", or "fan out" to run steps concurrently:

### Analyze Companies
For each company in {inputs.companies}, analyze their market position,
recent news, and competitive advantages. Run in parallel.

Approval Gates

Add human-in-the-loop checkpoints by mentioning "approval", "human review", or "sign-off":

### Review Draft
Present the draft for human approval before proceeding.
This step requires manual sign-off.

When an approval gate is reached, the execution pauses and shows Approve/Reject buttons in the console. The workflow only continues when a human approves.

Conditional Steps

Steps can run conditionally based on inputs or prior step outputs:

### Generate Charts
Only run if include_charts is true.
Create visualizations for the key metrics identified in the analysis.

Retries & Feedback Loops

Use "retry", "revision", or "send back" to create feedback loops:

### Quality Check
Review the report. If it doesn't meet quality standards, send it back
to the Write Report step for revision. Maximum 3 attempts.

Coordination Patterns

Output

The ## Output section specifies which step's output becomes the workflow's final result:

## Output
steps.write_report.output

If omitted, the compiler defaults to the last step's output. The compiler also infers the output_type from context:

Constraints & Settings

Optional ## Constraints or ## Settings section for global limits:

## Constraints
- Max total tokens: 100000
- Timeout: 30 minutes
- Max concurrent agents: 3

YAML Frontmatter (Configuration)

Add YAML frontmatter at the top of your workflow to configure execution behavior. All settings are optional.

---
# Pin specific model versions (override logical names)
models:
  sonnet: claude-sonnet-4-5
  haiku: claude-haiku-4-5
  opus: claude-opus-4

# Set a default model for all agents (default: sonnet)
default_model: sonnet

# Execute tool calls in parallel (default: true)
parallel_tools: true

# Output format hint for the final step
output: markdown

# Style guidance applied to all agent outputs
style: "Write in a professional but approachable tone. Use bullet points for lists."
---

# My Workflow
...

Configuration Reference

---
output: markdown
parallel_tools: true
style: "Professional tone. Use data tables where possible."
---

# Competitive Analysis

## Inputs
- company: The company to analyze (string, required)
- competitors: List of competitors (string[], required)

## Agents

### Researcher
Expert market researcher. Gathers factual data about companies.
Model: Sonnet
Tools: rag-engine

### Analyst
Strategic analyst who identifies competitive advantages and threats.
Model: Opus

## Steps

### Research Company
Research {inputs.company} — products, market position, recent news, financials.

### Research Competitors
For each competitor in {inputs.competitors}, research their products,
market position, and strategy. Run in parallel.

### Analyze
Using the research on {inputs.company}: {steps.research_company.output}

And competitor research: {steps.research_competitors.output}

Produce a competitive analysis with SWOT matrix, market positioning map,
and strategic recommendations.

### Review
Present the analysis for human approval before finalizing.
Requires sign-off.

## Output
steps.analyze.output