AI Blocks

Use AI blocks to turn prompts, upstream data, and pipeline context into reusable pipeline outputs.

AI blocks bring generative AI into the same pipeline canvas as your loaders, transformers, exporters, and monitors. Use them to summarize data, classify records, draft messages, create structured JSON, generate code, or hand work to Mage Pro AI Sidekick when a task needs project context.

Because AI blocks run inside a Mage pipeline, their answers can become real pipeline outputs. Downstream blocks can consume the final response just like any other block result.

​

Create an AI Block

Add an AI block to a pipeline, then describe the job in YAML.

prompt: |
  Summarize the customer feedback from upstream blocks.
  Return the top themes and recommended next actions.

Run the block from the editor, or run the full pipeline from a trigger. Mage sends the prompt to the configured AI runtime and stores the final response as the block output.

Use AI blocks when you want to:

• summarize reports, logs, feedback, or operational data
• extract structured fields from text
• classify rows or events into business categories
• generate code or SQL for a controlled workflow
• turn upstream block outputs into plain-language recommendations
• automate a decision step before the next pipeline block runs

​

Use an Agent Block

Create an Agent block when you want a Mage Pro pipeline step to run through Mage Pro AI Sidekick. Agent blocks are useful when the block should understand pipeline context, inspect upstream block outputs, and produce a final answer with the same project awareness users expect from Sidekick.

prompt: |
  Use the upstream customer rows to summarize churn risk.
message: Summarize the highest-risk customers and recommend next steps.
settings:
  speed: fast
output:
  level: default
runtime:
  report_name: weekly_churn_review

Agent blocks use the block type agent and are saved as YAML under the agents/ folder. New Agent block YAML does not need a top-level type: agent field; existing AI blocks that already use YAML type: agent still run for compatibility. Agent blocks run as part of the pipeline and return the final Sidekick answer as the block output. While Sidekick works, Mage prints progress and streamed response events to the block logs so users can see that the agent is running.

Use Agent blocks when the task benefits from pipeline context:

• “Read the upstream customer output and explain the highest churn risk.”
• “Review this pipeline run’s logs and summarize what failed.”
• “Compare the two upstream datasets and write a short executive summary.”
• “Use the runtime variables and upstream rows to draft a customer follow-up.”

​

Fields

​

prompt and instructions

The main instruction for a standard AI block is prompt. YAML-backed Agents use instructions for the saved default prompt stored in the agents/ folder. Keep either field clear and specific. Multi-line prompts are easier to read and maintain.

prompt: |
  Write a three-bullet summary of the upstream sales report.
  Include one recommended action for the revenue team.

type: agent
instructions: |
  You are a customer retention analyst.

​

message

An optional user-style request for type: agent blocks. Use instructions for saved standing instructions on YAML-backed Agents, or prompt on standalone AI blocks, and use message for the specific request to answer on this run.

prompt: |
  You are a customer retention analyst.
message: Which accounts need attention this week?

​

settings

Controls how the AI runtime should behave. For agent blocks, speed: fast is a good default when you want a quick operational answer.

settings:
  speed: fast

​

runtime

Optional context that travels with the block run. Use it for business labels, report names, or request metadata that helps the AI understand the job.

runtime:
  customer_segment: enterprise
  report_name: renewal_risk

​

output

Use output when you need the response to follow a predictable shape or control agent block logs.

For Agent blocks, output.level controls how much Sidekick runtime output Mage prints while the block runs:

• default: print streamed answer, narration/status, tool call, and error events.
• all: print every runtime event, including completion and other low-level events.
• none: do not print Sidekick runtime output; the final answer still becomes the block output.

prompt: Review the upstream data and summarize the result.
message: What changed since the last run?
output:
  level: all

Use format when a non-agent AI block should return structured data.

prompt: Extract customer details from the text.
output:
  format:
    name:
      type: string
      description: Customer's full name
    email:
      type: string
      format: email
    priority:
      type: string
      enum:
        - low
        - medium
        - high

​

validation

Use validation when the answer has to meet a business rule before it moves downstream.

prompt: Draft a customer escalation summary.
validation: Make sure the response includes the customer name, issue, impact, and next step.

​

tools

Use tools when a standard AI block should choose and trigger another pipeline as part of the workflow.

prompt: Analyze the request and choose the next processing pipeline.
tools:
  prompt: Choose the best pipeline for the request.
  required: true
  pipelines:
    - uuid: customer_follow_up
      description: Creates customer follow-up tasks.
      variables:
        customer_id:
          type: string

​

Upstream Data

AI and Agent blocks can sit downstream of regular Mage blocks. For Agent blocks, Sidekick receives references to upstream block outputs and can inspect those outputs through Mage instead of copying raw datasets into the prompt.

prompt: |
  Read the upstream customer scores and event history.
  Explain the biggest churn risk in plain English.
message: What should the account team do next?
settings:
  speed: fast

The final answer becomes the AI block output. Downstream blocks can store it, send it to another system, or combine it with additional data.

​

Examples

​

Minimal Summary

prompt: Summarize this document in five bullet points.

​

Structured Extraction

prompt: Extract the renewal request from the customer note.
output:
  format:
    customer_name:
      type: string
    renewal_date:
      type: string
      format: date
    requested_discount:
      type: number
    risk_level:
      type: string
      enum:
        - low
        - medium
        - high

​

Agent Block With Upstream Outputs

prompt: |
  You are reviewing customer health data from upstream blocks.
  Use the available customer scores and recent events to identify retention risk.
message: Summarize the top risks and recommended outreach.
settings:
  speed: fast
runtime:
  audience: account_team

​

Agent Block With No Message

prompt: |
  Use the upstream rows to produce a short operational summary.
settings:
  speed: fast

Use this pattern when the prompt itself is the complete request.

​

Best Practices

• Give the block one clear job.
• Put reusable instructions in instructions for YAML-backed Agents or prompt for standalone AI blocks.
• Put the run-specific ask in message for Agent blocks.
• Use upstream blocks for data and the AI block for interpretation.
• Use structured output when downstream blocks need predictable fields.
• Keep runtime context business-focused, such as segment, audience, or report name.
• Use Agent blocks when project context or upstream block output matters.