> 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-schema.md).

# YAML Schema

This section contains the complete YAML schema definitions for all available block types in Agent Forge. Each block type has specific configuration requirements and output formats.

### Core Blocks

These are the essential building blocks for creating workflows:

<table data-view="cards"><thead><tr><th>Title</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td>Starter Block<br>Workflow entry point supporting manual triggers, webhooks, and schedules</td><td><a href="file:///yaml/blocks/starter">file:///yaml/blocks/starter</a></td></tr><tr><td>Agent Block<br>AI-powered processing with LLM integration and tool support</td><td><a href="file:///yaml/blocks/agent">file:///yaml/blocks/agent</a></td></tr><tr><td>Function Block<br>Custom JavaScript/TypeScript code execution environment</td><td><a href="file:///yaml/blocks/function">file:///yaml/blocks/function</a></td></tr><tr><td>Response Block<br>Format and return final workflow results</td><td><a href="file:///yaml/blocks/response">file:///yaml/blocks/response</a></td></tr></tbody></table>

### Logic & Control Flow

Blocks for implementing conditional logic and control flow:

<table data-view="cards"><thead><tr><th>Title</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td>Condition Block<br>Conditional branching based on boolean expressions</td><td><a href="file:///yaml/blocks/condition">file:///yaml/blocks/condition</a></td></tr><tr><td>Router Block<br>AI-powered intelligent routing to multiple paths</td><td><a href="file:///yaml/blocks/router">file:///yaml/blocks/router</a></td></tr><tr><td>Loop Block<br>Iterative processing with for and forEach loops</td><td><a href="file:///yaml/blocks/loop">file:///yaml/blocks/loop</a></td></tr><tr><td>Parallel Block<br>Concurrent execution across multiple instances</td><td><a href="file:///yaml/blocks/parallel">file:///yaml/blocks/parallel</a></td></tr></tbody></table>

### Integration Blocks

Blocks for connecting to external services and systems:

<table data-view="cards"><thead><tr><th>Title</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td>API Block<br>HTTP requests to external REST APIs</td><td><a href="file:///yaml/blocks/api">file:///yaml/blocks/api</a></td></tr><tr><td>Webhook Block<br>Webhook triggers for external integrations</td><td><a href="file:///yaml/blocks/webhook">file:///yaml/blocks/webhook</a></td></tr></tbody></table>

### Advanced Blocks

Specialized blocks for complex workflow patterns:

<table data-view="cards"><thead><tr><th>Title</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td>Evaluator Block<br>Validate outputs against defined criteria and metrics</td><td><a href="file:///yaml/blocks/evaluator">file:///yaml/blocks/evaluator</a></td></tr><tr><td>Workflow Block<br>Execute other workflows as reusable components</td><td><a href="file:///yaml/blocks/workflow">file:///yaml/blocks/workflow</a></td></tr></tbody></table>

### Common Schema Elements

All blocks share these common elements:

#### Basic Structure

```yaml
block-id:
  type: <block-type>
  name: <display-name>
  inputs:
    # Block-specific configuration
  connections:
    # Connection definitions
```

#### Connection Types

* **success**: Target block for successful execution
* **error**: Target block for error handling (optional)
* **conditions**: Multiple paths for conditional blocks

#### Environment Variables

Use double curly braces for environment variables:

```yaml
inputs:
  apiKey: '{{API_KEY_NAME}}'
  endpoint: '{{SERVICE_ENDPOINT}}'
```

#### Block References

Reference other block outputs using the block name in lowercase:

```yaml
inputs:
  userPrompt: <blockname.content>
  data: <functionblock.output>
  originalInput: <start.input>
```

### Validation Rules

All YAML blocks are validated against their schemas:

1. **Required fields**: Must be present
2. **Type validation**: Values must match expected types
3. **Enum validation**: String values must be from allowed lists
4. **Range validation**: Numbers must be within specified ranges
5. **Pattern validation**: Strings must match regex patterns (where applicable)

### Quick Reference

#### Block Types and Properties

| Block Type | Primary Output  | Common Use Cases                      |
| ---------- | --------------- | ------------------------------------- |
| starter    | `.input`        | Workflow entry point                  |
| agent      | `.content`      | AI processing, text generation        |
| function   | `.output`       | Data transformation, calculations     |
| api        | `.output`       | External service integration          |
| condition  | N/A (branching) | Conditional logic                     |
| router     | N/A (branching) | Intelligent routing                   |
| response   | N/A (terminal)  | Final output formatting               |
| loop       | `.results`      | Iterative processing                  |
| parallel   | `.results`      | Concurrent processing                 |
| webhook    | `.payload`      | External triggers                     |
| evaluator  | `.score`        | Output validation, quality assessment |
| workflow   | `.output`       | Sub-workflow execution, modularity    |

#### Required vs Optional

* **Always required**: `type`, `name`
* **Usually required**: `inputs`, `connections`
* **Context dependent**: Specific input fields vary by block type
* **Always optional**: `error` connections, UI-specific fields