AIP-101: Appendix - Reference Implementation

Status

Table of Contents

Design Decisions

This section documents the key architectural decisions for the AI Assistant plugin design. Each decision establishes choices that have cascading implications throughout the AIP and implementation strategy. Rather than presenting alternatives as mere options, this section documents what was chosen, why, what trade-offs it introduces, and how those consequences shape other parts of the proposal.

Delivery method (standalone plugin or the common.ai  Airflow provider)

Resolution: Deliver as a standalone plugin package - not as part of the common.ai  provider package.

Considered alternatives:

• Existing common.ai  provider: Providers follow Airflow's provider lifecycle.

Rationale for standalone plugin vs. provider

• Providers are mostly for operator/hook packages: Airflow providers are designed to package operators, hooks, transfer utilities, and executors for specific platforms (AWS, GCP, etc.). They follow a specific contract: inherit from Airflow base classes, integrate with Dag execution, and respond to task lifecycle events.
• Assistant is a novel capability, not a provider integration: The AI Assistant doesn't register operators or hooks. It's a completely new extension point: a conversational interface for operational insights. Applying the provider model would be semantically incorrect and would bloat the assistant with provider-specific conventions it doesn't need.
• Security and governance implications: The assistant integrates with external LLM providers and processes sensitive Airflow metadata. It needs its own security review cycle, separate from provider releases. Providers typically follow a rapid release model suitable for integrations with external services (e.g., adding support for a new AWS resource). The AI Assistant, being a novel security-sensitive integration point, needs deliberate, slower, well-audited releases.
• AI/LLM space is volatile: LLM models, frameworks, and best practices change weekly. The assistant must iterate faster than Airflow's provider lifecycle permits, without waiting for core Airflow releases. A separate distribution cycle with independent versioning allows security patches and model updates to ship independently.
• Community expectations: Releasing the assistant as a provider would signal "this is as stable and mature as any standard Airflow integration." The reality is Phase 1 is a proof-of-concept. A separate distribution cycle with clear versioning lets us signal "early, opt-in, rapidly evolving."

Trade-off: Users cannot install the assistant via pip install apache-airflow-providers-ai . Instead, they use pip install apache-airflow-ai-assistant,  which in turn installs the plugin. 

Consequence: The assistant's lifecycle (versioning, security response, feature planning) is independent of Airflow's core and provider release schedules. This requires clear ownership and a documented SLA for security patches.

Plugin-based architecture vs. core component

Resolution: Delivered as an optional plugin in a separate distribution.

Considered alternatives:

• Core component (integrated into airflow core): Would provide unified distribution but creates permanent maintenance burden in core.
• Optional library bundled with core: Splits the best/worst of both approaches.

Rationale for plugin approach:

• Security boundary: The assistant integrates with external LLM providers and introduces new outbound network egress patterns. Making it explicitly opt-in (plugin) allows operators to prohibit AI assistance entirely, reducing the Airflow security surface for organizations with strict policies.
• Opt-in principle: Airflow users range from small teams to enterprises. Many have no use for AI assistance or cannot use external LLM providers. A plugin avoids imposing this capability and its operational overhead on all deployments.
• Independent evolution: AI/LLM tooling evolves rapidly. Plugin architecture allows the assistant to iterate independently of Airflow's release cycle, respond to security findings quickly, and experiment with new LLM models without waiting for core Airflow releases.
• Clear ownership: Plugin-based delivery with independent versioning makes ownership and maintenance expectations explicit.

Trade-off: Users who want the assistant must explicitly install and manage it; it is not included in standard Airflow distributions.

Consequence: Dependency management (see below).

MCP (Model Context Protocol) as the tool interface (vs. direct internal API calls)

Resolution: Use standardized MCP interface (as defined in AIP-91) to expose tool capabilities.

Considered alternatives:

• Direct API calls: Assistant backend invokes Airflow REST/GraphQL APIs directly without abstraction.
• Custom tool interface: Define a new tool registry specific to the assistant.
• LangChain/LlamaIndex integrations: Leverage existing tool marshalling frameworks.

Rationale for MCP approach:

