Pydantic AI Documentation Skill

What is Pydantic AI?

Core Concepts

1. Agent Instantiation

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

)

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')

@agent.tool_plain

RunContext

references/FUNCTION_TOOLS.md

3. Dependency Injection (

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. Structured Output

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.

references/MESSAGES.md

references/MODELS.md

FunctionToolset

references/TOOLS_AND_TOOLSETS.md

references/MCP.md

TestModel

override

Agent Behavior Rules

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.

Source

dougtrajano/pydantic-ai-skills

./scripts/update-vendored.sh pydanticai-docs

See also (related skills — Pydantic AI family)

• 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.