What is the best way to handle Pydantic validation failures?

Increase the 'retries' parameter in your Agent configuration and refine your instructions to explicitly describe the required JSON structure.

Why am I getting a UserError for RunContext in my tool?

RunContext is only allowed as the first parameter in tools decorated with @agent.tool. If you are using @agent.tool_plain, context is not supported and should be removed.

Can I register tools without using decorators?

Yes, PydanticAI supports raw function registration. You can pass functions directly to the Agent(tools=[...]) argument, and it will automatically detect RunContext from the signature.

How do I prevent 'ModelAPIError' during agent runs?

Ensure your environment variables (like OPENAI_API_KEY) are set, or use defer_model_check=True if you plan to override the model during testing.

Is it safe to use time.sleep() inside an async tool?

No, using blocking calls like time.sleep() will freeze the event loop. Always use await asyncio.sleep() or other non-blocking I/O within async tools.

PydanticAI Debugging & Best Practices

Name: PydanticAI Debugging & Best Practices
Author: existential-birds

byexistential-birds

•

データサイエンスとML

Identifies and fixes common implementation errors and architectural pitfalls when building PydanticAI agents.

This skill provides specialized guidance for developers working with the PydanticAI framework to build robust AI agents. It streamlines the debugging process by identifying frequent mistakes such as incorrect RunContext usage in tool decorators, dependency injection mismatches, and problematic async/sync patterns. By applying these best practices and verification workflows, developers can ensure their agents handle validation retries correctly, manage streaming responses efficiently, and maintain proper serialization for production-grade LLM applications.

主な機能

01Troubleshoots response streaming and message history capture issues

02Validates RunContext positioning and annotations for context-aware tools

03Identifies blocking sync code within asynchronous tool definitions

04Detects dependency type mismatches and missing runtime dependencies

05Optimizes Pydantic output validation and LLM retry strategies

0614 GitHub stars

ユースケース

01Debugging UserError exceptions related to tool signatures and decorators

02Ensuring proper instrumentation and tracing with Logfire integration

03Conducting code reviews for complex PydanticAI agent architectures

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add existential-birds/beagle pydantic-ai-common-pitfalls

For use in Claude.ai and ChatGPT

Download Skill