• Standardization: MCP is a model-agnostic, widely-adopted standard for connecting AI systems to tools. By using MCP, the assistant avoids vendor lock-in and enables community contributions of new tool adapters.
• Decoupling: MCP isolates the assistant's tool calls from Airflow's internal API surface. This means assistant evolution does not require changes to core Airflow APIs, and core API changes do not directly impact the assistant.
• Multi-model compatibility: MCP enables the same tool definitions to work with different LLM providers (Claude, GPT, open-source models, etc.), all via Pydantic AI or other MCP-compatible frameworks.
• Auditability: MCP-based tool calls are structured and versioned, making it easier to define allowlists, enforce RBAC, and audit what data tools actually expose.
• Future extensibility: As higher-level AI agentic patterns emerge (autonomous workflows, tool-use orchestration), MCP provides a stable foundation that can evolve without re-architecting the assistant.

Trade-off: MCP introduces an abstraction layer and an additional component (MCP tool service) that must be deployed and monitored. Performance is determined by the tool service's efficiency.

Consequence: The assistant is partially dependent on AIP-91's completion and stability. If AIP-91 is delayed or significantly redesigned, the assistant's tool integration timeline may shift.

Pydantic AI as the LLM invocation framework (vs. alternatives)

Resolution: Use Pydantic AI to invoke LLM providers with structured request/response schemas.

Considered alternatives:

• Direct SDK calls: Query LLM provider SDKs (OpenAI, Anthropic, etc.) directly, implementing request construction and response parsing in-house.
• LangChain: Larger, more opinionated framework with broader integrations but higher complexity overhead.
• LlamaIndex: Focused on retrieval-augmented generation (RAG) workflows, less suitable for structured tool-based reasoning.

Rationale for Pydantic AI approach:

• Airflow ecosystem alignment: Airflow already uses Pydantic extensively for configuration validation, serialization, and API schemas. Pydantic AI maintains consistency with this established pattern and reduces cognitive overhead for maintainers familiar with Airflow's codebase. Pydantic AI provides a lightweight, focused interface for structured LLM calls without the complexity overhead of larger frameworks like LangChain. This reduces the surface area for bugs and security vulnerabilities.
• Structured outputs: Pydantic AI's tight integration with Pydantic models enables validated, schema-enforced LLM responses. The assistant can define strict response structures (e.g., tool selection, reasoning) and automatically reject malformed outputs.
• Provider agnosticity: While Pydantic AI is maintained by Pydantic, it offers a provider-agnostic abstraction layer. The same code works with OpenAI, Anthropic, or self-hosted models without code changes (only config changes).
• Maturity: Pydantic AI is actively maintained and widely adopted in the Python AI ecosystem. It is more stable than ad-hoc integrations and has been battle-tested by a growing community.

Trade-off: Adds Pydantic AI as a dependency required for the plugin to operate. While Pydantic is already in Airflow, pydantic-ai  is a separate package. 

Consequence: Pydantic AI is installed as part of the plugin, compatibility should be considered between the version of pydantic-ai  in common.ai  package, and that AI assistant.

Where the AI assistant lives (part of airflow-core vs. monorepo vs. separate repository)

Resolution: Separate assistant plugin package, versioned independently from airflow-core , as an independently-versioned package within the apache/airflow  monorepo.

Considered alternatives:

• Core component (integrated into airflow-core ): Unified distribution but higher maintenance burden and governance overhead.
• Separate repository (independently versioned under apache/airflow-ai ) : Strongest separation, adds cross-repo coordination and CI/CD complexity.
• Monorepo component (independently versioned, e.g., under airflow-ai in apache/airflow ) - recommended option

Rationale:

• Preserves opt-in behavior and minimizes risk to core Airflow.
• Allows faster iteration and security response without waiting for core release cycles.
• Keeps ownership and maintenance boundaries explicit.

Trade-offs:

• Requires explicit compatibility management with supported Airflow versions.
• Adds minor operational complexity for users installing the plugin.*

Consequences:

• Users install and upgrade the assistant plugin package explicitly (alongside Airflow), rather than as part of the core distribution.
• Deployment managers must follow a documented compatibility matrix between the plugin and supported Airflow versions.

Database Schema and Migration Strategy

The assistant needs persistence for audit metadata and operational diagnostics when the feature is enabled.

Resolution: Plugin-managed schema and migrations, independent of core Airflow's Alembic chain.

Considered alternatives:

Core Alembic migrations:

• Simple for core-integrated features, but not viable when the assistant is packaged separately.
• Plugin-managed Alembic chain (supported by Airflow): Preserves separation, but depends on Airflow exposing a supported plugin migration API.
• Self-contained schema management: Keeps full separation but adds maintenance overhead and custom tooling.

Rationale:

