pydantic-ai-common-pitfallslisted
Install: claude install-skill existential-birds/beagle
# 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