YAML Workflow Reference

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

Quick Start

Every MyBotBox 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

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

Block Structure: All workflow blocks are defined under the blocks key

Block References: Use block names in lowercase without spaces (e.g., <aiassistant.content>)

Environment Variables: Reference using double curly braces {{VARIABLE_NAME}}

Block Types

MyBotBox supports several core block types, each with specific YAML schemas:

Starter Block

Workflow entry point with support for manual, webhook, and scheduled triggers

Agent Block

AI-powered processing with tool support and structured output

Function Block

Execute custom JavaScript/TypeScript code

API Block

HTTP requests to external services

Condition Block

Conditional branching based on boolean expressions

Router Block

AI-powered intelligent routing to multiple paths

Loop Block

Iterative processing with for and forEach loops

Parallel Block

Concurrent execution across multiple instances

Webhook Block

Webhook triggers for external integrations

Evaluator Block

Validation of outputs against defined criteria and metrics

Workflow Block

Execute other workflows as reusable components

Response Block

Format final workflow output

Block Reference Syntax

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

Basic Rules

Use the block name (not block ID), converted to lowercase without spaces
Add the appropriate property (.content for agents, .output for tools)
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 user-friendly: "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

Next Steps

Block Reference Syntax - Detailed referencing rules
Complete Block Schemas - All available block types
Workflow Examples - Real-world workflow patterns