pydantic-ai-common-pitfalls

What This Skill Does

The pydantic-ai-common-pitfalls skill acts as a diagnostic and reference engine for developers building AI agents with PydanticAI. It provides expert-level pattern matching to identify frequent architectural mistakes, such as improper tool decorator usage, incorrectly ordered RunContext parameters, and Pydantic dependency injection failures. By using this skill, developers can reduce debugging time for common 'UserError' messages and ensure their agent implementations adhere to the official PydanticAI library specifications.

Installation

To integrate this skill into your environment, run the following command in your terminal: clawhub install openclaw/skills/skills/anderskev/pydantic-ai-common-pitfalls

Use Cases

This skill is best utilized during the iterative development phase of an AI agent. Use it when:

1. You receive a UserError regarding tool signature mismatch or RunContext issues.
2. You are troubleshooting agent crashes that occur during the agent.run_sync or agent.run execution lifecycle due to missing dependencies.
3. You are refactoring existing code to transition from standard functions to decorated tools.
4. You need to verify if your custom tool registration pattern is valid under the current version of PydanticAI.

Example Prompts

1. 'I am getting a UserError saying RunContext annotations can only be used with tools that take context. Can you check my tool implementation?'
2. 'Why is my agent failing when I try to run it with deps? Here is the code snippet for my Agent instantiation.'
3. 'Help me debug this error: First parameter of tools that take context must be annotated with RunContext.'

Tips & Limitations

This skill is designed as an analytical tool. When using it, always provide the specific snippet of code causing the issue, including the Agent definition and the relevant tool function signatures. Note that while this skill covers core PydanticAI pitfalls, it cannot diagnose runtime logic errors or issues external to the PydanticAI framework. Always ensure your environment uses compatible versions of Pydantic and PydanticAI, as breaking changes in the framework may render some diagnostic patterns obsolete. Always favor official documentation if the agent's suggestion conflicts with the latest release notes.