Skip to main content
skill CX Codex

pydantic-ai-common-pitfalls — Claude Code skill

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.

Apache-2.0 221 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-common-pitfalls -a claude-code
Open on GitHub

What pydantic-ai-common-pitfalls does

The skill lists what usually goes wrong in PydanticAI agents and how to trace it when the stack trace says little. Most of it covers tool decorators: RunContext has no place in tool_plain, and under @agent.tool it must be the first parameter. It also confirms the plain-function route through Agent(tools=[...]), where the context is read from the signature.

Dependencies get their own section. Set deps_type and every run or run_sync call needs the deps argument. Then come output schemas with retries and clearer instructions, nested models that produce awkward schemas, and the sync/async split: run_sync in a plain function, await run inside async code, asyncio.sleep instead of time.sleep in tools, and reading response.output only after the stream context closes.

When a failure makes no sense, the skill gives an ordered check: pull the messages with capture_run_messages() or result.all_messages(), separate the model reply from your schema, confirm deps on each call path. No provider key in the environment means the first run dies on authentication, so for tests it points at defer_model_check=True plus agent.override(model=TestModel()).

What it helps with

  • Trace a UserError about RunContext back to the wrong decorator
  • Loosen a failing output_type schema with retries and sharper instructions
  • Find a blocking call inside an async tool
  • Read result.all_messages() and see where the agent went off
  • Confirm deps reach every run call

Example prompts for the agent

  • My agent throws a UserError about RunContext — check agent.py and tell me which decorator to change.
  • Review tools.py for PydanticAI mistakes: context, deps, return types.
  • The streamed answer stops mid-sentence — walk the debugging checklist and fix it.

How to install pydantic-ai-common-pitfalls

1Skills CLI (Vercel)

npx skills add existential-birds/beagle --skill pydantic-ai-common-pitfalls -a claude-code

2Manually: put the files in place

~/.claude/skills/pydantic-ai-common-pitfalls/SKILL.md

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

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

Questions about pydantic-ai-common-pitfalls

How do I install pydantic-ai-common-pitfalls in Claude Code?

Run npx skills add existential-birds/beagle --skill pydantic-ai-common-pitfalls -a claude-code. The skill lands at ~/.claude/skills/pydantic-ai-common-pitfalls/SKILL.md.

What does pydantic-ai-common-pitfalls cover?

Tool decorator errors, dependency types, output validation, async mistakes and streaming, plus an ordered debugging routine.

Is passing plain functions to Agent(tools=[...]) a bug?

No. PydanticAI reads the signature, and a first parameter typed RunContext[T] marks the function as context-aware. The skill tells reviewers not to flag it.

Source text

SKILL.md · Apache-2.0
---
name: pydantic-ai-common-pitfalls
description: Avoid common mistakes and debug issues in PydanticAI agents. Use when encountering errors, unexpected behavior, or when reviewing agent implementations.
---

# PydanticAI Common Pitfalls and Debugging

## Tool Decorator Errors

### Wrong: RunContext in tool_plain

```python
# ERROR: RunContext not allowed in tool_plain
@agent.tool_plain
async def bad_tool(ctx: RunContext[MyDeps]) -> str:
    return "oops"
# UserError: RunContext annotations can only be used with tools that take context
```

**Fix**: Use `@agent.tool` if you need context:
```python
@agent.tool
async def good_tool(ctx: RunContext[MyDeps]) -> str:
    return "works"
```

### Wrong: Missing RunContext in tool

```python
# ERROR: First param must be RunContext
@agent.tool
def bad_tool(user_id: int) -> str:
    return "oops"
# UserError: First parameter of tools that take context must be annotated with RunContext[...]
```

**Fix**: Add RunContext as first parameter:
```python
@agent.tool
def good_tool(ctx: RunContext[MyDeps], user_id: int) -> str:
    return "works"
```

### Wrong: RunContext not first

```python
# ERROR: RunContext must be first parameter
@agent.tool
def bad_tool(user_id: int, ctx: RunContext[MyDeps]) -> str:
    return "oops"
```

**Fix**: RunContext must always be the first parameter.

## Valid Patterns (Not Errors)

### Raw Function Tool Registration

The following pattern IS valid and supported by pydantic-ai:

