Pydantic AI：端到端类型安全的 Python Agent SDK｜安装与 Harness 指南

仓库：https://github.com/pydantic/pydantic-ai 官方文档：https://pydantic.dev/docs/ai/ 许可证：MIT（见仓库 LICENSE） 运行形态：Python SDK（uv add pydantic-ai），无 Web 端口

1. 项目简介

Pydantic AI 是 Pydantic 团队出的 Python AI SDK。它把 Pydantic 的类型校验思想带到 Agent 上：结构化输出、工具参数、依赖注入全部带类型，IDE / mypy / LLM 都能对齐。同一份 Agent 定义可以跑在 CLI、Web 前端、语音通话、Temporal 后台队列、GitHub Actions 等多种界面。

1.1 核心信息一览

1.2 适用场景

• 想要"输出类型化、工具参数校验过"的生产级 Agent；
• 想把同一份 Agent 同时跑 CLI、Web、语音、后台任务；
• 需要 Temporal / DBOS 等持久执行，长任务不丢状态；
• 想用现成 Coder capability 搭一个终端编码 Agent。

1.3 能力边界（官方口径）

• 这是 SDK / 框架，不是开箱即用的托管服务；
• 日志、观测走 OpenTelemetry，可接 Pydantic Logfire 或任意 OTLP 后端；
• 模型调用费用由你选择的 Provider 承担。

2. 功能特性

• 任意模型、一个 Python API：字符串切换 Provider，支持 fallback；
• 端到端类型化：output_type=Sentiment 让每次 run 都返回校验过的对象；
• Capability 组合：把工具、指令、hooks、模型设置打包成可复用单元；
• 多种界面：CLI、Web Chat、Realtime Voice、AG-UI / Vercel AI、ACP、GitHub Agentic Workflows；
• 持久执行：8 种引擎，长任务跨重启恢复；
• Harness 库：从 memory、guardrails、sub-agents 到完整 Coder / Researcher；
• Pydantic Evals：对最终输出与 tool-call 轨迹做评估；
• Image generation / Embeddings：同一包内提供。

3. 官方界面预览

官方 README 顶部为 SVG logo（pydantic-ai-light.svg / pydantic-ai-dark.svg），本文不转载位图。代码示例见第 6 节。

4. 官方跳转链接汇总

• 仓库主页：https://github.com/pydantic/pydantic-ai
• 文档首页：https://pydantic.dev/docs/ai/
• 安装指南：https://pydantic.dev/docs/ai/overview/install/
• Harness：https://pydantic.dev/docs/ai/harness/
• Coder：https://pydantic.dev/docs/ai/harness/coder/
• 模型列表：https://pydantic.dev/docs/ai/models/overview/
• 持久执行：https://pydantic.dev/docs/ai/capabilities/durable_execution/overview/
• Slack：https://logfire.pydantic.dev/docs/join-slack/

5. 前置要求与服务器配置

• Python 3.11+（uv 推荐）；
• 至少一个模型 Provider API Key（OpenAI / Anthropic / Google 等）；
• 可选：Temporal / DBOS / Prefect 等持久执行引擎；
• 无端口、无数据库（除非你自己接）。

6. 方式一：uv 安装（官方推荐）

最简数据提取示例：

uv add pydantic-ai

from typing import Literal
from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext


class Sentiment(BaseModel):
    label: Literal['positive', 'negative', 'neutral']
    score: float = Field(ge=-1, le=1)


agent = Agent('openai:gpt-6.1-sol', output_type=Sentiment)


@agent.tool
def recent_reviews(ctx: RunContext, product: str) -> list[str]:
    '''Fetch recent review snippets for a product.'''
    return ['The new release fixed everything I complained about!']


result = agent.run_sync('How are people feeling about the Extract app?')
print(result.output)

带 Coder 的终端编码 Agent：

uv add pydantic-ai "pydantic-ai-harness[coder]"

from pydantic_ai import Agent
from pydantic_ai.capabilities import WebSearch
from pydantic_ai_harness import Advisor, Coder

agent = Agent(
    'anthropic:claude-fable-5-1',
    capabilities=[
        Coder(),
        WebSearch(),
        Advisor('openai:gpt-6.1-sol'),
    ],
)
agent.to_cli_sync()

不想写代码直接试：

uvx --with "pydantic-ai-harness[coder]" \
  clai -a pydantic_ai_harness.coder:coder_agent -m anthropic:claude-fable-5-1

7. 方式二：持久执行 / 语音 / 镜像

Temporal 持久执行：

uv add "pydantic-ai[temporal]"

Realtime 语音：

uv add "pydantic-ai[openai-realtime]"

图像生成：

uv add pydantic-ai

from pydantic_ai import ImageGenerator
generator = ImageGenerator('openai:gpt-image-2.5-flare')
result = generator.generate_sync('A minimalist logo for a coffee shop called Extract.')

8. 配置项说明

9. 常用运维命令

# 安装
uv add pydantic-ai

# 带 harness
uv add "pydantic-ai-harness[coder]"

# 升级
uv lock --upgrade pydantic-ai

# 用 clai 跑现成 agent
uvx --with "pydantic-ai-harness[coder]" clai -a <agent> -m <model>

# 一键接 Logfire
uvx logfire-cli wizard --task pydantic-ai

10. 常见故障排查

• 模型 401：检查对应 API Key 环境变量；
• 类型校验失败：output_type 是 Pydantic 模型，字段类型要对；
• 想看每次调用：接 Logfire 或 OTLP 后端；
• 长任务中断：加 TemporalDurability 等持久执行 capability；
• 想从 LangChain 迁移：看官方 comparisons / migration skills 文档。

11. 风险与合规说明

• MIT 许可；
• SDK 本身不带模型，费用由 Provider 承担；
• 工具执行会调用你的代码 / shell，生产环境请做权限隔离；
• 本文为社区部署笔记，命令以 pydantic.dev/docs/ai 最新版本为准。