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, which does not fit the plain api_key + base_url shape that the generic Pydantic AI connection connection assumes. All fields live in extra; the password and host fields are hidden in the connection form.

Note

This connection type was previously named pydanticai-vertex. Connections stored as a URI or as JSON keep working; a type stored verbatim, such as a row created in the UI, must be re-created. See A connection of type pydanticai-azure, pydanticai-bedrock or pydanticai-vertex no longer resolves.

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.5-flash, or the bare gemini-2.5-flash). A bare name is automatically resolved to google-cloud:<name>, instantiating the GoogleCloudProvider that accepts this hook’s project / location / service_account_info fields (see “Credentials” below) – Vertex AI is this connection type’s default platform for a bare name, and that default holds regardless of which credential fields are set on the connection: it is not inferred from whether api_key is present, because api_key here can equally mean Vertex AI Express Mode credentials (see “Credentials” below), so its presence alone cannot tell the two platforms apart. To reach the Generative Language API instead, prefix the model explicitly with google: – that spelling routes to a different provider regardless of which fields this connection sets.
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: Not needed: the google-cloud: model prefix above already makes GoogleCloudProvider build a Vertex AI client.

Note

This field is accepted for backward compatibility but has no effect: it is never forwarded to the provider, and every other field on the connection (project, location, service account, API key) is passed through normally. Setting it logs a warning in the task log noting that the field is ignored and that Vertex AI vs. Generative Language API mode is selected via the model prefix (google-cloud: vs. google:) instead.
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 Pydantic AI connection 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).
Fallback Connections: Other connection IDs to fail over to, in order, while this provider is unavailable. Stored in extra["fallback_conn_ids"]. Entries may name any pydanticai connection type, so one chain can span vendors. See Provider fallback.

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:

{
    "conn_type": "pydanticai_vertex",
    "extra": "{\"model\": \"google-cloud:gemini-2.5-flash\", \"project\": \"my-gcp-project\", \"location\": \"us-central1\"}"
}

Inline service account

{
    "conn_type": "pydanticai_vertex",
    "extra": "{\"model\": \"google-cloud:gemini-2.5-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\"}}"
}