```python
from pydantic_ai import Agent, RunContext

async def search_db(ctx: RunContext[MyDeps], query: str) -> list[dict]:
    """Search the database."""
    return await ctx.deps.db.search(query)

async def get_user(ctx: RunContext[MyDeps], user_id: int) -> dict:
    """Get user by ID."""
    return await ctx.deps.db.get_user(user_id)

# Valid: Pass raw functions to Agent(tools=[...])
agent = Agent(
    'openai:gpt-4o',
    deps_type=MyDeps,
    tools=[search_db, get_user]  # RunContext detected from signature
)
```

**Why this works:** PydanticAI inspects function signatures. If the first parameter is `RunContext[T]`, it's treated as a context-aware tool. No decorator required.

**Reference:** https://ai.pydantic.dev/agents/#registering-tools-via-the-tools-argument

**Do NOT flag** code that passes functions with `RunContext` signatures to `Agent(tools=[...])`. This is equivalent to using `@agent.tool` and is explicitly documented.

## Dependency Type Mismatches

### Wrong: Missing deps at runtime

```python
agent = Agent('openai:gpt-4o', deps_type=MyDeps)

# ERROR: deps required but not provided
result = agent.run_sync('Hello')  # Missing deps!
```

**Fix**: Always provide deps when deps_type is set:
```python
result = agent.run_sync('Hello', deps=MyDeps(...))
```

### Wrong: Wrong deps type

```python
@dataclass
class AppDeps:
    db: Database

@dataclass
class WrongDeps:
    api: ApiClient

agent = Agent('openai:gpt-4o', deps_type=AppDeps)

# Type error: WrongDeps != AppDeps
result = agent.run_sync('Hello', deps=WrongDeps(...))
```

## Output Type Issues

### Pydantic validation fails

```python
class Response(BaseModel):
    count: int
    items: list[str]

agent = Agent('openai:gpt-4o', output_type=Response)
result = agent.run_sync('List items')
# May fail if LLM returns wrong structure
```

**Fix**: Increase retries or improve prompt:
```python
agent = Agent(
    'openai:gpt-4o',
    output_type=Response,
    retries=3,  # More attempts
    instructions='Return JSON with count (int) and items (list of strings).'
)
```

### Complex nested types

```python
# May cause schema issues with some models
class Complex(BaseModel):
    nested: dict[str, list[tuple[int, str]]]
```

**Fix**: Simplify or use intermediate models:
```python
class Item(BaseModel):
    id: int
    name: str

class Simple(BaseModel):
    items: list[Item]
```

## Async vs Sync Mistakes

### Wrong: Calling async in sync context

```python
# ERROR: Can't await in sync function
def handler():
    result = await agent.run('Hello')  # SyntaxError!
```

**Fix**: Use run_sync or make handler async:
```python
def handler():
    result = agent.run_sync('Hello')

# Or
async def handler():
    result = await agent.run('Hello')
```

### Wrong: Blocking in async tools

```python
@agent.tool
async def slow_tool(ctx: RunContext[Deps]) -> str:
    time.sleep(5)  # WRONG: Blocks event loop!
    return "done"
```

**Fix**: Use async I/O:
```python
@agent.tool
async def slow_tool(ctx: RunContext[Deps]) -> str:
    await asyncio.sleep(5)  # Correct
    return "done"
```

## Model Configuration Errors

### Missing API key

```python
# ERROR: OPENAI_API_KEY not set
agent = Agent('openai:gpt-4o')
result = agent.run_sync('Hello')
# ModelAPIError: Authentication failed
```

**Fix**: Set environment variable or use defer_model_check:
```python
# For testing
agent = Agent('openai:gpt-4o', defer_model_check=True)
with agent.override(model=TestModel()):
    result = agent.run_sync('Hello')
```

### Invalid model string

```python
# ERROR: Unknown provider
agent = Agent('unknown:model')
# ValueError: Unknown model provider
```

**Fix**: Use valid provider:model format.

## Streaming Issues

### Wrong: Using result before stream completes

```python
async with agent.run_stream('Hello') as response:
    # DON'T access .output before streaming completes
    print(response.output)  # May be incomplete!

# Correct: access after context manager
print(response.output)  # Complete result
```

### Wrong: Not iterating stream

```python
async with agent.run_stream('Hello') as response:
    pass  # Never consumed!

# Stream was never read - output may be incomplete
```

**Fix**: Always consume the stream:
```python
async with agent.run_stream('Hello') as response:
    async for chunk in response.stream_output():
        print(chunk, end='')
```

## Tool Return Issues

### Wrong: Returning non-serializable

