Quick start¶

This guide installs the provider, configures a connection, and runs a first LLM task.

Before you start: this assumes a working Installation of Airflow® (Airflow 3.0+) already exists, you have an API key for the LLM provider you plan to use, and step 3 below makes a real, billed API call to that provider.

1. Install¶

Install the provider together with the extra matching the model SDK you plan to use — openai, anthropic, google, or bedrock (see apache-airflow-providers-common-ai for the full list of available extras). Replace <extra> below with the one you need:

pip install "apache-airflow-providers-common-ai[<extra>]"

2. Configure the connection¶

Every LLM call goes through a Pydantic AI connection (conn_type pydanticai, default connection id pydanticai_default). The model is set in provider:model format and the API key goes in the password field. See Pydantic AI Connection for the full reference, including providers that don’t need an API key (Bedrock, Vertex AI).

The quickest way to set one up is an environment variable. Replace openai:gpt-5.6-sol with a model you have access to and sk-... with your actual API key:

export AIRFLOW_CONN_PYDANTICAI_DEFAULT='{"conn_type": "pydanticai", "password": "sk-...", "extra": {"model": "openai:gpt-5.6-sol"}}'

Or add it through the Airflow UI (Admin > Connections) or the CLI (airflow connections add).

3. Write your first Dag¶

The @task.llm decorator turns a function that returns a prompt string into a task that sends that prompt to the LLM and returns its response:

airflow/providers/common/ai/example_dags/example_quickstart.py[source]

from airflow.sdk import dag, task


@dag(schedule=None, tags=["example"])
def quickstart_llm():
    @task.llm(llm_conn_id="pydanticai_default", system_prompt="You are a helpful assistant. Be concise.")
    def summarize(text: str):
        return f"Summarize this article: {text}"

    summarize(
        "Apache Airflow is a platform for programmatically authoring, scheduling, and monitoring workflows."
    )


quickstart_llm()

Run it like any other Dag (airflow dags test quickstart_llm) and the summarize task pushes the LLM’s response to XCom.

Structured output¶

Need typed data instead of a string? Set output_type to a Pydantic BaseModel and the model instance is pushed to XCom unchanged. See the “Structured Output” section of the LLMOperator guide for the full example and its XCom-deserialization requirements.

Where to go next¶

Common AI Operators — the full set of operators and @task decorators (file analysis, SQL, branching, schema comparison).
Toolsets — Airflow Hooks as AI Agent Tools — give an agent tools built from Airflow hooks, SQL databases, or MCP servers.
AgentOperator & @task.agent — run a multi-turn agent that reasons and calls tools instead of a single prompt-response call.
Observability (OpenTelemetry tracing) — trace LLM and tool calls with OpenTelemetry.