Develop DAGsAstro IDE

Blueprint

Public Preview
This feature is in Public Preview.

Blueprint is a template-based Dag authoring mode in the Astro IDE. Platform teams define reusable building blocks in Python. Analysts, analytics engineers, and data scientists assemble those blocks into production Dags through a visual builder and form-driven configuration, without writing Airflow code.

The open-source astronomer/blueprint library powers Blueprint in the Astro IDE, handling blueprint definition, YAML parsing, validation, and Dag generation. See the GitHub repository for the full API reference, blueprint authoring guide, and examples.

How Blueprint works

Blueprint has two sides: platform teams define blueprints; other team members use them.

ConceptWhat it is
BlueprintA reusable building block defined in Python by the platform team. Each blueprint has a configuration schema that controls what users see and configure.
StepAn instance of a blueprint placed on the canvas and configured with specific values.
WorkflowA collection of steps with dependencies and a schedule, stored as a Dag YAML file in your project repository.
Airflow DagThe production Dag generated automatically from the workflow Dag YAML.

Prerequisites

  • An Astro Workspace with Astro IDE access.
  • Workspace Author permissions to use the Astro IDE. You need Workspace Operator permissions to start ephemeral test Deployments.
  • The airflow-blueprint library (version 0.2.0 or later) added to your project’s requirements.txt.
  • At least one blueprint defined in your project with its JSON schema generated. See Set up blueprints.

Set up blueprints

Platform teams complete this setup so blueprints appear in the Astro IDE library for other team members to use.

1

Install the library

Add the following line to your project’s requirements.txt:

airflow-blueprint>=0.2.0
2

Define blueprints in Python

Create blueprint files in your project under dags/templates/. Each blueprint is a Python class that defines a configuration schema and a render() method. The field descriptions you write become the form labels users see in the IDE.

The Astro IDE renders supported Pydantic field types as interactive form fields. The following types are supported:

Pydantic typeUI fieldNotes
strStringField
intNumberFieldstep=1
floatNumberField
boolBooleanField
Literal["a","b"]EnumField
list[str]ArrayField
list[int]ArrayFieldValidates whole numbers on entry
list[float]ArrayFieldValidates numeric input on entry
list (untyped)ArrayFieldTreated as string array
Field(ge=, le=, pattern=, etc.)Constraint propsIncludes exclusiveMin/exclusiveMax, converted to ±1
Field(multiple_of=)NumberField stepOnly for float; int always uses step=1
Optional[T] / T | NoneUnwraps to T’s fieldConstraints from inner type preserved
Optional[Literal["a","b"]]EnumField
Multi-version blueprintMatched variantMatches by discriminator and selectedVersion; defaults to latest

The following types are not supported and render as an unsupported field with a warning in the IDE:

Pydantic typeNotes
str | int (true unions)Shows “unsupported schema type” warning
Nested BaseModel
list[Model]
list[bool]Text input doesn’t fit true/false values
dict[str, T]

For full details on defining blueprints, including configuration models, field validation, and versioning, see the Blueprint GitHub repository.

3

Create the loader file

Create a file at dags/loader.py with the following content:

1# dags/loader.py
2from blueprint import build_all
3
4build_all()

Airflow scans the dags/ folder for Python files that contain Dag objects. This file tells Blueprint to discover all .dag.yaml files in your project, parse them, and register the resulting Dags with Airflow automatically.

4

Generate JSON schemas

For the Astro IDE to discover your blueprints, generate a JSON schema for each blueprint and output it to blueprint/generated-schemas/ in your project:

$blueprint schema <blueprint-name> > blueprint/generated-schemas/<blueprint-name>.schema.json

Repeat this command for each blueprint. The IDE reads this folder to determine which blueprints are available and uses the schemas to render configuration forms.

After you add or update a blueprint, regenerate its schema so the Astro IDE picks up the changes.

5

Commit the schemas

Commit the generated schema files in blueprint/generated-schemas/ to your repository so the IDE can read them when you or your team members open the project.

Build a workflow with Blueprint

After your platform team has set up blueprints, other team members can build workflows in the Astro IDE without writing Airflow code.

1

Open Blueprint mode

  1. Open your project in the Astro IDE.
  2. Click the Blueprint toggle in the top navigation bar. The interface switches to Blueprint mode.
2

Create a workflow

Click New DAG to create a new workflow. Enter a Dag ID and click Generate DAG. Blueprint creates a new Dag YAML file in your project’s dags/ folder.

To open an existing workflow, select it from the workflow list.

3

Add steps from the library

  1. Browse the library panel on the left side of the canvas. The library shows all blueprints your platform team has defined and registered.
  2. Drag a blueprint from the library onto the canvas. Each item you add to the canvas is a step.
  3. Repeat to add more steps.
4

Configure the Dag

To configure Dag properties such as a description, Dag ID, or schedule, click DAG Properties.

5

Configure each step

  1. Click a step on the canvas to open its configuration form in the right panel.
  2. Fill in the fields your platform team has exposed. The IDE marks required fields. Field descriptions explain what each value controls.

The configuration form only shows fields your platform team has explicitly exposed. Operational settings like retry logic, connection credentials, and default values are baked into the blueprint.

6

Set dependencies between steps

To define the order in which steps run, draw a dependency line between them:

  1. Hover over the step that should run first. A connection point appears at the edge.
  2. Click and drag from that connection point to the next step.
  3. Release to create the dependency. An arrow appears between the two steps.

Steps with no dependencies run in parallel.

7

Set the schedule, description, or Dag ID

  1. Open the DAG Properties panel.
  2. Enter a cron expression in the Schedule field.
  3. Configure any additional pipeline-level settings such as Description.

Test a workflow

After building your workflow, test it in an ephemeral Deployment. See Test and run code with the Astro IDE for instructions.

Fix issues

If a task fails or produces unexpected output:

  • Edit the configuration directly: Click the step on the canvas to reopen its configuration form and adjust the values.
  • Use Ask AI to Fix: Click Ask AI to Fix next to an error message for AI-generated suggestions on how to resolve the issue.

After making changes, click Sync to Test to push the updated configuration to the running Deployment without restarting it.

Commit and deploy

After testing, commit your workflow and deploy it. See Deploy code from the Astro IDE or Deploy code from the Astro IDE to Git.