20260617:目前有914 页

concepts/pydantic-ai.md

@@ -0,0 +1,56 @@
+---
+title: "Pydantic AI"
+created: 2026-06-10
+updated: 2026-06-10
+type: concept
+tags: [pydantic, agent, type-safety, structured-output]
+sources: [raw/articles/pydantic-three-piece-suite-2026.md]
+---
+
+# Pydantic AI
+
+> 将 [[pydantic|Pydantic]] 的类型系统直接嵌入 Agent 运行时的框架。类型不只是校验输出——类型定义了 Agent 能做什么、怎么做、产出什么。
+
+## 核心定位
+
+Pydantic AI 不是 LangChain 的竞品——LangChain 用链式调用组织工作流，Pydantic AI 用**类型系统约束 Agent 的工具选择和输出格式**。
+
+也不是 Instructor 的竞品——Instructor 解决单次 LLM 结构化输出，Pydantic AI 把这件事内置到多步 Agent 框架里。
+
+## 关键能力
+
+- **`@agent.tool`**：从函数签名和返回类型自动推断 tool schema——无需手写 JSON Schema
+- **`result.data`**：类型安全，IDE 补全可用，不需要手动 `model_validate`
+- **多步 Agent**：支持多次推理 + 多次 tool 调用
+- **`instrument=True`**：自动接 [[logfire|Logfire]] trace，全链路可观测
+- **事前约束**：类型的角色从"报错器"变为"编译器"——在运行时之前就约束了行为空间
+
+## vs Instructor
+
+| 能力 | Instructor | Pydantic AI |
+|------|-----------|-------------|
+| LLM → Pydantic 对象 | ✅ | ✅ |
+| Tool 调用自动 schema | ❌ | ✅ |
+| 多步 Agent | ❌ | ✅ |
+| 全链路 trace | ❌ | ✅ |
+
+**规则**：单次 LLM 结构化输出 → Instructor。多步推理 + 多 tool 调用的 Agent → Pydantic AI。
+
+## 示例
+
+```python
+agent = Agent('openai:gpt-4o', result_type=OutfitSuggestion, instrument=True)
+
+@agent.tool
+async def get_weather(city: str) -> WeatherInfo: ...
+
+result = await agent.run("深圳今天穿什么")
+# result.data 类型安全，IDE 补全可用
+```
+
+## 参考
+
+- [[pydantic|Pydantic 生态]]
+- [[type-safety-in-agents|Agent 类型安全]]
+- [[structured-output|结构化输出]]
+- [[logfire|Logfire]]