​
1. What is an AI Block?

An AI block is a special type of block in a Mage pipeline that uses a Large Language Model (LLM) to:
  • Generate text or code
  • Return structured data in a defined schema
  • Trigger other pipelines as tools
  • Validate outputs before passing them downstream
AI blocks are configured in YAML and can be designed to:
  • Write and validate executable code
  • Produce structured outputs for downstream blocks
  • Decide which other pipelines to trigger and pass them variables
They integrate directly with Mage’s orchestration engine, allowing AI-generated outputs to be chained together, validated, and reused.

​
2. How to Use an AI Block

  1. Add a new block in your Mage pipeline and set its type to ai.
  2. Write a prompt — the main instruction for the AI.
  3. Optionally define output settings:
    • Code generation (output.code)
    • Structured JSON schema (output.format)
  4. (Optional) Configure tools to allow the AI to trigger other pipelines.
  5. Run the pipeline — Mage will send your prompt and configuration to the AI model, validate the output (if specified), and pass it to the next blocks.
Minimal example: 
prompt: Summarize the input text in two sentences

​
3. AI Block Configuration

​
3.1 Basic Structure

prompt: |
  Enter what you want AI to do
output:
  # Choose either `code` or `format`, not both
  code:
    save: true
    validation: Ensure this code runs without errors
  format:
    name:
      type: string
      description: The name of the person
    age:
      type: integer
      minimum: 0
validation: Validation prompt for output
tools:
  prompt: A prompt to decide which pipeline(s) to trigger
  required: false
  pipelines:
    - uuid: pipeline_uuid
      description: Description of the pipeline
      blocks:
        - uuid: block_uuid
      variables:
        user_id:
          type: string

​
3.2 Fields

​
prompt (Required)

The instruction to send to the AI model.
  • Supports multi-line strings with |.
  • Example:
prompt: |
  Write a haiku about the moon.

​
output

Controls how the AI’s response is validated and structured.
  1. Code Output
output:
  code:
    save: true # Save generated code for reuse
    validation: Ensure no syntax errors
    language: sql # Optional, e.g., python or sql
    profile: default # SQL connection profile from io_config.yaml
    client: postgres # SQL client type
  1. Structured Format Output
output:
  format:
    title:
      type: string
      description: Blog post title
    tags:
      type: array
      items:
        type: string
    published:
      type: boolean
  validation: Ensure all fields are present and valid
  1. Unstructured Output
output: ''

​
tools

Lets the AI trigger other pipelines as part of execution. 
tools:
  prompt: Select a pipeline to process this request
  required: true
  pipelines:
    - uuid: abc123
      description: Cleans and normalizes customer data
      blocks:
        - uuid: block_1
      variables:
        customer_id:
          type: string

​
4. JSON Schema Support for Structured Outputs

The output.format and variables fields use JSON Schema draft-07 (subset) to define:
  • type — string, number, integer, boolean, array, object
  • description — field description
  • enum — allowed values
  • items — item schema for arrays
  • minItems, maxItems — constraints for arrays
  • pattern — regex validation for strings
  • required — list of required keys
  • oneOf, anyOf, allOf — branching validation
  • $ref, $defs — recursive or modular schemas
Example: 
output:
  format:
    email:
      type: string
      format: email
    signup_date:
      type: string
      format: date-time

​
5. Best Practices

  • Use output.code only when expecting executable code.
  • Use output.format for predictable structured outputs.
  • Avoid defining both code and format in the same block.
  • Use multi-line prompts with | for readability.
  • Only include fields you need — minimal configs run faster.
  • Always include a validation prompt for critical outputs.
  • When chaining pipelines, define variables clearly for tool execution.

​
6. Example Configurations

Minimal AI Block 
prompt: Summarize this document in bullet points
AI Block with Structured Output 
prompt: Extract customer details from the text
output:
  format:
    name:
      type: string
      description: Customer's full name
    email:
      type: string
      format: email
    phone:
      type: string
      pattern: "^[0-9\\-]+$"
  validation: Ensure all fields are filled
AI Block Triggering Another Pipeline 
prompt: Analyze sales data and decide next action
tools:
  prompt: Choose a data processing pipeline
  required: true
  pipelines:
    - uuid: sales_analysis_001
      description: Processes daily sales data
      blocks:
        - uuid: clean_data_block
      variables:
        date:
          type: string
          format: date