pydantic-ai-common-pitfalls

Tool decorators require RunContext as the first parameter to access agent context. Omitting it or placing it elsewhere causes decorator failures. Ensure RunContext is always the initial parameter in tool_plain and other tool functions.

Dependency type mismatches occur when deps_type declaration doesn't align with provided dependencies. Validate that your deps_type annotation matches the actual dependency objects passed to the agent at runtime.

Output serialization fails when tool returns non-serializable types or complex nested structures. Ensure all tool outputs are JSON-serializable and use proper Pydantic models for structured responses.

Async/sync mismatches occur when blocking I/O runs in async tools or async calls execute in sync contexts. Verify tool functions use async/await consistently and avoid blocking operations in async tools.

Streaming works with PydanticAI but common issues include improper output handling and timing errors. Ensure streaming responses are properly configured and output types support incremental delivery.

Diagnose by checking RunContext placement in decorators, validating dependency types, ensuring output serializability, verifying async/sync alignment, and reviewing model configuration. Apply fixes systematically across these common pitfall areas.