> For the complete documentation index, see [llms.txt](https://whitepaper.aitech.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whitepaper.aitech.io/agentforge/yaml/yaml-workflow-reference.md).

# YAML Workflow Reference

YAML workflows provide a powerful way to define, version, and share workflow configurations in Agent Forge. This reference guide covers the complete YAML syntax, block schemas, and best practices for creating robust workflows.

## Quick Start

Every Agent Forge workflow follows this basic structure:

```yaml
version: '1.0'
blocks:
  start:
    type: starter
    name: Start
    inputs:
      startWorkflow: manual
    connections:
      success: agent-1

  agent-1:
    type: agent
    name: "AI Assistant"
    inputs:
      systemPrompt: "You are a helpful assistant."
      userPrompt: 'Hi'
      model: gpt-4o
      apiKey: '{{OPENAI_API_KEY}}'
```

## Core Concepts

{% stepper %}
{% step %}

#### Version Declaration

Must be exactly `version: '1.0'` (with quotes)
{% endstep %}

{% step %}

#### Blocks Structure

All workflow blocks are defined under the `blocks` key
{% endstep %}

{% step %}

#### Block References

Use block names in lowercase with spaces removed (e.g., `<aiassistant.content>`)
{% endstep %}

{% step %}

#### Environment Variables

Reference with double curly braces `{{VARIABLE_NAME}}`
{% endstep %}
{% endstepper %}

## Block Reference Syntax

The most critical aspect of YAML workflows is understanding how to reference data between blocks:

### Basic Rules

1. **Use the block name** (not the block ID) converted to lowercase with spaces removed
2. **Add the appropriate property** (.content for agents, .output for tools)
3. **When using chat, reference the starter block** as `<start.input>`

### Examples

```yaml
# Block definitions
email-processor:
  type: agent
  name: "Email Agent"
  # ... configuration

data-formatter:
  type: function
  name: "Data Agent"
  # ... configuration

# Referencing their outputs
next-block:
  type: agent
  name: "Next Step"
  inputs:
    userPrompt: |
      Process this email: <emailagent.content>
      Use this formatted data: <dataagent.output>
      Original input: <start.input>
```

### Special Cases

* **Loop Variables**: `<loop.index>`, `<loop.currentItem>`, `<loop.items>`
* **Parallel Variables**: `<parallel.index>`, `<parallel.currentItem>`

## Environment Variables

Use environment variables for sensitive data like API keys:

```yaml
inputs:
  apiKey: '{{OPENAI_API_KEY}}'
  database: '{{DATABASE_URL}}'
  token: '{{SLACK_BOT_TOKEN}}'
```

## Best Practices

* **Keep block names human-readable**: "Email Processor" for UI display
* **Reference environment variables**: Never hardcode API keys
* **Structure for readability**: Group related blocks logically
* **Test incrementally**: Build workflows step by step