The assistant is packaged independently, so core Alembic migrations are not a reliable mechanism.
Plugin-managed or self-contained schema control aligns with independent releases and keeps ownership boundaries clear.

Trade-offs:

• Requires explicit upgrade steps for plugin users.
• Adds testing burden for cross-version compatibility.

Consequences:

Deployment managers must run plugin-specific migrations during install/upgrade.
The plugin must publish clear upgrade guidance and compatibility requirements.

Proposed Solution

High-level overview

This AIP introduces an official, opt-in AI Assistance capability for Airflow that enables users to ask natural-language questions about their workflows and receive grounded answers based on real Airflow state.

At a high level, this change introduces the usage of the following components (only when the feature is enabled):

1. Frontend assistant plugin - A UI extension embedded in the Airflow web interface (e.g., as a dedicated tab or panel) that accepts natural-language questions and displays contextual, read-only answers or insights (see illustration in Figure 1). 
2. Plugin backend - A plugin component that exposes secured API endpoints co-deployed with the Airflow instance, receives frontend requests, coordinates with a configurable assistant backend, and mediates access to Airflow signals and tools in an audited and controlled way.
3. MCP integration surface – A standardized interface, as defined and implemented in AIP-91, that allows the assistant backend to call controlled tools that retrieve Airflow information (for example, Dag list, Dag runs, task instances, logs, etc.) in a way that respects RBAC and allowlisting policies. This AIP consumes that interface but does not define or implement it.

The first phase of this capability focuses on read-only insights and explanations of Airflow state. Actions that modify state (create, update, delete) such as triggering runs, modifying tasks, or altering configurations are explicitly out of scope for the initial implementation and may be considered in a future phase once safe action patterns, permission controls, and guardrails have been established.

This design uses Airflow’s plugin infrastructure (custom UI and API extension points) to minimize core changes while providing a secure and extensible foundation for AI-assisted workflow insights.

Definitions

• Assistant UI (Plugin UI): The web UI surface embedded in the Airflow UI that sends user prompts and renders responses.
• Assistant Backend (Plugin Backend): The server-side component (a dedicated FastAPI app registered via Airflow plugin extension points) that authenticates requests, enforces policy, invokes tools, and optionally calls an LLM provider.
• Model / LLM Provider: The external or local model service used to generate response text based on inputs. The model is treated as untrusted.

• Tool: A backend-controlled capability that retrieves specific Airflow state (and only that state) under the requesting user’s identity and permissions.
• MCP Tool Service: A tool host implementing the interface defined by AIP-91.
• Grounded Mode: The assistant retrieves live Airflow state via tools and uses it to inform responses. Responses SHOULD be based on retrieved tool outputs whenever the query pertains to specific Airflow objects or state.
• Non-grounded Mode: Tool invocation is disabled; responses are limited to general guidance and must be labeled as not based on live Airflow state.
• Metadata-level audit logging: Audit records that capture operational context - user identity, timestamp, query type (grounded/non-grounded), tools invoked, tool execution outcome, LLM provider invocation status, and response latency - without storing full prompt text, full response text, or full tool output bodies. Full content logging MAY be enabled via configuration but MUST respect redaction policies.

Behavioral Model

User Interaction Model

When enabled, the assistant appears as an embedded UI surface within the Airflow web interface (see Figure 1 for illustration). 

The assistant operates in a conversational model:

• Users submit natural-language queries.

• Responses are generated in context of live Airflow state.

• Each interaction is scoped to the current authenticated user.

Figure 1 - Illustrations of the assistant plugin UI

Query Processing Semantics

For each user query (see Figure 2):

1. The request is associated with the currently authenticated Airflow user.

2. The system evaluates the user’s RBAC permissions.

3. The assistant may invoke read-only tools to retrieve relevant Airflow state.

4. Retrieved data is filtered according to the user’s permissions.

5. The assistant generates a response grounded in tool outputs.

6. The response is displayed in read-only format.

Figure 2 - Query processing semantics diagram

The assistant never bypasses permission checks or accesses data unavailable to the requesting user.

Tool Invocation & Grounding

 In Phase 1, tool invocation MUST be controlled by the Assistant Backend, not by the model:

• The model MUST be treated as untrusted. All tool execution decisions are made by the Assistant Backend.
  

