用途：帮助开发者避免和排查 PydanticAI 智能体实现中的常见错误，适用于遇到报错、行为异常或审查智能体代码时参考。
主要能力与要点：
- 工具装饰器：@agent.tool_plain 不允许 RunContext 参数；@agent.tool 要求第一个参数为 RunContext[...]，否则报 UserError。将带 RunContext 签名的原始函数直接传入 Agent(tools=[...]) 是合法用法，无需装饰器。
- 依赖类型：设置 deps_type 后，run/run_sync/run_stream 必须传 deps=...，且类型需匹配，否则报错。
- 输出类型：output_type 校验失败时，可提高 retries 或改进 instructions；复杂嵌套类型可能引发 schema 问题，建议简化或使用中间模型。
- 异步与同步：同步函数中不能 await，应使用 run_sync 或将函数改为 async；异步工具中避免 time.sleep 阻塞事件循环，改用 asyncio.sleep。
- 模型配置：缺少 API key 会报 ModelAPIError；测试时可用 defer_model_check=True 配合 agent.override(model=TestModel())；模型字符串须为 provider:model 格式。
- 流式输出：不要在流完成前访问 response.output；必须消费流（如 async for chunk in response.stream_output()）。
- 工具返回值：需可序列化（str、dict、Pydantic 模型等）。
调试方法：按顺序排查——用 capture_run_messages() 或 result.all_messages() 捕获证据；区分模型问题与 schema 问题；确认每个调用路径都传了 deps。可启用 logfire.configure() 与 logfire.instrument_pydantic_ai()，或对单个 agent 设置 instrument=True。
限制：资料未提供安装命令、版本要求、收费信息及具体平台支持范围。