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:

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

1

Version Declaration

Must be exactly version: '1.0' (with quotes)

2

Blocks Structure

All workflow blocks are defined under the blocks key

3

Block References

Use block names in lowercase with spaces removed (e.g., <aiassistant.content>)

4

Environment Variables

Reference with double curly braces {{VARIABLE_NAME}}

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

# 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:

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