Back to Details

pydanticai-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Pydantic AI Documentation Skill

Pydantic AI 文档技能

What is Pydantic AI?

什么是Pydantic AI？

Pydantic AI is a production-grade Python agent framework for building type-safe, dependency-injected Generative AI applications. It supports multiple LLM providers, structured outputs via Pydantic models, and composable multi-agent patterns.
Doc: https://ai.pydantic.dev/index.md
Pydantic AI是一款用于构建类型安全、依赖注入式生成AI应用的生产级Python Agent框架。它支持多LLM提供商、通过Pydantic模型实现的结构化输出，以及可组合的多Agent模式。
文档：https://ai.pydantic.dev/index.md

Core Concepts

核心概念

1. Agent Instantiation

1. Agent实例化

python
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)
For full constructor parameters, run methods, and streaming: load 
references/AGENT.md
.
python
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. Function Tools (
@agent.tool
)

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

python
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')
Use 
@agent.tool_plain
when you don't need 
RunContext
. For tool registration, return types, and retries: load 
references/FUNCTION_TOOLS.md
.
python
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. Dependency Injection (
RunContext
)

3. 依赖注入（
RunContext
）

python
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}'
For 
RunContext
fields, injection into system prompts and output validators: load 
references/DEPENDENCIES.md
.
python
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. Structured Output

4. 结构化输出

python
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')
For union types, plain scalars, 
output_validator
, and partial validation: load 
references/OUTPUT.md
.
python
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
。

Additional Topics

其他主题

For these topics, load the named reference file or follow the doc link — no implementation code is provided here.
TopicReference fileDoc link
Message history / multi-turn conversations
references/MESSAGES.md
https://ai.pydantic.dev/message-history/index.md
Model / provider setup (all providers)
references/MODELS.md
https://ai.pydantic.dev/models/overview/index.md
Toolsets (
FunctionToolset
, composition)
references/TOOLS_AND_TOOLSETS.md
https://ai.pydantic.dev/toolsets/index.md
MCP server integration
references/MCP.md
https://ai.pydantic.dev/mcp/client/index.md
Multi-agent applicationsdoc link onlyhttps://ai.pydantic.dev/multi-agent-applications/index.md
Graphs (pydantic-graph)doc link onlyhttps://ai.pydantic.dev/graph/index.md
Evals (pydantic-evals)doc link onlyhttps://ai.pydantic.dev/evals/index.md
Durable executiondoc link onlyhttps://ai.pydantic.dev/durable_execution/overview/index.md
Retriesdoc link onlyhttps://ai.pydantic.dev/retries/index.md
Testing (
TestModel
, 
override
)		doc link onlyhttps://ai.pydantic.dev/testing/index.md
Logfire integrationdoc link onlyhttps://ai.pydantic.dev/logfire/index.md
Builtin toolsdoc link onlyhttps://ai.pydantic.dev/builtin-tools/index.md
Streamingdoc link onlyhttps://ai.pydantic.dev/agent/index.md
对于这些主题，请加载指定的参考文件或访问文档链接——此处不提供实现代码。
主题参考文件文档链接
消息历史 / 多轮对话
references/MESSAGES.md
https://ai.pydantic.dev/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/toolsets/index.md
MCP服务器集成
references/MCP.md
https://ai.pydantic.dev/mcp/client/index.md
多Agent应用仅文档链接https://ai.pydantic.dev/multi-agent-applications/index.md
图（pydantic-graph）仅文档链接https://ai.pydantic.dev/graph/index.md
评估（pydantic-evals）仅文档链接https://ai.pydantic.dev/evals/index.md
持久执行仅文档链接https://ai.pydantic.dev/durable_execution/overview/index.md
重试仅文档链接https://ai.pydantic.dev/retries/index.md
测试（
TestModel
、
override
）		仅文档链接https://ai.pydantic.dev/testing/index.md
Logfire集成仅文档链接https://ai.pydantic.dev/logfire/index.md
内置工具仅文档链接https://ai.pydantic.dev/builtin-tools/index.md
流式处理仅文档链接https://ai.pydantic.dev/agent/index.md

Agent Behavior Rules

Agent行为规则

  1. Default to this file — answer from core concepts first; load only the specific 
    references/<CONCEPT>.md
    relevant to the user's question when more depth is needed.
  2. Never fabricate API details — always end with "For details, see: <URL>" using a link from the official index above.
  3. No implementation code for non-core topics — return a doc link only for topics listed in the Additional Topics table.
  4. Prefer specificity — route to the most specific page (e.g., 
    models/anthropic/index.md
    ) when the user's question targets a specific provider, not the overview.
  5. Out of scope — do not debug user code passively, do not generate full production agent implementations, do not answer questions unrelated to the Pydantic AI ecosystem.
<!-- vendored:start -->
  1. 默认使用此文件——优先从核心概念中回答；当需要更深入的内容时，仅加载与用户问题相关的特定
    references/<CONCEPT>.md
    。
  2. 切勿编造API细节——始终以“详情请见：<URL>”结尾，并使用上述官方索引中的链接。
  3. 非核心主题不提供实现代码——对于“其他主题”表格中列出的主题，仅返回文档链接。
  4. 优先选择特定内容——当用户的问题针对特定提供商时，引导至最具体的页面（例如
    models/anthropic/index.md
    ），而非概览页面。
  5. 超出范围的内容——不要被动调试用户代码，不要生成完整的生产级Agent实现，不要回答与Pydantic AI生态系统无关的问题。
<!-- vendored:start -->

Source

来源

Refreshed from 
dougtrajano/pydantic-ai-skills
 on 2026-05-16. Refresh with 
./scripts/update-vendored.sh pydanticai-docs
from the conejo-skills repo.
<!-- vendored:end --> <!-- cross-ref:start -->
于2026-05-16从
dougtrajano/pydantic-ai-skills
更新。 从conejo-skills仓库使用
./scripts/update-vendored.sh pydanticai-docs
进行更新。
<!-- vendored:end --> <!-- cross-ref:start -->

See also (related skills — Pydantic AI family)

另请参阅（相关技能——Pydantic AI系列）

If your issue relates to:
  • main Pydantic AI guide with reference files (start here) — check 
    pydantic-ai-agent-builder
    if appropriate.
  • common mistakes and debugging Pydantic AI agents — check 
    pydantic-ai-common-pitfalls
    if appropriate.
  • RunContext, deps_type, dependency injection patterns — check 
    pydantic-ai-dependency-injection
    if appropriate.
  • configuring providers, fallback models, streaming, settings — check 
    pydantic-ai-model-integration
    if appropriate.
  • TestModel, FunctionModel, VCR cassettes, inline snapshots — check 
    pydantic-ai-testing
    if appropriate.
  • registering tools, function calling, ctx handling — check 
    pydantic-ai-tool-system
    if appropriate.
<!-- cross-ref:end -->
如果你的问题涉及：
  • 包含参考文件的Pydantic AI主指南（从这里开始）——如果合适，请查看
    pydantic-ai-agent-builder
    。
  • Pydantic AI Agent的常见错误与调试——如果合适，请查看
    pydantic-ai-common-pitfalls
    。
  • RunContext、deps_type、依赖注入模式——如果合适，请查看
    pydantic-ai-dependency-injection
    。
  • 配置提供商、 fallback模型、流式处理、设置——如果合适，请查看
    pydantic-ai-model-integration
    。
  • TestModel、FunctionModel、VCR cassettes、内联快照——如果合适，请查看
    pydantic-ai-testing
    。
  • 注册工具、函数调用、ctx处理——如果合适，请查看
    pydantic-ai-tool-system
    。
<!-- cross-ref:end -->