This is an automated email from the ASF dual-hosted git repository.
Lee-W pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new d6af65e2680 Document the dedicated pydantic-ai vendor connection types
(#71774)
d6af65e2680 is described below
commit d6af65e26802390bb2cb45c80c398a209b5518eb
Author: Wei Lee <[email protected]>
AuthorDate: Wed Aug 19 16:59:14 2026 +0800
Document the dedicated pydantic-ai vendor connection types (#71774)
---
.../common/ai/docs/connections/pydantic_ai.rst | 19 ++-
.../ai/docs/connections/pydantic_ai_azure.rst | 76 ++++++++++++
.../ai/docs/connections/pydantic_ai_bedrock.rst | 118 +++++++++++++++++++
.../ai/docs/connections/pydantic_ai_vertex.rst | 128 +++++++++++++++++++++
providers/common/ai/docs/index.rst | 5 +-
5 files changed, 343 insertions(+), 3 deletions(-)
diff --git a/providers/common/ai/docs/connections/pydantic_ai.rst
b/providers/common/ai/docs/connections/pydantic_ai.rst
index a77fce140a6..e71b703da48 100644
--- a/providers/common/ai/docs/connections/pydantic_ai.rst
+++ b/providers/common/ai/docs/connections/pydantic_ai.rst
@@ -118,9 +118,15 @@ Leave password empty and configure ``AWS_PROFILE`` or IAM
role in the environmen
"extra": "{\"model\": \"bedrock:us.anthropic.claude-opus-4-6-v1:0\"}"
}
-**Google Vertex AI**
+This still works — the ``bedrock:`` model prefix and the environment-variable
+credential chain are unchanged. For AWS-specific fields with dedicated UI
+inputs (region, IAM keys, profile, bearer token, timeouts) instead of raw
+``extra`` JSON, use the :doc:`pydantic_ai_bedrock` connection type.
-Leave password empty and configure ``GOOGLE_APPLICATION_CREDENTIALS`` in the
environment:
+**Google Vertex AI / Gemini API**
+
+Leave password empty and configure ``GOOGLE_API_KEY`` (or ``GEMINI_API_KEY``)
+in the environment:
.. code-block:: json
@@ -129,6 +135,15 @@ Leave password empty and configure
``GOOGLE_APPLICATION_CREDENTIALS`` in the env
"extra": "{\"model\": \"google:gemini-2.0-flash\"}"
}
+This connects to the Gemini API (Google AI Studio), not Vertex AI —
pydantic-ai's
+plain ``google:`` provider only reads an API key
+(``GOOGLE_API_KEY``/``GEMINI_API_KEY``); it does not fall back to
+``GOOGLE_APPLICATION_CREDENTIALS`` or any other Application Default
+Credentials source. For project/location-scoped Vertex AI access — service
+account or Application Default Credentials — use the
+:doc:`pydantic_ai_vertex` connection type with a ``google-cloud:`` model
+prefix instead.
+
Model Resolution Order
----------------------
diff --git a/providers/common/ai/docs/connections/pydantic_ai_azure.rst
b/providers/common/ai/docs/connections/pydantic_ai_azure.rst
new file mode 100644
index 00000000000..6660010d43a
--- /dev/null
+++ b/providers/common/ai/docs/connections/pydantic_ai_azure.rst
@@ -0,0 +1,76 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ .. http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+.. _howto/connection:pydanticai-azure:
+
+Pydantic AI (Azure OpenAI) Connection
+======================================
+
+The ``pydanticai-azure`` connection type configures access to
+`Azure OpenAI
<https://azure.microsoft.com/en-us/products/ai-services/openai-service>`__
+via the pydantic-ai framework. It backs ``PydanticAIAzureHook``, the dedicated
+subclass of ``PydanticAIHook`` for Azure's non-standard auth (an endpoint URL
+plus an API version, rather than the plain ``api_key`` + optional ``base_url``
+that the generic :doc:`pydantic_ai` connection assumes).
+
+Default Connection IDs
+----------------------
+
+The ``PydanticAIAzureHook`` uses ``pydanticai_azure_default`` by default.
+
+Configuring the Connection
+--------------------------
+
+Model
+ Azure model identifier (e.g. ``azure:gpt-4o``). This field appears as a
+ dedicated input in the connection form (via ``conn-fields``) and stores its
+ value in ``extra["model"]``.
+
+ The ``azure:`` prefix is required — it is what makes pydantic-ai
instantiate
+ the Azure OpenAI provider instead of the plain OpenAI one.
+
+API Key (Password field)
+ The Azure OpenAI API key.
+
+Azure Endpoint (Host field)
+ The Azure OpenAI resource endpoint, e.g.
+ ``https://<resource>.openai.azure.com/openai/deployments/<deployment>``.
+
+API Version (Extra field)
+ Azure OpenAI API version (e.g. ``2024-07-01-preview``). Falls back to the
+ ``OPENAI_API_VERSION`` environment variable when omitted.
+
+Examples
+--------
+
+.. code-block:: json
+
+ {
+ "conn_type": "pydanticai-azure",
+ "password": "<azure-api-key>",
+ "host": "https://<resource>.openai.azure.com",
+ "extra": "{\"model\": \"azure:gpt-4o\", \"api_version\":
\"2024-07-01-preview\"}"
+ }
+
+Relationship to the hook
+-------------------------
+
+``PydanticAIAzureHook`` maps the connection's ``password`` to the provider's
+``api_key``, ``host`` to ``azure_endpoint``, and ``extra["api_version"]`` to
+``api_version``, then constructs pydantic-ai's Azure provider with those
values.
+If none of them are set, the hook falls back to pydantic-ai's own
environment-variable
+resolution (``AZURE_OPENAI_API_KEY``, ``AZURE_OPENAI_ENDPOINT``,
``OPENAI_API_VERSION``).
diff --git a/providers/common/ai/docs/connections/pydantic_ai_bedrock.rst
b/providers/common/ai/docs/connections/pydantic_ai_bedrock.rst
new file mode 100644
index 00000000000..744400b2659
--- /dev/null
+++ b/providers/common/ai/docs/connections/pydantic_ai_bedrock.rst
@@ -0,0 +1,118 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ .. http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+.. _howto/connection:pydanticai-bedrock:
+
+Pydantic AI (AWS Bedrock) Connection
+=======================================
+
+The ``pydanticai-bedrock`` connection type configures access to
+`AWS Bedrock <https://aws.amazon.com/bedrock/>`__ via the pydantic-ai
framework.
+It backs ``PydanticAIBedrockHook``, the dedicated subclass of
``PydanticAIHook``
+for Bedrock's AWS-style credentials — IAM keys, a bearer token, or the default
+credential chain — none of which fit the plain ``api_key`` + ``base_url`` shape
+that the generic :doc:`pydantic_ai` connection assumes. All fields live in
+``extra``; the ``password`` and ``host`` fields are hidden in the connection
form.
+
+Default Connection IDs
+----------------------
+
+The ``PydanticAIBedrockHook`` uses ``pydanticai_bedrock_default`` by default.
+
+Configuring the Connection
+--------------------------
+
+All fields below are ``extra`` (JSON) fields.
+
+Model
+ Bedrock model identifier (e.g. ``bedrock:us.anthropic.claude-opus-4-5``).
+
+AWS Region
+ AWS region (e.g. ``us-east-1``). Falls back to the ``AWS_DEFAULT_REGION``
+ environment variable.
+
+AWS Access Key ID
+ IAM access key. Leave empty to use instance role / environment credential
chain.
+
+AWS Secret Access Key
+ IAM secret key.
+
+AWS Session Token
+ Temporary session token (optional).
+
+AWS Profile Name
+ Named AWS credentials profile (optional).
+
+Bearer Token
+ AWS bearer token (alt. to IAM key/secret). Falls back to the
+ ``AWS_BEARER_TOKEN_BEDROCK`` environment variable.
+
+Custom Endpoint URL
+ Override the Bedrock runtime endpoint URL (optional).
+
+Read Timeout (s)
+ boto3 read timeout in seconds (float, optional).
+
+Connect Timeout (s)
+ boto3 connect timeout in seconds (float, optional).
+
+Credentials
+-----------
+
+The hook passes every field you set on to ``BedrockProvider`` together; when
+more than one credential source is set at once, the bearer token
+(``api_key``) takes precedence over IAM keys:
+
+- A bearer token (``api_key``, mapped to ``AWS_BEARER_TOKEN_BEDROCK``) — used
+ first if set.
+- IAM keys (``aws_access_key_id`` + ``aws_secret_access_key``, optionally
+ ``aws_session_token``) — used only when no bearer token is set.
+- The environment-variable / instance-role credential chain
+ (``AWS_PROFILE``, IAM role, …) when none of the fields above are set.
+
+Examples
+--------
+
+**IAM instance role / environment credential chain (recommended)**
+
+Leave the AWS credential fields empty and let boto3 resolve credentials from
+the instance role or environment:
+
+.. code-block:: json
+
+ {
+ "conn_type": "pydanticai-bedrock",
+ "extra": "{\"model\": \"bedrock:us.anthropic.claude-opus-4-5\",
\"region_name\": \"us-east-1\"}"
+ }
+
+**Explicit IAM keys**
+
+.. code-block:: json
+
+ {
+ "conn_type": "pydanticai-bedrock",
+ "extra": "{\"model\": \"bedrock:us.anthropic.claude-opus-4-5\",
\"region_name\": \"us-east-1\", \"aws_access_key_id\": \"AKIA...\",
\"aws_secret_access_key\": \"...\"}"
+ }
+
+**Bearer token**
+
+.. code-block:: json
+
+ {
+ "conn_type": "pydanticai-bedrock",
+ "extra": "{\"model\": \"bedrock:us.anthropic.claude-opus-4-5\",
\"api_key\": \"<bearer-token>\"}"
+ }
diff --git a/providers/common/ai/docs/connections/pydantic_ai_vertex.rst
b/providers/common/ai/docs/connections/pydantic_ai_vertex.rst
new file mode 100644
index 00000000000..8bebb7be313
--- /dev/null
+++ b/providers/common/ai/docs/connections/pydantic_ai_vertex.rst
@@ -0,0 +1,128 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ .. http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+.. _howto/connection:pydanticai-vertex:
+
+Pydantic AI (Google Vertex AI) Connection
+============================================
+
+The ``pydanticai-vertex`` connection type configures access to
+`Google Vertex AI <https://cloud.google.com/vertex-ai>`__ via the pydantic-ai
+framework. It backs ``PydanticAIVertexHook``, the dedicated subclass of
+``PydanticAIHook`` for Google Cloud's project/location/service-account
+credential shape — none of which fit the plain ``api_key`` + ``base_url``
+shape that the generic :doc:`pydantic_ai` connection assumes. All fields live
+in ``extra``; the ``password`` and ``host`` fields are hidden in the connection
+form.
+
+Default Connection IDs
+----------------------
+
+The ``PydanticAIVertexHook`` uses ``pydanticai_vertex_default`` by default.
+
+Configuring the Connection
+--------------------------
+
+All fields below are ``extra`` (JSON) fields.
+
+Model
+ Google model identifier (e.g. ``google-cloud:gemini-2.0-flash``). The
+ ``google-cloud:`` prefix is required — it is what makes pydantic-ai
+ instantiate the ``GoogleCloudProvider``, which is what accepts this
+ hook's ``project`` / ``location`` / ``service_account_info`` fields (see
+ "Credentials" below).
+
+GCP Project
+ Google Cloud project ID. Falls back to the ``GOOGLE_CLOUD_PROJECT``
+ environment variable.
+
+Location / Region
+ Vertex AI region (e.g. ``us-central1``). Falls back to the
+ ``GOOGLE_CLOUD_LOCATION`` environment variable.
+
+Force Vertex AI Mode
+ Legacy flag from pydantic-ai 1.x, where a single ``GoogleProvider`` took a
+ ``vertexai`` argument. Not needed here: the ``google-cloud:`` model prefix
+ above already makes ``GoogleCloudProvider`` hard-code ``vertexai=True``
+ unconditionally when it builds its client.
+
+ .. important::
+ Leave this field unset. Setting it currently breaks the connection:
+ neither ``GoogleProvider`` nor ``GoogleCloudProvider`` accept a
+ ``vertexai`` constructor argument, so the hook silently discards
+ every other field on this connection (project, location, service
+ account, API key) and falls back to resolving credentials from
+ environment variables only. If auth unexpectedly falls back to env
+ vars, check the task log for a "rejected kwargs" warning.
+
+API Key
+ Google API key for Vertex AI Express Mode. Falls back to the
+ ``GOOGLE_API_KEY`` environment variable. Cannot be combined with
+ ``project`` / ``location`` / ``service_account_info`` (those select the
+ credentials/ADC path instead, which takes precedence and nulls the API
+ key). For the Generative Language API
+ (non-Vertex, API-key-only), use the ``google:`` prefix on the generic
+ :doc:`pydantic_ai` connection instead.
+
+Service Account Info
+ Service account key as an inline JSON object (with ``type``,
+ ``project_id``, ``private_key``, etc.) — not a file path.
+
+Custom Endpoint URL
+ Override the Google API base URL (optional).
+
+Credentials
+-----------
+
+The hook passes every field you set on to ``GoogleCloudProvider`` together;
+when more than one credential source is set at once, ``credentials`` /
+``project`` / ``location`` take precedence over ``api_key`` (which is then
+ignored):
+
+- ``service_account_info`` — loaded into Google Cloud credentials and passed
+ as ``credentials`` to the provider.
+- Application Default Credentials (``GOOGLE_APPLICATION_CREDENTIALS``,
+ ``gcloud auth application-default login``, Workload Identity, …) — used
+ automatically once ``project`` and/or ``location`` are set without
+ ``service_account_info``.
+- ``api_key`` — for Vertex AI Express Mode, only used when none of the above
+ are set.
+
+Examples
+--------
+
+**Application Default Credentials (recommended)**
+
+Leave the credential fields empty and configure
+``GOOGLE_APPLICATION_CREDENTIALS`` (or another ADC source) in the worker
+environment:
+
+.. code-block:: json
+
+ {
+ "conn_type": "pydanticai-vertex",
+ "extra": "{\"model\": \"google-cloud:gemini-2.0-flash\", \"project\":
\"my-gcp-project\", \"location\": \"us-central1\"}"
+ }
+
+**Inline service account**
+
+.. code-block:: json
+
+ {
+ "conn_type": "pydanticai-vertex",
+ "extra": "{\"model\": \"google-cloud:gemini-2.0-flash\", \"project\":
\"my-gcp-project\", \"location\": \"us-central1\", \"service_account_info\":
{\"type\": \"service_account\", \"project_id\": \"my-gcp-project\",
\"private_key\": \"<contents of the service account JSON key's private_key
field>\", \"client_email\": \"[email protected]\"}}"
+ }
diff --git a/providers/common/ai/docs/index.rst
b/providers/common/ai/docs/index.rst
index c34c3a70932..81c067d584e 100644
--- a/providers/common/ai/docs/index.rst
+++ b/providers/common/ai/docs/index.rst
@@ -147,7 +147,10 @@ See the Optional dependencies table below for the exact
package each extra insta
:caption: Guides
Quick start <quickstart>
- Connection types <connections/pydantic_ai>
+ Pydantic AI connection <connections/pydantic_ai>
+ Pydantic AI (Azure OpenAI) connection <connections/pydantic_ai_azure>
+ Pydantic AI (AWS Bedrock) connection <connections/pydantic_ai_bedrock>
+ Pydantic AI (Google Vertex AI) connection <connections/pydantic_ai_vertex>
MCP connection <connections/mcp>
LangChain connection <connections/langchain>
LlamaIndex connection <connections/llamaindex>
