pydanticai-docs

Pydantic AI 文档技能

什么是 Pydantic AI？

Pydantic AI 是一个面向生产环境的 Python Agent 框架，用于构建类型安全、依赖注入式的生成式 AI 应用。它支持多种 LLM 提供商、通过 Pydantic 模型实现结构化输出，以及可组合的多 Agent 模式。

文档：https://ai.pydantic.dev/

---

核心概念

1. Agent 实例化

from pydantic_ai import Agent

agent = Agent(
    'openai:gpt-4o',          # model string: provider:model-name
    system_prompt='Be helpful.',
)
result = agent.run_sync('What is the capital of France?')
print(result.output)

如需了解完整的构造函数参数、运行方法和流式处理，请加载 references/AGENT.md。

2. 函数工具（@agent.tool）

from pydantic_ai import Agent, RunContext

agent = Agent('openai:gpt-4o', deps_type=str)

@agent.tool
def get_user_name(ctx: RunContext[str]) -> str:
    """Return the current user's name."""
    return ctx.deps

result = agent.run_sync('What is my name?', deps='Alice')

如果不需要 RunContext，请使用 @agent.tool_plain。如需了解工具注册、返回类型和重试，请加载 references/FUNCTION_TOOLS.md。

3. 依赖注入（RunContext）

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class MyDeps:
    api_key: str
    user_id: int

agent = Agent('openai:gpt-4o', deps_type=MyDeps)

@agent.tool
async def fetch_data(ctx: RunContext[MyDeps]) -> str:
    return f'User {ctx.deps.user_id}'

如需了解 RunContext 字段、向系统提示词注入内容，以及输出验证器，请加载 references/DEPENDENCIES.md。

4. 结构化输出

from pydantic import BaseModel
from pydantic_ai import Agent

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

agent = Agent('openai:gpt-4o', output_type=CityInfo)
result = agent.run_sync('Where were the 2012 Olympics held?')
print(result.output)  # CityInfo(city='London', country='United Kingdom')

如需了解联合类型、普通标量、output_validator 和部分验证，请加载 references/OUTPUT.md。

---

其他主题

如需了解这些主题，请加载指定的参考文件或访问文档链接 — 此处不提供实现代码。

主题	参考文件	文档链接
消息历史 / 多轮对话	references/MESSAGES.md	https://ai.pydantic.dev/core-concepts/message-history/index.md
模型 / 提供商配置（所有提供商）	references/MODELS.md	https://ai.pydantic.dev/models/overview/index.md
工具集（FunctionToolset、组合）	references/TOOLS_AND_TOOLSETS.md	https://ai.pydantic.dev/tools-toolsets/toolsets/index.md
MCP 服务集成	references/MCP.md	https://ai.pydantic.dev/mcp/client/index.md
多 Agent 应用	仅提供文档链接	https://ai.pydantic.dev/guides/multi-agent-applications/index.md
图（pydantic-graph）	仅提供文档链接	https://ai.pydantic.dev/graph/graph/index.md
评估（pydantic-evals）	仅提供文档链接	https://ai.pydantic.dev/evals/evals/index.md
持久化执行	仅提供文档链接	https://ai.pydantic.dev/durable_execution/overview/index.md
重试	仅提供文档链接	https://ai.pydantic.dev/core-concepts/retries/index.md
测试（TestModel、override）	仅提供文档链接	https://ai.pydantic.dev/guides/testing/index.md
Logfire 集成	仅提供文档链接	https://ai.pydantic.dev/integrations/logfire/index.md
原生工具（以前称为内置工具）	仅提供文档链接	https://ai.pydantic.dev/tools-toolsets/native-tools/index.md
流式处理	仅提供文档链接	https://ai.pydantic.dev/core-concepts/agent/index.md

---

Agent 行为规则

1. 默认使用此文件 — 首先根据核心概念作答；需要更深入的信息时，仅加载与用户问题相关的特定 references/<CONCEPT>.md。
2. 绝不编造 API 细节 — 结尾始终使用官方索引中的链接，并注明“详情请参阅：<URL>”。
3. 非核心主题不提供实现代码 — 对“其他主题”表格中列出的主题，仅返回文档链接。
4. 优先提供具体信息 — 用户的问题针对特定提供商时，应指向最具体的页面（例如 models/anthropic/index.md），而不是概览页面。
5. 超出范围 — 不要被动调试用户代码，不要生成完整的生产级 Agent 实现，也不要回答与 Pydantic AI 生态无关的问题。