Skip to main content
skill CX Codex

pydantic-ai-agent-creation — Claude Code skill

The pydantic-ai-agent-creation skill guides PydanticAI agent setup with typed dependencies, validated outputs, and model configuration. Use it when building agents or chat systems.

Apache-2.0 219 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-agent-creation -a claude-code
Open on GitHub

What pydantic-ai-agent-creation does

The skill shows how to define a PydanticAI Agent with a provider:model-name model string, a Pydantic class for output_type, and a typed dependency object through deps_type. Its examples cover OpenAI, Anthropic, and Google models, plus settings such as temperature, max_tokens, retries, name, and end_strategy.

It compares asynchronous run, synchronous run_sync, and streaming with run_stream. The guidance also separates static instructions, dynamic @agent.instructions functions, and system_prompt, then uses a typed dependency class for access to external services.

The verification sequence checks a basic call, schema validation, and dependency passing before production use. Once deps_type is set, omitting deps= causes the invocation to fail type checking.

What it helps with

  • create a PydanticAI agent with typed dependencies
  • return model data through a validated Pydantic schema
  • configure retries for validation failures
  • choose async, sync, or streaming execution
  • verify an agent before using it in production code

Example prompts for the agent

  • Create a PydanticAI agent with output_type=CityInfo and validate the returned object.
  • Set up an agent with deps_type=MyDeps, pass deps=, and add dynamic instructions.
  • Show async execution with await agent.run(...) and stream the response with run_stream.

How to install pydantic-ai-agent-creation

1Skills CLI (Vercel)

npx skills add existential-birds/beagle --skill pydantic-ai-agent-creation -a claude-code

2Manually: put the files in place

~/.claude/skills/pydantic-ai-agent-creation/SKILL.md

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

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

Questions about pydantic-ai-agent-creation

How do I install pydantic-ai-agent-creation in Claude Code?

Run npx skills add existential-birds/beagle --skill pydantic-ai-agent-creation -a claude-code, then check ~/.claude/skills/pydantic-ai-agent-creation/SKILL.md.

What does pydantic-ai-agent-creation do?

It guides the setup of PydanticAI agents with typed dependencies, schema-based outputs, provider settings, and several execution modes.

How does the skill verify structured output?

Set output_type, request data that matches the schema, and confirm that result.output is an instance of the Pydantic model. Repeated validation errors point to clearer instructions or a higher retries value.

Source text

SKILL.md · Apache-2.0
---
name: pydantic-ai-agent-creation
description: Create PydanticAI agents with type-safe dependencies, structured outputs, and proper configuration. Use when building AI agents, creating chat systems, or integrating LLMs with Pydantic validation.
---

# Creating PydanticAI Agents

## Quick Start

```python
from pydantic_ai import Agent

# Minimal agent (text output)
agent = Agent('openai:gpt-4o')
result = agent.run_sync('Hello!')
print(result.output)  # str
```

## Model Selection

Model strings follow `provider:model-name` format:

```python
# OpenAI
agent = Agent('openai:gpt-4o')
agent = Agent('openai:gpt-4o-mini')

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

# Google
agent = Agent('google-gla:gemini-2.0-flash')
agent = Agent('google-vertex:gemini-2.0-flash')

# Others: groq:, mistral:, cohere:, bedrock:, etc.
```

## Structured Outputs

Use Pydantic models for validated, typed responses:

```python
from pydantic import BaseModel
from pydantic_ai import Agent

class CityInfo(BaseModel):
    city: str
    country: str
    population: int

agent = Agent('openai:gpt-4o', output_type=CityInfo)
result = agent.run_sync('Tell me about Paris')
print(result.output.city)  # "Paris"
print(result.output.population)  # int, validated
```

## Agent Configuration

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

agent = Agent(
    'openai:gpt-4o',
    output_type=MyOutput,           # Structured output type
    deps_type=MyDeps,               # Dependency injection type
    instructions='You are helpful.',  # Static instructions
    retries=2,                      # Retry attempts for validation
    name='my-agent',                # For logging/tracing
    model_settings=ModelSettings(   # Provider settings
        temperature=0.7,
        max_tokens=1000
    ),
    end_strategy='early',           # How to handle tool calls with results
)
```

## Running Agents

Three execution methods:

```python
# Async (preferred)
result = await agent.run('prompt', deps=my_deps)

