{"enrichment":{"faq":[{"a":"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.","q":"What are pydantic ai common mistakes to avoid?"},{"a":"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.","q":"How do I fix pydantic ai tool decorator issues?"},{"a":"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\u2014type errors surface early if caught during registration rather than runtime execution.","q":"How can I debug dependency type mismatches in PydanticAI?"},{"a":"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\u2014review model prompts and output schema definitions.","q":"What causes pydantic ai output validation to fail?"},{"a":"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.","q":"How do I troubleshoot pydantic-ai async and sync patterns?"},{"a":"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.","q":"How can message capture help debug pydantic-ai agents?"}],"shadow_tags":["error-resolution","agent-debugging","type-safety","async-patterns","schema-validation","dependency-wiring","tool-integration","streaming-gotchas","best-practices","troubleshooting-guide"],"summary_rewrite":"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."},"files":[{"bytes":8252,"path":"plugins/beagle-ai/skills/pydantic-ai-common-pitfalls/SKILL.md","sha256":"1ffc5704c14540ed5901cd1aca5fb6dd5199bdcd238e49f37b482bf729167820","url":"https://skillfed.io/files/existential-birds/beagle/pydantic-ai-common-pitfalls/10b75d0a/SKILL.md"}],"id":"existential-birds/beagle/pydantic-ai-common-pitfalls","links":{"html":"https://skillfed.io/existential-birds/beagle/pydantic-ai-common-pitfalls","md":"https://skillfed.io/existential-birds/beagle/pydantic-ai-common-pitfalls.md","repo":"https://github.com/existential-birds/beagle"},"meta":{"agents_supported":[],"first_seen":"2026-07-28","forks":10,"language":"TypeScript","last_updated":"2026-07-21","license":"Apache-2.0","name":"pydantic-ai-common-pitfalls","publisher":"existential-birds","stars":74},"relations":{"similar":[{"id":"existential-birds/beagle/pydantic-ai-testing"},{"id":"DougTrajano/pydantic-ai-skills/pydanticai-docs"},{"id":"existential-birds/beagle/pydantic-ai-dependency-injection"},{"id":"existential-birds/beagle/pydantic-ai-tool-system"},{"id":"existential-birds/beagle/pydantic-ai-agent-creation"},{"id":"cline/skills/building-pydantic-ai-agents"},{"id":"pydantic/skills/building-pydantic-ai-agents"},{"id":"itechmeat/llm-code/pydantic-ai"},{"id":"existential-birds/beagle/pydantic-ai-model-integration"},{"id":"alinaqi/maggy/agentic-development"}]},"slug":{"owner":"existential-birds","repo":"beagle","skill":"pydantic-ai-common-pitfalls"},"version":"10b75d0a"}