Core concepts¶

The provider connects Airflow to a model through a connection, runs the call or the agent loop inside a task, gives agents tools through toolsets, and returns results through XCom.

Connections choose the model¶

common.ai is built on pydantic-ai, so the model vendor (OpenAI, Anthropic, Google, Bedrock, …) is picked by the connection llm_conn_id points at, so switching providers later is a connection change, not a Dag rewrite. Most connections use the generic pydanticai type, but Azure OpenAI, Bedrock, and Vertex AI also have their own connection types (pydanticai_azure, pydanticai_bedrock, pydanticai_vertex) for provider-specific authentication.

The model name lives on the connection in provider:model form, and model_id on an operator overrides it. Pydantic AI connection has the full resolution order, and Provider fallback explains how one connection can name others to fail over to.

Operators and decorators do the work¶

Every operator ships with a matching @task decorator, so a Dag can use whichever style it already uses. LLMOperator sends one prompt and returns one answer. AgentOperator runs a multi-turn loop in which the model calls tools until it is done. The other operators are specializations of the first: branching on the answer, analyzing a file, generating SQL, comparing schemas, or submitting many prompts as one batch. Choosing an operator has the selection table.

The AI step is orchestrated by Airflow: the model calls, the agent loop, and any tools run in the Airflow worker by default, where they get retries, logging, and observability like any other task. The exception is SandboxToolset, which exists so that code the model writes runs somewhere else.

Toolsets give agents reach¶

A toolset is what an agent is allowed to call. The provider ships toolsets that wrap Airflow hooks, SQL databases, files through DataFusion, MCP servers, Agent Skills, a sandboxed shell, and vendor-managed agents. An agent’s reach is exactly the toolsets you register on it. Toolsets compares them and Securing agent tools explains the defense layers.

Existing LangChain tools are not locked out either: pydantic-ai ships pydantic_ai.ext.langchain.LangChainToolset upstream, which wraps LangChain tools for a common.ai agent, and the provider’s own airflow_toolset_to_langchain_tools() converts the other way, from Airflow-managed toolsets into LangChain tools (see LangChain tools in both directions).

Hooks are the plumbing underneath¶

The provider’s hooks bridge an Airflow connection to a specific framework’s model objects. Each hook is a thin adapter: it reads credentials and config from the connection, then returns native framework objects (a pydantic_ai Agent / Model, a LangChain BaseChatModel or Embeddings, an MCP client, …). Operators and @task decorators use these hooks internally, and you reach for one directly only when you want the framework object in a plain @task.

Hook	When to use
`PydanticAIHook`	Default for `common.ai` operators (`LLMOperator`, `AgentOperator`, `LLMBranchOperator`, …). Returns a pydantic-ai `Agent` / `Model`. See Using the hook directly: PydanticAIHook.
`LangChainHook`	Direct LangChain access for tasks that compose `Runnable`\s, use the LangChain agent surface, or need LangChain-native chat / embedding model objects. Independent of the pydantic-ai-backed operators. See LangChain models: LangChainHook.
`LlamaIndexHook`	Backs the LlamaIndex `LlamaIndexEmbeddingOperator` and `LlamaIndexRetrievalOperator`. Returns LlamaIndex-native `BaseEmbedding` / `LLM` objects (OpenAI by default). For non-OpenAI vendors, pass a pre-built `BaseEmbedding` / `LLM` instance straight to the operator and bypass the hook. See Using LlamaIndex directly: LlamaIndexHook.
`MCPHook`	Backs `MCPToolset` (see MCP servers: MCPToolset) for agent tasks that call tools on a remote MCP server. Configure the connection via MCP server connection. See MCPHook.

Results flow through XCom¶

Every operator pushes its result to XCom like any other task. A plain string arrives as a string. A Pydantic output_type arrives as the model instance, typed, so a downstream task can use attribute access. Structured output and XCom explains how the class is registered for deserialization and where that stops working.