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
npx skills add existential-birds/beagle --skill pydantic-ai-agent-creation -a claude-codeWhat 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=CityInfoand validate the returned object. - Set up an agent with
deps_type=MyDeps, passdeps=, and add dynamic instructions. - Show async execution with
await agent.run(...)and stream the response withrun_stream.
How to install pydantic-ai-agent-creation
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill pydantic-ai-agent-creation -a claude-code2Manually: put the files in place
~/.claude/skills/pydantic-ai-agent-creation/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/pydantic-ai-agent-creation/
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill pydantic-ai-agent-creation -a codex2Manually: put the files in place
.agents/skills/pydantic-ai-agent-creation/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill pydantic-ai-agent-creation -a cursor2Manually: put the files in place
.cursor/skills/pydantic-ai-agent-creation/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install existential-birds/beagle plugins/beagle-ai/skills/pydantic-ai-agent-creation2Manually: put the files in place
.github/skills/pydantic-ai-agent-creation/SKILL.md1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill pydantic-ai-agent-creation -a gemini-cli2Platform CLI
gemini skills install https://github.com/existential-birds/beagle --path plugins/beagle-ai/skills/pydantic-ai-agent-creationManually: put the files in place
.devin/skills/pydantic-ai-agent-creation/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill pydantic-ai-agent-creation -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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