pydantic-ai-common-pitfalls
Troubleshoot PydanticAI agents with guidance on tool decorator patterns, dependency wiring, async/sync contexts, and output validation. Covers common mistakes like missing RunContext parameters, type mismatches, and streaming consumption, plus debugging techniques using message capture and tracing.
pydantic-ai-common-pitfalls helps you resolve errors and unexpected behavior in PydanticAI agent implementations.
AI-generated summary based on this skill's SKILL.md
Install
existential-birds/beagle/pydantic-ai-common-pitfalls · repository language: TypeScript
git clone https://github.com/existential-birds/beagle
cp -r beagle/plugins/beagle-ai/skills/pydantic-ai-common-pitfalls ~/.claude/skills/pydantic-ai-common-pitfallsFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
What are pydantic ai common mistakes to avoid?
pydantic-ai-common-pitfalls identifies several frequent errors: forgetting RunContext parameters in tool methods, mismatching dependency types between agent initialization and tool signatures, and improper async/sync mixing. Tools must declare all dependencies explicitly, and output validation failures often stem from model configuration mismatches. Always verify tool decorators include correct parameter names and that streaming results are fully consumed before agent completion.
How do I fix pydantic ai tool decorator issues?
pydantic-ai-common-pitfalls guides tool decorator troubleshooting: ensure tools are registered before agent initialization, declare RunContext as the first parameter if needed, and match dependency types exactly. Tool return values must be serializable; if validation fails, check that your model's output schema aligns with tool signatures. Use type hints consistently and verify decorator syntax matches your async/sync context.
How can I debug dependency type mismatches in PydanticAI?
pydantic-ai-common-pitfalls addresses deps type mismatch errors by recommending strict type checking: verify dependencies passed to agent initialization match tool parameter annotations exactly. Mismatches occur when a tool expects a specific class but receives a parent or incompatible type. Enable detailed error logging and inspect agent construction—type errors surface early if caught during registration rather than runtime execution.
What causes pydantic ai output validation to fail?
pydantic-ai-common-pitfalls explains validation failures arise from schema misalignment between model output and tool return types. Ensure your model configuration produces data matching declared output types, and that tool serialization handles all fields. Check for missing required fields, incorrect type conversions, and model instruction clarity. Validation errors often indicate the agent's response doesn't conform to expected structure—review model prompts and output schema definitions.
How do I troubleshoot pydantic-ai async and sync patterns?
pydantic-ai-common-pitfalls covers async/sync problems: never mix async tools with sync agents or vice versa. All tools in an agent must share the same concurrency model. Streaming consumption must complete before agent finalization; incomplete reads cause hangs. Use `await` consistently in async contexts and verify RunContext usage matches your execution model. Test with simple synchronous agents first, then migrate to async when patterns are clear.
How can message capture help debug pydantic-ai agents?
pydantic-ai-common-pitfalls recommends capturing agent messages for tracing: enable message logging to inspect tool calls, model responses, and validation steps. Captured messages reveal where agents diverge from expected behavior, showing exact inputs to tools and outputs from models. Use tracing to verify dependency injection worked, tools executed in correct order, and streaming completed. Message inspection accelerates root-cause analysis for unexpected agent behavior.
SKILL.md
rendered from the published skill — quoted content, verbatim
PydanticAI Common Pitfalls and Debugging
Tool Decorator Errors
Wrong: RunContext in tool_plain
# 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:
@agent.tool
async def good_tool(ctx: RunContext[MyDeps]) -> str:
return "works"
Wrong: Missing RunContext in tool
# 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:
@agent.tool
def good_tool(ctx: RunContext[MyDeps], user_id: int) -> str:
return "works"
Wrong: RunContext not first
```python
ERROR: RunContext must be first
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 1 file
plugins/beagle-ai/skills/pydantic-ai-common-pitfalls/SKILL.md