• The model's output MAY include tool call suggestions (e.g., "retrieve Dag runs for Dag_id=X"), but these suggestions are treated as hints, not directives. The Assistant Backend MUST independently:

  • Validate the suggested tool against a configured allowlist.

  • Verify that the authenticated user has RBAC permission for the requested resource.

  • Enforce redaction rules, rate limits, and maximum query scope.

  • Execute or reject the tool call based on its own policy evaluation.

  • The model MUST NOT directly invoke tools, construct API calls, or determine execution order. The backend is the sole authority for tool execution.

• Tool outputs MUST be filtered and redacted before being included in any model prompt, response, or persisted audit record.
• Grounding requirements:
  • In Grounded Mode, responses SHOULD be based on tool outputs whenever possible.
• If grounding fails (tools unavailable, permission denied, or policy constraints), the assistant MUST state that limitation explicitly and MUST NOT fabricate unavailable data.

Error and Failure Handling

The assistant must gracefully handle:

• LLM provider timeouts

• Rate limits

• Tool invocation failures

• Permission denials

Failure states must:

• Not block the Airflow UI

• Not affect scheduler or task execution

• Display clear user-facing error messages

Audit and Accountability

Each interaction is associated with the authenticated user identity and recorded according to audit policy. Detailed audit requirements, including record structure, redaction, and retention, are specified in [Security and controls > Auditability and Traceability].

Response Characteristics

Responses must:

• Be clearly marked as AI-generated.
• Indicate when external data was retrieved.
• Provide citations or references to Airflow objects when applicable (e.g., Dag ID, Dag Run ID).
• Avoid fabricating unavailable data.

If grounding fails or required tools are unavailable, the assistant must communicate this explicitly rather than hallucinate.

 UI/UX Principles

The assistant UI:

• Follows existing Airflow UI conventions.

• Does not obscure core UI functionality.

• Provides indicators for backend & MCP connectivity.

• Clearly communicates rate limits and errors.

• Clearly distinguishes between facts retrieved from Airflow state and model-generated analysis or suggestions.

Session Management

The assistant operates in a session-based conversational model:

• Each conversation session is scoped to a single authenticated user.
• Conversation history within a session MAY be sent to the LLM to provide conversational context, subject to context window limits and redaction policies.
• Conversation content (prompts and responses) MUST NOT be shared across users.
• The assistant SHOULD support configurable conversation history length (number of prior turns included in LLM context) to balance conversational quality against cost and context window limits.
• Conversation persistence across page reloads is an implementation decision and is not mandated by this AIP. If conversations are persisted, they MUST respect the same redaction and retention policies as audit records.
• Conversation content is distinct from audit metadata. Audit records capture operational metadata (who, when, which tools, outcome); conversation content captures the full prompt/response text. Different retention and redaction policies MAY apply to each.

Technical Architecture

Assistant Plugin

Delivery mechanism

The assistant backend is delivered as an Apache Airflow plugin by subclassing airflow.plugins_manager.AirflowPlugin.

The plugin uses supported Airflow 3.x extension points to:

• Register a dedicated FastAPI application via fastapi_apps.

• Optionally register a FastAPI root middleware for UI integration purposes.

No modifications to Airflow core modules are required, except for adding the Airflow AI assistant as an installation extra

The plugin can be installed or removed independently of core Airflow functionality.

Assistant API Surface

The plugin exposes a dedicated FastAPI application mounted under a stable URL prefix (e.g., /assistant).

The API surface is intentionally minimal and scoped to Phase 1 (read-only assistance):

• GET /assistant/health
  Provides readiness and configuration diagnostics (e.g., LLM configuration status, MCP reachability).

• POST /assistant/chat
  Accepts a user message and returns a structured assistant response.

Requests and responses are JSON-based and validated using explicit schemas to ensure predictable behavior and clear error reporting.

No state-modifying endpoints are exposed in Phase 1.

Configuration Model

The plugin relies exclusively on Airflow-native configuration primitives:

• LLM credentials are resolved from an Airflow Connection.

• Runtime settings (e.g., model selection, MCP endpoint URL) are configurable via Airflow configuration.

This ensures:

• Consistency with existing Airflow secret management patterns.

• No introduction of a parallel configuration system.

All configuration is explicit and required for enablement; the feature remains disabled by default.

LLM Invocation Model

The assistant backend uses Pydantic AI to invoke an LLM provider using structured request and response schemas, using the credentials provided from Airflow Connections. This ensures validated, predictable outputs and avoids reliance on ad-hoc parsing of model responses.

The abstraction layer allows support for multiple LLM providers without changing the plugin’s public API surface.

