Document the dedicated pydantic-ai vendor connection types

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
 ----------------------
 

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``).

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>\"}"
+    }

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\": \"sa@my-gcp-project.iam.gserviceaccount.com\"}}"
+    }

providers/common/ai/docs/index.rst

@@ -127,7 +127,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>
     Hooks <hooks/index>
     Toolsets <toolsets>