# Sync (convenience)
result = agent.run_sync('prompt', deps=my_deps)

# Streaming
async with agent.run_stream('prompt') as response:
    async for chunk in response.stream_output():
        print(chunk, end='')
```

## Instructions vs System Prompts

```python
# Instructions: Concatenated, for agent behavior
agent = Agent(
    'openai:gpt-4o',
    instructions='You are a helpful assistant. Be concise.'
)

# Dynamic instructions via decorator
@agent.instructions
def add_context(ctx: RunContext[MyDeps]) -> str:
    return f"User ID: {ctx.deps.user_id}"

# System prompts: Static, for model context
agent = Agent(
    'openai:gpt-4o',
    system_prompt=['You are an expert.', 'Always cite sources.']
)
```

## Common Patterns

### Parameterized Agent (Type-Safe)

```python
from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class Deps:
    api_key: str
    user_id: int

agent: Agent[Deps, str] = Agent(
    'openai:gpt-4o',
    deps_type=Deps,
)

# deps is now required and type-checked
result = agent.run_sync('Hello', deps=Deps(api_key='...', user_id=123))
```

### No Dependencies (Satisfy Type Checker)

```python
# Option 1: Explicit type annotation
agent: Agent[None, str] = Agent('openai:gpt-4o')

# Option 2: Pass deps=None
result = agent.run_sync('Hello', deps=None)
```

## Verification gates

Run these in order before depending on an agent in production code:

1. **Smoke run** — Execute `agent.run_sync('Reply with OK.')` (or `await agent.run(...)` in async code). **Pass:** the call completes without raising and `result.output` is present.
2. **Structured output** — If you set `output_type`, prompt for a response that should satisfy the schema. **Pass:** `result.output` is an instance of your Pydantic model; repeated validation failures mean tightening instructions or `retries`, not adding features yet.
3. **Dependencies** — If you set `deps_type`, call `run` / `run_sync` with `deps=` of that type. **Pass:** the invocation type-checks and completes (or fails only for model/API reasons, not a missing or wrong `deps` value).

## Decision Framework

| Scenario | Configuration |
|----------|--------------|
| Simple text responses | `Agent(model)` |
| Structured data extraction | `Agent(model, output_type=MyModel)` |
| Need external services | Add `deps_type=MyDeps` |
| Validation retries needed | Increase `retries=3` |
| Debugging/monitoring | Set `instrument=True` |

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

Similar skills

All skills for AI and ML →

From the same set68

The whole set →
pytest-code-review pytest-code-review reviews pytest test files for async patterns, fixture scopes, parametrization, and mock targets. Catches unawaited coroutines and broken patch paths before CI runs. CX Codex +1 239installs sqlalchemy-code-review sqlalchemy-code-review reviews SQLAlchemy code for session, relationship, query, and migration issues. Use it when checking SQLAlchemy 2.0 or Alembic changes. CX Codex +1 228installs pydantic-ai-common-pitfalls pydantic-ai-common-pitfalls walks through the mistakes that break PydanticAI agents and gives a fixed order for debugging: tool decorators, deps, output schemas, streaming. CX Codex +1 221installs agent-architecture-analysis agent-architecture-analysis audits an LLM agent codebase against the 12-Factor Agents rubric, then scores each factor and points at the files behind the score. CX Codex +1 220installs ai-elements A skill for Claude Code, Codex, Cursor, Copilot, Gemini CLI and OpenCode: helps build chat interfaces, job queues, tool execution displays and approval workflows. Triggers on ai-elements, Queue, Tool, Confirmation, Message, PromptInput. CX Codex +1 211installs go-code-review go-code-review — a Go review skill that reads go.mod first, then checks errors, goroutines, interfaces and cleanup, ranking each finding by severity. CX Codex +1 206installs shadcn-code-review shadcn-code-review audits React components built with shadcn/ui, Radix primitives, and Tailwind CSS. Catches CVA mistakes, broken asChild slots, and missing accessibility states. CX Codex +1 206installs react-router-code-review react-router-code-review is a Claude Code skill that checks React Router v6.4+ code for loaders, actions, error boundaries, and navigation. It reviews routing changes. CX Codex +1 202installs

Project sponsors

Companies that keep this analytics open