PydanticAI 是 Pydantic 团队开发的高层次 Python AI Agent 框架，强调类型安全和结构化输出。通过其 OpenAIModel 类可以接入 OpenRouter：安装 pydantic-ai-slim[openai]，创建 OpenAIModel 实例并指定 base_url="https://openrouter.ai/api/v1" 和 OpenRouter API key，然后传入 Agent 即可使用 agent.run() 发起调用。

PydanticAI 是 Pydantic 团队开发的 Python AI Agent 框架，提供类型安全的模型交互接口，内置结构化输出、依赖注入和 async 支持。

安装

pip install 'pydantic-ai-slim[openai]'

[openai] extra 包含连接 OpenAI 兼容 API（包括 OpenRouter）所需的依赖。

基本用法

通过 OpenAIModel 的 base_url 参数将请求路由到 OpenRouter：

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel

model = OpenAIModel(
    "anthropic/claude-sonnet-4.6",  # 任意 OpenRouter 模型 ID
    base_url="https://openrouter.ai/api/v1",
    api_key="sk-or-...",
)

agent = Agent(model)
result = await agent.run("What is the meaning of life?")
print(result)

使用环境变量

推荐从环境变量读取 API key：

import os
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel

model = OpenAIModel(
    "anthropic/claude-sonnet-4.6",
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
)

agent = Agent(model)

结构化输出

PydanticAI 的核心优势是类型安全的结构化输出，用 result_type 指定返回类型：

from pydantic import BaseModel
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel

class CityInfo(BaseModel):
    city: str
    country: str
    population: int

model = OpenAIModel(
    "anthropic/claude-sonnet-4.6",
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
)

agent = Agent(model, result_type=CityInfo)
result = await agent.run("Tell me about Paris")
print(result.data)  # CityInfo(city='Paris', country='France', population=2161000)

支持的模型

可以使用任意 OpenRouter 模型列表 中的模型，格式为 provider/model-name，替换 OpenAIModel 的第一个参数即可。

更多文档

• PydanticAI 文档
• OpenAIModel API 参考
• OpenRouter 模型列表

常见问题

Q: PydanticAI 的 OpenAIModel 和直接用 openai 库有什么区别？

A: PydanticAI 在 OpenAI SDK 之上提供了更高层次的 Agent 抽象：内置工具调用（@agent.tool）、依赖注入、类型安全的结构化输出（result_type）和 async 支持。如果只需要简单的 chat completion，直接用 openai 库更轻量；如果要构建带工具的 Agent，PydanticAI 更合适。

Q: PydanticAI 的 result_type 如何处理模型不遵守格式的情况？

A: PydanticAI 会在底层使用 function calling 或 JSON mode 强制模型输出结构化格式，并用 Pydantic 验证结果。如果解析失败，会自动重试（默认最多 1 次）并附带 Pydantic 的验证错误信息，让模型修正输出。

Q: 如何传入 OpenRouter 的 Provider 路由参数？

A: 目前 PydanticAI 通过 extra_headers 或直接配置 httpx 客户端来传入额外参数，base_url 指向 OpenRouter 后，可以通过 http_client 参数配置自定义 headers：

import httpx
from pydantic_ai.models.openai import OpenAIModel

model = OpenAIModel(
    "anthropic/claude-sonnet-4.6",
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
)

更复杂的路由参数建议参考 PydanticAI 文档。