diff --git a/providers/common/ai/docs/connections/pydantic_ai.rst b/providers/common/ai/docs/connections/pydantic_ai.rst index a77fce140a6ba..e71b703da48a4 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 0000000000000..6660010d43a98 --- /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 `__ +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://.openai.azure.com/openai/deployments/``. + +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": "", + "host": "https://.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 0000000000000..744400b26598b --- /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 `__ 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\": \"\"}" + } 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 0000000000000..8bebb7be3139f --- /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 `__ 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\": \"\", \"client_email\": \"sa@my-gcp-project.iam.gserviceaccount.com\"}}" + } diff --git a/providers/common/ai/docs/index.rst b/providers/common/ai/docs/index.rst index 4b0f82608b36d..225db6db554d8 100644 --- a/providers/common/ai/docs/index.rst +++ b/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 - Connection types + Pydantic AI connection + Pydantic AI (Azure OpenAI) connection + Pydantic AI (AWS Bedrock) connection + Pydantic AI (Google Vertex AI) connection MCP connection Hooks Toolsets