Skip to main content
skill CX Codex

pydantic-ai-model-integration — Claude Code skill

pydantic-ai-model-integration guides LLM provider configuration, fallback model chains, streaming, and token limits in PydanticAI.

Apache-2.0 120 installs ★ 89 updated 2026-09-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add existential-birds/beagle --skill pydantic-ai-model-integration -a claude-code
Open on GitHub

What pydantic-ai-model-integration does

This skill teaches coding assistants how to configure LLMs in PydanticAI using the provider:model-name pattern. It covers endpoints for OpenAI, Anthropic, Google GLA and Vertex AI, Groq, Mistral, Cohere, and Bedrock, alongside request timeouts and temperature controls in ModelSettings.

It outlines resilient architectures using FallbackModel, including custom filters for HTTP 429 and server errors. The material also covers response streaming via run_stream, complete with live parsing of structured outputs defined by Pydantic models.

PydanticAI checks environment variables on instantiation, so offline tests will fail unless configured with defer_model_check=True or an agent.override block.

What it helps with

  • configure multiple LLM providers in PydanticAI using standard strings
  • set up automatic model failover using FallbackModel on rate limits
  • stream partial structured JSON output into Pydantic models
  • track and restrict token consumption with UsageLimits

Example prompts for the agent

  • Create a PydanticAI agent with Claude 3.5 Sonnet and an OpenAI fallback
  • Show how to stream a validated Pydantic model using run_stream
  • How do I set token limits and timeouts for PydanticAI runs?

How to install pydantic-ai-model-integration

1Skills CLI (Vercel)

npx skills add existential-birds/beagle --skill pydantic-ai-model-integration -a claude-code

2Manually: put the files in place

~/.claude/skills/pydantic-ai-model-integration/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/pydantic-ai-model-integration/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about pydantic-ai-model-integration

How to install pydantic-ai-model-integration in Claude Code?

Run npx skills add existential-birds/beagle --skill pydantic-ai-model-integration -a claude-code in your terminal.

What does pydantic-ai-model-integration do?

It provides your AI assistant with reference patterns for provider strings, streaming, fallback logic, and token tracking in PydanticAI.

How do I run tests without active API credentials?

Initialize your agent with defer_model_check=True or wrap test runs in the agent.override context manager.

Source text

SKILL.md · Apache-2.0
---
name: pydantic-ai-model-integration
description: Configure LLM providers, use fallback models, handle streaming, and manage model settings in PydanticAI. Use when selecting models, implementing resilience, or optimizing API calls.
---

# PydanticAI Model Integration

## Provider Model Strings

Format: `provider:model-name`

```python
from pydantic_ai import Agent

# OpenAI
Agent('openai:gpt-4o')
Agent('openai:gpt-4o-mini')
Agent('openai:o1-preview')

# Anthropic
Agent('anthropic:claude-sonnet-4-5')
Agent('anthropic:claude-haiku-4-5')

# Google (API Key)
Agent('google-gla:gemini-2.0-flash')
Agent('google-gla:gemini-2.0-pro')

# Google (Vertex AI)
Agent('google-vertex:gemini-2.0-flash')

# Groq
Agent('groq:llama-3.3-70b-versatile')
Agent('groq:mixtral-8x7b-32768')

# Mistral
Agent('mistral:mistral-large-latest')

# Other providers
Agent('cohere:command-r-plus')
Agent('bedrock:anthropic.claude-3-sonnet')
```

## Model Settings

```python
from pydantic_ai import Agent
from pydantic_ai.settings import ModelSettings

agent = Agent(
    'openai:gpt-4o',
    model_settings=ModelSettings(
        temperature=0.7,
        max_tokens=1000,
        top_p=0.9,
        timeout=30.0,  # Request timeout
    )
)

# Override per-run
result = await agent.run(
    'Generate creative text',
    model_settings=ModelSettings(temperature=1.0)
)
```

## Fallback Models

Chain models for resilience:

```python
from pydantic_ai.models.fallback import FallbackModel

# Try models in order until one succeeds
fallback = FallbackModel(
    'openai:gpt-4o',
    'anthropic:claude-sonnet-4-5',
    'google-gla:gemini-2.0-flash'
)

agent = Agent(fallback)
result = await agent.run('Hello')

# Custom fallback conditions
from pydantic_ai.exceptions import ModelAPIError

def should_fallback(error: Exception) -> bool:
    """Only fallback on rate limits or server errors."""
    if isinstance(error, ModelAPIError):
        return error.status_code in (429, 500, 502, 503)
    return False

fallback = FallbackModel(
    'openai:gpt-4o',
    'anthropic:claude-sonnet-4-5',
    fallback_on=should_fallback
)
```

## Streaming Responses

```python
async def stream_response():
    async with agent.run_stream('Tell me a story') as response:
        # Stream text output
        async for chunk in response.stream_output():
            print(chunk, end='', flush=True)

    # Access final result after streaming
    print(f"\nTokens used: {response.usage().total_tokens}")
```