The backend constructs prompts, enforces redaction and permission boundaries prior to invocation, validates structured outputs, and returns normalized responses to the Airflow UI.

MCP Integration

When enabled, the backend connects to an MCP-compatible tool service as defined in AIP-91.

Key properties:

• Tool access is read-only in Phase 1.

• Tool invocation occurs under explicit backend control.

• Tool calls retrieve Airflow state through RBAC-enforced APIs.

State-backed assistance in Phase 1 depends on a properly configured and reachable MCP endpoint. If MCP is configured but unreachable, the assistant enters the "Enabled but Not Configured" state (see Feature States): the UI entry point MAY be shown with a clear diagnostic indicator, but no tool calls or grounded responses are served. If MCP is not configured at all and non-grounded mode is not enabled, the assistant MUST remain in the Disabled state.

Deployments may optionally enable a non-grounded mode as part of Phase 1. In this mode:

• No live Airflow state is accessed.

• Tool invocation is disabled.

• Responses are limited to general Airflow knowledge or documentation-style assistance.

• Responses must be clearly labeled as model-generated and not based on system data.

• The UI must visually distinguish this mode from state-backed assistance.

Non-grounded mode is not the primary capability of Phase 1. It is offered as an optional fallback for deployments where MCP is not yet configured or for general Airflow knowledge questions that do not require live state.
The same security controls (prompt injection protection, audit logging, RBAC gating) apply regardless of mode.

Grounded and non-grounded modes must not be implicitly interchangeable, and the active mode must be clearly communicated to the user.

Configuration Requirements

• Enablement MUST be controlled via Airflow configuration and MUST default to disabled.
• Network endpoints (LLM provider endpoint and MCP tool service endpoint) MUST be configurable by deployment administrators using Airflow’s existing configuration mechanisms.
• Secrets/credentials for external services MUST be stored and resolved via Airflow Connections.

Security model

This section describes the technical implementation of identity propagation and authorization enforcement within the assistant plugin.

For the broader security risk analysis and mitigation controls, see the "Security and controls" section below.

Identity Propagation & Authorization

The assistant MUST enforce authorization on every request and tool call.

• Requests to the Assistant Backend MUST be authenticated using Airflow’s existing authentication mechanisms.
• The Assistant Backend MUST evaluate a dedicated permission gate for assistant usage (e.g., “can use AI assistant”) in addition to resource-level RBAC.
• Tool calls MUST execute on behalf of the authenticated user and MUST be authorized using the same RBAC rules that govern access in the Airflow UI/API.

If an MCP Tool Service is used:

• The Assistant Backend MUST propagate user identity and authorization context in a verifiable manner (e.g., a signed, short-lived token or a delegated credential) such that the tool service can enforce per-user RBAC.
• The tool service MUST NOT use a single shared privileged identity to fetch data for all users.

Database Schema and Migration Scope

The assistant introduces persistence of audit metadata and operational diagnostics when the feature is enabled:

• Assistant-related tables MUST be namespaced (e.g., ai_assistant_* ).
• Audit records MUST comply with redaction and retention policy and SHOULD avoid storing full prompt/response bodies by default.
• The plugin's documentation MUST describe the upgrade/migration path.

Security and controls

This feature introduces new integration points between Airflow and external systems. As such, it expands the overall security surface of an Airflow deployment. The following sections describe the primary risks and the controls required to mitigate them.

Network Egress Control

Risk

When enabled, the assistant may initiate outbound network requests to a configured external LLM provider. Misconfiguration or insufficient network controls could result in unintended data exposure or violations of organizational network policies.

Controls

• The feature is disabled by default.

• External LLM integration must be explicitly configured.

• Approved LLM provider endpoints and credentials must be defined via Airflow Connections.

• Network egress policies remain under the control of the deployment environment (e.g., firewall, proxy, or VPC controls).

Data Minimization and Redaction

Risk

The assistant may process operational signals such as Dag code, task logs, configuration metadata, and runtime context. These artifacts may contain secrets, access tokens, connection passwords, or personally identifiable information (PII).

Controls

• Secrets, credentials, and connection passwords must never be transmitted to an external LLM provider.
• The assistant must align with and respect Airflow’s existing secret masking and sensitive field handling mechanisms (e.g., log redaction and connection field masking), and must not introduce alternate paths that expose unmasked sensitive data.
• Improvements to redaction and sensitive data handling in Airflow core should directly strengthen the security posture of the assistant.
• Tool outputs must be filtered and redacted before inclusion in prompts, responses, or audit records.
• Redaction must occur prior to:
  • LLM invocation,
  • Audit persistence
  • Rendering in the UI.
