用途：把 Pydantic AI 智能体的运行追踪导出到 Maple，使每次对话成为一个 Maple Agent Session，每次 agent.run() 成为一个 turn（一条 trace），包含对话记录、带 token 的 chat span、带参数/结果的 execute_tool span、失败的 tool 标记，以及子智能体独立泳道。机制为 Pydantic AI 原生 OTel 插桩（scope 为 pydantic-ai），无需额外插桩包；Maple 以 gen_ai.conversation.id 作为会话键。
前置要求：Pydantic AI 需 2.x（资料称测试于 2.51.0），1.x 无 conversation_id=，需升级；ToolFailed 需 >= 2.16。先检测项目中是否已有 TracerProvider、logfire.configure 等。
区域与密钥：美国端点 https://ingest.maple.dev，欧盟端点 https://ingest.eu.maple.dev；请求头 Authorization=Bearer <key>。密钥与区域绑定，401 ingest_unauthorized 可能表示密钥属于另一区域。未提供密钥时会使用字面量 MAPLE_TEST，需用户自行在 Settings → Ingestion 替换。不要把私钥放进浏览器代码。
接入方式一（纯 OpenTelemetry）：安装 pydantic-ai-slim[openai]>=2.51、opentelemetry-sdk>=1.45、opentelemetry-exporter-otlp-proto-http>=1.45，创建 TracerProvider 并挂 BatchSpanProcessor(OTLPSpanExporter())，再调用 Agent.instrument_all(InstrumentationSettings(include_content=True, include_binary_content=False))，须在首次 agent.run() 前导入。
接入方式二（Logfire）：项目已用 Logfire 时保留其配置，设置环境变量后调用 logfire.configure(...) 与 logfire.instrument_pydantic_ai()，不要再装上述 OTel 包（logfire 5.1.x 固定 opentelemetry-sdk<1.45）。
关键步骤：每次 run 都要显式传入稳定的 conversation_id（来自应用的会话/线程 id），同一会话内保持不变，不可用进程级常量或每请求 uuid4；委派给子智能体时需传 conversation_id=ctx.conversation_id 与 usage=ctx.usage；流式场景需保持 async with 打开直到消费完毕。
验证与限制：导出后检查每个对话恰好一个 session、framework 显示为 Pydantic AI、chat span 含输入输出 token、失败工具被标记、子智能体独立泳道且同属调用方会话。脚本、CLI、无服务器任务需显式 flush/shutdown。工具失败处理：ToolFailed 标记 span ERROR 但运行继续；ModelRetry 也标记 ERROR 且计入重试；未捕获异常会中止运行；返回 {"error": ...} 会显示为成功调用。禁用内容采集会丢失对话文本与异常消息。其他插桩器可能造成重复 trace。部分耗时指标 Maple 尚不读取，无法定价的模型显示为 unpriced。其他细节暂未提供。