### Streaming with Structured Output

```python
from pydantic import BaseModel

class Story(BaseModel):
    title: str
    content: str
    moral: str

agent = Agent('openai:gpt-4o', output_type=Story)

async with agent.run_stream('Write a fable') as response:
    # For structured output, stream_output yields partial JSON
    async for partial in response.stream_output():
        print(partial)  # Partial Story object as parsed

    # Final validated result
    story = response.output
```

## Dynamic Model Selection

```python
import os

# Environment-based selection
model = os.getenv('PYDANTIC_AI_MODEL', 'openai:gpt-4o')
agent = Agent(model)

# Runtime model override
result = await agent.run(
    'Hello',
    model='anthropic:claude-sonnet-4-5'  # Override default
)

# Context manager override
with agent.override(model='google-gla:gemini-2.0-flash'):
    result = agent.run_sync('Hello')
```

## Deferred Model Checking

Delay model validation for testing:

```python
# Default: Validates model immediately (checks env vars)
agent = Agent('openai:gpt-4o')

# Deferred: Validates only on first run
agent = Agent('openai:gpt-4o', defer_model_check=True)

# Useful for testing with override
with agent.override(model=TestModel()):
    result = agent.run_sync('Test')  # No OpenAI key needed
```

## Usage Tracking

```python
result = await agent.run('Hello')

# Request usage (last request)
usage = result.usage()
print(f"Input tokens: {usage.input_tokens}")
print(f"Output tokens: {usage.output_tokens}")
print(f"Total tokens: {usage.total_tokens}")

# Full run usage (all requests in run)
run_usage = result.run_usage()
print(f"Total requests: {run_usage.requests}")
```

## Usage Limits

```python
from pydantic_ai.usage import UsageLimits

# Limit token usage
result = await agent.run(
    'Generate content',
    usage_limits=UsageLimits(
        total_tokens=1000,
        request_tokens=500,
        response_tokens=500,
    )
)
```

## Provider-Specific Features

### OpenAI

```python
from pydantic_ai.models.openai import OpenAIModel

model = OpenAIModel(
    'gpt-4o',
    api_key='your-key',  # Or use OPENAI_API_KEY env var
    base_url='https://custom-endpoint.com'  # For Azure, proxies
)
```

### Anthropic

```python
from pydantic_ai.models.anthropic import AnthropicModel

model = AnthropicModel(
    'claude-sonnet-4-5',
    api_key='your-key'  # Or ANTHROPIC_API_KEY
)
```

## Common Model Patterns

| Use Case | Recommendation |
|----------|---------------|
| General purpose | `openai:gpt-4o` or `anthropic:claude-sonnet-4-5` |
| Fast/cheap | `openai:gpt-4o-mini` or `anthropic:claude-haiku-4-5` |
| Long context | `anthropic:claude-sonnet-4-5` (200k) or `google-gla:gemini-2.0-flash` |
| Reasoning | `openai:o1-preview` |
| Cost-sensitive prod | `FallbackModel` with fast model first |

## Check gates before ship

Use these only where they prevent obvious misconfiguration; they do not replace integration tests.

- **Fallback chain order:** **Pass:** The first model passed to `FallbackModel(...)` is the intended primary; each subsequent model is a deliberate fallback (not reversed by mistake).
- **Secrets:** **Pass:** Production and shared scripts load API keys from environment variables or a platform secret store; no real keys committed (placeholders only in examples).

© existential-birds · Apache-2.0 · existential-birds/beagle

Similar skills

All skills for AI and ML →

From the same set68

The whole set →
combine-code-review combine-code-review is a Claude Code skill that checks Combine code for subscription, operator, memory, and error-handling issues during Swift code review. CX Codex +1 123installs receive-feedback receive-feedback takes review comments from another model, a human or a CI tool and checks each one against the real code before anything is edited. CX Codex +1 123installs reference-docs reference-docs is a Claude Code skill for writing API and symbol reference pages, with parameter tables, return values, errors, and runnable examples. CX Codex +1 121installs widgetkit-code-review widgetkit-code-review is a Claude Code skill that checks WidgetKit widget code against a checklist for timelines, view composition, configurable intents, and memory, before release or after an iOS 17 migration. CX Codex +1 121installs review-ai-writing review-ai-writing scans documentation, docstrings, commit messages, and pull request descriptions for machine-generated writing patterns. Useful for keeping project artifacts clear and natural. CX Codex +1 119installs wish-ssh-code-review wish-ssh-code-review inspects Go SSH server code using charmbracelet/wish for middleware order, session handling, host keys, and graceful shutdown patterns. CX Codex +1 119installs urlsession-code-review urlsession-code-review reviews the networking layer of iOS and macOS apps: status codes, caching, timeouts, background sessions. Findings come with file:line. CX Codex +1 116installs elixir-security-review elixir-security-review audits Elixir code for security issues like code injection, atom table exhaustion, and exposed secrets before merging. CX Codex +1 110installs

Project sponsors

Companies that keep this analytics open