• Administrators may configure additional allowlists or redaction policies to further restrict exposed metadata fields.

• The assistant must adhere to a data minimization principle, including only the fields necessary for the requested interaction.

RBAC Enforcement and Permission Isolation

Risk

An assistant operating on behalf of a user could inadvertently expose objects outside that user’s permissions, escalate privileges through tool misuse, or access metadata beyond the intended scope of the authenticated user.

Controls

All data retrieval performed on behalf of a user must be subject to Airflow’s role-based access control:

• All data access must flow through Airflow’s RBAC-enforced API layer.

• MCP tooling must not bypass RBAC protections. Tooling access should be mediated in ways consistent with how Airflow enforces resource-based permissions (e.g., Dag, TaskInstance, Log access) via authenticated API calls.

• The assistant must not operate with elevated or system-level privileges. It must never grant higher access than the authenticated user’s role would ordinarily allow in the Airflow UI or API.

• Privileged state must not be cached or reused across interactions. Stored or shared state across users must not be permitted unless it respects the originating user’s RBAC boundaries.

• Each interaction must be evaluated independently against the authenticated user’s identity. The assistant must treat user identity as the sole authority for permission decisions.

• The assistant must strictly inherit, and never expand, the permissions of the requesting user. It must never provide a user with access to data or operations they could not otherwise access through the Airflow UI or API under their assigned roles.

In addition to resource-level RBAC, access to the assistant UI/API MUST be gated by a dedicated permission. This allows operators to:

• Enable the feature for a subset of trusted roles first.
• Keep the feature enabled system-wide but restricted to specific groups.

Prompt Injection and Tool Misuse Protection

Risk

LLM-integrated systems are susceptible to prompt injection and manipulation via malicious free-text artifacts (e.g., logs, comments, task output). Without safeguards, such content could be leveraged to influence the assistant’s behavior, attempt to override system instructions, or expose unauthorized data.

Controls

• Tool invocation must be explicitly controlled by the plugin backend.
  The model must not autonomously determine which internal tools to call or what data to request; all tool calls must be initiated and authorized by backend logic.

• System prompts and interaction scaffolding must enforce strict behavioral boundaries.
  Prompt templates must explicitly constrain:

  • Read-only semantics

  • Disallowed operations

  • External communication policies

• All retrieved content must be treated as untrusted input.
  Logs, configuration text, and other free-text artifacts must not be interpreted as executable instructions or as directives to change assistant behavior.

• Sensitive system instructions must not be surfaced to the model or rendered in user responses.
  System instruction text used internally to constrain model behavior must not be exposed in output visible to end users.

• The assistant must not infer or execute control logic from untrusted content.
  Model outputs must be validated against expected structure and semantics; the assistant must not treat model suggestions as operational directives unless explicitly authorized.

Auditability and Traceability

Risk

Without structured auditing, misuse, misconfiguration, or unintended data exposure may go undetected and difficult to investigate.

Controls

• Every assistant interaction must be associated with the authenticated user identity.

• Each interaction must be timestamped and persistently recorded in a structured audit log stored within the Airflow metadata database.

• Audit records must capture sufficient metadata to support investigation, including:

  • Requested action,

  • Invoked tools (if any)
  • Execution outcome
  • External LLM invocation status (e.g., success, failure, timeout).

• Audit persistence must respect configured redaction policies.

• Retention policies for assistant audit records must be configurable.

These controls ensure accountability and enable operational review, incident response, and compliance verification.

Operational Isolation

Risk

External LLM provider instability, high latency, or rate limiting could degrade assistant responsiveness or, if improperly integrated, introduce cascading failures into core Airflow components.

Controls

• The assistant backend operates within the Airflow webserver context and must not run within scheduler or executor processes.

• Assistant failures must not impact scheduler execution, task execution, or overall Airflow availability.

• LLM and tool invocations must be subject to configurable timeouts and retry limits to prevent blocking behavior.

• Assistant-related errors must degrade gracefully to clear, user-facing messages limited to the assistant UI surface.

• Assistant logic must not block, delay, or interfere with core scheduling, execution, or metadata database operations.

• The assistant must remain operationally isolated from scheduler and executor components, both logically and at the process level.

Operational reliability & Configurability

