Pydantic AI connection

The Pydantic AI connection type configures access to LLM providers via the pydantic-ai framework. A single connection type works with any provider that pydantic-ai supports: OpenAI, Anthropic, Google, Bedrock, Groq, Mistral, Ollama, vLLM, and others.

Default Connection IDs

The PydanticAIHook uses pydanticai_default by default.

Configuring the Connection

Model

The model identifier in provider:model format. This field appears as a dedicated input in the connection form (via conn-fields) and stores its value in extra["model"].

The provider: prefix is required here: this generic connection type has no platform of its own (unlike the vendor connection types below), so a bare name (e.g. gpt-5 without openai:) raises ValueError naming this connection rather than being resolved automatically.

Examples: openai:gpt-5, anthropic:claude-sonnet-5, bedrock:us.anthropic.claude-opus-4-6-v1:0, google:gemini-2.5-flash

See Anthropic’s models overview for the current list of Claude model IDs across the Claude API, Amazon Bedrock, and Google Cloud. See OpenAI’s models reference for the current list of OpenAI model IDs.

The model can also be overridden at the hook/operator level via the model_id parameter.

API Key (Password field)

The API key for your LLM provider. Required for API-key-based providers (OpenAI, Anthropic, Groq, Mistral). Leave empty for providers using environment-based auth (Bedrock via AWS_PROFILE, Vertex via GOOGLE_APPLICATION_CREDENTIALS).

Host (optional)

Base URL for the provider’s API. Only needed for custom endpoints:

  • Ollama: http://localhost:11434/v1

  • vLLM: http://localhost:8000/v1

  • Azure OpenAI with an openai: model: https://<resource>.openai.azure.com/openai/v1. For an azure: model, use the dedicated Pydantic AI (Azure OpenAI) connection connection instead.

  • Any OpenAI-compatible API: the base URL of that service

Extra (JSON, optional)

A JSON object with additional configuration. Programmatic users can set the model directly in extra:

{"model": "openai:gpt-5"}

When using the UI, the “Model” field above writes to this same location automatically.

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.

Examples

OpenAI

{
    "conn_type": "pydanticai",
    "password": "sk-...",
    "extra": "{\"model\": \"openai:gpt-5\"}"
}

Anthropic

{
    "conn_type": "pydanticai",
    "password": "sk-ant-...",
    "extra": "{\"model\": \"anthropic:claude-sonnet-5\"}"
}

Ollama (local)

{
    "conn_type": "pydanticai",
    "host": "http://localhost:11434/v1",
    "extra": "{\"model\": \"openai:llama3\"}"
}

AWS Bedrock

Leave password empty and configure AWS_PROFILE or IAM role in the environment:

{
    "conn_type": "pydanticai",
    "extra": "{\"model\": \"bedrock:us.anthropic.claude-opus-4-6-v1:0\"}"
}

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 Pydantic AI (AWS Bedrock) connection connection type.

Google Vertex AI / Gemini API

Leave password empty and configure GOOGLE_API_KEY (or GEMINI_API_KEY) in the environment:

{
    "conn_type": "pydanticai",
    "extra": "{\"model\": \"google:gemini-2.5-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 Pydantic AI (Google Vertex AI) connection connection type with a google-cloud: model prefix instead.

Model Resolution Order

The hook reads the model from these sources in priority order:

  1. model_id parameter on the hook/operator

  2. model in the connection’s extra JSON (set by the “Model” conn-field in the UI)

  3. When this connection is used as a fallback and neither of the above is set, the bare model_id forwarded from the primary connection (see Provider fallback) – a forwarded name that already pins a platform is not applied here, since it names a model of the primary’s own platform.

  4. With PydanticAIHook.create_agent(spec_file=...), the model declared in the spec file, when neither model_id nor the connection’s model extra is set. A connection that declares fallback_conn_ids but no model raises instead, because a spec-file model cannot be wrapped in a fallback chain (see Using the hook directly: PydanticAIHook).

Whichever name is chosen, a name that already pins a recognized platform (its segment before the first : is itself a pydantic-ai provider) is used verbatim; a bare name is qualified with this connection’s platform, and this generic connection type has none, so a bare name reaching this step always raises.

Was this entry helpful?