```python
@agent.tool_plain
def bad_return() -> object:
    return CustomObject()  # Can't serialize!
```

**Fix**: Return serializable types (str, dict, Pydantic model):
```python
@agent.tool_plain
def good_return() -> dict:
    return {"key": "value"}
```

## Debugging Tips

### Gates (ambiguous failures)

When the agent misbehaves but the stack trace or error string is unclear, follow **in order**; do not skip ahead.

1. **Capture evidence** — Re-run with `capture_run_messages()` or, after `run`/`run_sync`, inspect `result.all_messages()` (or print message types in order). **Pass:** You can name the message part type and one line of content that explains the failure (e.g. `RetryPromptPart`, tool return, model text).
2. **Separate model from schema** — If validation or `RetryPromptPart` appears, compare the last model message to your `output_type` fields and types. **Pass:** You identified a concrete mismatch (missing field, wrong type, refusal) before only raising `retries` or changing the model.
3. **Confirm deps on every path** — If tools or deps fail, verify each call site (`run`, `run_sync`, `run_stream`) supplies `deps=...` when `deps_type` is set. **Pass:** A minimal repro with explicit `deps` matches or rules out a deps wiring bug.

### Enable tracing

```python
import logfire
logfire.configure()
logfire.instrument_pydantic_ai()

# Or per-agent
agent = Agent('openai:gpt-4o', instrument=True)
```

### Capture messages

```python
from pydantic_ai import capture_run_messages

with capture_run_messages() as messages:
    result = agent.run_sync('Hello')

for msg in messages:
    print(type(msg).__name__, msg)
```

### Check model responses

```python
result = agent.run_sync('Hello')
print(result.all_messages())  # Full message history
print(result.response)  # Last model response
print(result.usage())  # Token usage
```

## Common Error Messages

| Error | Cause | Fix |
|-------|-------|-----|
| `First parameter... RunContext` | @agent.tool missing ctx | Add `ctx: RunContext[...]` |
| `RunContext... only... context` | @agent.tool_plain has ctx | Remove ctx or use @agent.tool |
| `Unknown model provider` | Invalid model string | Use valid `provider:model` |
| `ModelAPIError` | API auth/quota | Check API key, limits |
| `RetryPromptPart` in messages | Validation failed | Check output_type, increase retries |

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

Similar skills

All skills for Agent setup: memory, context, orchestration →
building-pydantic-ai-agents pydantic building-pydantic-ai-agents guides coding assistants in writing production Pydantic AI applications with tools and structured output. Useful for building typed agent workflows. CX Codex +1 6,600installs migrating-langchain-to-pydantic-ai pydantic migrating-langchain-to-pydantic-ai — a skill for Claude Code, Codex, Cursor, GitHub Copilot, and Gemini CLI that moves Python projects from LangChain, LangGraph, and Deep Agents to Pydantic AI. CX Codex +1 476installs agentic-development alinaqi agentic-development — a skill for building autonomous AI agents with Pydantic AI in Python or the Claude Agent SDK in Node.js. Useful when an agent has to run multi-step tasks with tools. CX Codex +1 416installs migrating-ai-sdk-to-common-ai astronomer migrating-ai-sdk-to-common-ai moves Airflow projects off airflow-ai-sdk onto the official apache-airflow-providers-common-ai 0.4.0+ provider. Useful when LLM decorators and model config have to move to connections. CX Codex +1 394installs exploring-llm-traces PostHog exploring-llm-traces is a Claude Code skill that investigates LLM agent traces through PostHog MCP tools. It activates for trace or session links and questions about errors, tool calls, context, tokens, or cost. CX Codex +1 440installs check-crewai-api crewAIInc check-crewai-api — a skill that checks crewai code against 1.15.x instead of the 0.x syntax assistants still remember. Useful when an import or a parameter quietly does nothing. CX Codex +1 1,300installs

From the same set68

The whole set →
swift-code-review swift-code-review is a Claude Code skill that checks Swift code for concurrency, error-handling, and memory issues. It activates for .swift reviews involving async/await, actors, or Sendable. CX Codex +1 253installs review-verification-protocol review-verification-protocol — a skill that enforces verification before any code review finding enters the report: read the source freshly, search for context, distinguish bugs from style. Cuts false positives. CX Codex +1 252installs 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 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 pydantic-ai-agent-creation 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. CX Codex +1 219installs 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

Project sponsors

Companies that keep this analytics open