> 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://whitepaper.aitech.io/agentforge/yaml/yaml-workflow-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.