Building, Configuring, and Automating with LLMs

Only in Mage Pro.Try our fully managed solution to access this advanced feature.

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

Add a new block in your Mage pipeline and set its type to ai.
Write a prompt — the main instruction for the AI.
Optionally define output settings:
- Code generation (output.code)
- Structured JSON schema (output.format)
(Optional) Configure tools to allow the AI to trigger other pipelines.
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.

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

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

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

Adventure starts here

Deployment architecture

Getting started

Mage Agent

CI/CD

Pro only features

Infrastructure

Migration guides

Global hooks

Mage Pro API

Building, Configuring, and Automating with LLMs

1. What is an AI Block?

2. How to Use an AI Block

3. AI Block Configuration

3.1 Basic Structure

3.2 Fields

prompt (Required)

output

tools

4. JSON Schema Support for Structured Outputs

5. Best Practices

6. Example Configurations

​1. What is an AI Block?

​2. How to Use an AI Block

​3. AI Block Configuration

​3.1 Basic Structure

​3.2 Fields

​prompt (Required)

​output

​tools

​4. JSON Schema Support for Structured Outputs

​5. Best Practices

​6. Example Configurations

1. What is an AI Block?

2. How to Use an AI Block

3. AI Block Configuration

3.1 Basic Structure

3.2 Fields

prompt (Required)

output

tools

4. JSON Schema Support for Structured Outputs

5. Best Practices

6. Example Configurations