This feature adds a new integration surface area. Documentation should clearly describe provider-side limits and behaviours, and - where feasible - Airflow should expose corresponding configuration controls (such as client-side timeouts and retry policies) to help operators manage dependencies on external services and reduce the impact of provider rate limits on Airflow stability.

The initial implementation phase is an integration framework and a minimal assistant UX; it is not a fully autonomous expert system and should not be relied upon for automated remediation without explicit operator verification.

Feature States

The assistant has three operator-visible states:

• Disabled (default):
  • The assistant UI entry point MUST NOT be shown.
  • Assistant backend endpoints SHOULD return 404  (or 403 ) and MUST NOT attempt external calls
• Enabled but Not Configured:
  • The assistant UI entry point MAY be shown but MUST clearly indicate that configuration is required.
  • The assistant backend MUST NOT call any external service.
  • The `/assistant/health` endpoint MUST return diagnostic metadata (e.g., {"llm_configured": false, "mcp_reachable": false, "mode": "grounded"} ) to aid troubleshooting, without leaking secrets or credentials.
• Enabled and Ready:
  • The assistant UI is available to authorized users.
  • The assistant backend may call tools and/or the configured LLM provider depending on the active mode.

Reliability Controls

• The assistant backend MUST enforce timeouts for all outbound calls (LLM and tools).
• The assistant backend SHOULD implement per-user and global rate limiting.
• The assistant backend MUST implement circuit breaking / fast-fail when the provider is degraded, and MUST not block the Airflow UI indefinitely.
• The assistant backend MUST bound request sizes and tool result sizes to limit cost and reduce exfiltration risk.

Cost Observability

LLM API calls incur direct cost (typically per-token). The assistant backend SHOULD expose basic usage metrics (e.g., total tokens consumed, requests per user, requests per time window) via Airflow's existing metrics/logging infrastructure. Administrators MAY use these metrics to set budgets or alerts. Detailed cost management is out of scope for Phase 1 but the metric surface SHOULD be designed to support it.

Packaging and Release Model

Repository location: The assistant is delivered as a standalone plugin package ss an independently-versioned package within the apache/airflow  monorepo.

Versioning: The plugin is versioned independently from core Airflow.

Compatibility matrix: The plugin publishes supported Airflow versions and maintains a compatibility policy.

Release cadence and ownership: The plugin has its own release cadence and explicit ownership/maintenance responsibilities.

Dependency management: The plugin declares its own dependencies (including pydantic-ai ) in its pyproject.toml . Users should install the plugin using apache-airflow-ai-assistant .

CI/CD and Repository Infrastructure

This section describes the CI/CD implications of the recommended packaging model (separate repository).

Secret management

Requires cooordination with ASF Infrastructure for securely storage of AWS credentials for LLM testing.

AI-Specific Testing Infrastructure

System prompt evaluation and red-teaming require LLM access in CI:

• AWS-sponsored instance: Airflow's AWS partner provides a dedicated instance (currently used for doc archiving) with LLM capabilities. This instance will be repurposed to also host prompt evaluation and red-teaming tests (e.g., using promptfoo or similar tools).
• Test scope: System prompt evaluation tests are run on every PR to validate security constraints, response quality, and prompt injection resilience.
• CI integration: Tests run after unit and integration test suites, before merge approval.

Reusable Workflows

Possible leverage existing GitHub Actions workflows from apache/airflow  to minimize duplication:

• Static checks: Linting, type checking, code formatting (e.g., ruff, mypy, black).
• Release workflows: PyPI publishing, tag creation, release notes generation.
• Documentation builds: Sphinx doc generation and publication.

Downsides & Tradeoffs

Security surface expansion

Operational complexity

The assistant introduces additional configuration and runtime considerations, including external LLM provider management, rate limits, timeouts, and monitoring. While isolated from core scheduling and task execution, it adds components that deployment managers must configure and operate when the feature is enabled.

Maintenance burden

This feature increases long-term maintenance overhead across UI, backend, MCP integration, and provider compatibility. Ongoing testing of security boundaries, API stability, and cross-version compatibility will be required. Clear ownership of interface contracts is essential.

Dependency on MCP implementation (AIP-91)

The assistant depends on the MCP tooling surface defined in AIP-91. Changes or delays in that interface may impact implementation timelines or require adaptation. This introduces cross-AIP coordination requirements.

Impact Analysis

Which users are affected?

• Deployment Managers: Configure and enable/disable the feature; manage credentials and policies; deploy and operate the assistant plugin components and the MCP tooling service (as defined in AIP-91).
• Operational Users: Use the assistant within the Airflow UI to retrieve read-only insights about workflows.

Migration & Upgrade impact

By default (feature disabled)

• No behavioral change.
• No database upgrade required.
• No additional services.

When enabled (opt-in)

• Deployment managers must explicitly configure:

  • A feature enable flag (e.g., AIRFLOW__AI_ASSISTANT__ENABLED  or equivalent plugin configuration).

  • LLM provider credentials and endpoint (e.g., API key, URL) stored via an Airflow Connection.

  • The MCP tooling service endpoint and credentials, according to AIP-91, which the plugin backend uses to securely retrieve Airflow state.

• Operational users:

  • A database migration must be applied to create required AI-related tables (e.g., audit logs).

  • The MCP tooling service must be reachable from the plugin backend.

  • Enabling the feature changes the system's security posture and requires documented guardrails.

What is the level of migration effort (manual and automated) needed for the users to adapt to the breaking changes?

The migration strategy depends on the chosen packaging model (see Database Schema and Migration Scope). Under the recommended packaging model, database schema changes are managed by the assistant plugin's own migration mechanism, not by core Airflow's Alembic chain. Users must run the plugin's migration tooling after installation or upgrade. The plugin's documentation MUST provide clear upgrade instructions.

What defines this AIP as "done"?

This AIP is considered complete when the following criteria have been satisfied for the first phase (read-only AI-assisted insights):

Functional completeness

• A production-ready implementation suitable for real-world deployments of Airflow 3.x, under the defined scope (read-only AI assistance).
• The assistant UI is integrated into the Airflow web interface using standard plugin extension points and is accessible only to authorized users.
• The assistant can accept questions via the plugin UI and return grounded answers based on live Airflow state.
• The implementation supports integration with at least one configurable LLM provider and defines an extensible abstraction layer to support additional LLM providers.
• The implementation integrates with the standardized tooling interface defined in AIP-91 (once available) to retrieve Airflow signals in a secure, read-only manner.
• The assistant UI follows established Airflow UI patterns and integrates consistently with existing navigation and permission models.

Security and controls

• Permission and RBAC boundaries are enforced for all assistant access.
• Administrators can configure allowlists and redaction policies to control what data is exposed externally.
• Assistant interactions are persistently recorded in a structured audit log (e.g., a dedicated database table), capturing sufficient context for traceability and accountability, in accordance with configured redaction and retention policies.

Configurability and operational behavior

• Feature gating and default-off behavior are implemented.
• Administrators can configure timeouts, error handling behavior, and integration controls.
• Failure scenarios (such as provider errors or rate limits) have defined behaviors and do not compromise core Airflow availability.

Quality assurance (QA)

• Unit tests validate request/response schemas, redaction, permission gating, and error handling.
• Integration tests validate that the assistant respects RBAC boundaries across representative objects (DAG, DagRun, TaskInstance, logs).
• System prompt evaluation and red-teaming tests are implemented using Airflow's AWS-sponsored instance.
• Frontend tests (unit/component) validate the assistant UI plugin behavior (rendering, loading/error states, and clear labeling for grounded vs non-grounded responses).
• UI integration/end-to-end tests validate that the assistant UI entry point and actions are correctly gated by permissions and that failures do not degrade core UI navigation.
• Provider interactions are tested using mocks or local test doubles; CI MUST NOT require access to proprietary external LLM services.
• Security-focused tests cover prompt injection scenarios (malicious log content) and verify that policy prevents disallowed tool calls and sensitive-field exfiltration.
• Performance characteristics meet agreed-upon expectations and do not degrade core Airflow functionality.
• The assistant UI provides clear feedback for loading, error, and rate-limit states.
• AI-generated responses are clearly identified as such to users.

Optional (non-gating) system tests MAY be documented for deployment administrators who want to validate their configured LLM integration and tool service in their own environment.

Documentation

• User and administrator documentation exists that explains how to enable/disable the feature, control data exposure, and configure credentials securely.
• A basic troubleshooting guide is provided for common error classes and operational problems.

Distribution and Release Readiness

• The packaging, and release model for the assistant feature are defined and approved.

• Versioning and compatibility expectations with supported Airflow 3.x releases are documented.

• Ownership and maintenance responsibilities are clearly defined.

Once all of these criteria are met, the feature in its first phase (read-only AI assistance) can be considered done and ready for adoption with production usage expectations.