pydanticai-docs

# Pydantic AI Documentation Skill

## What is 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>

---

## Core Concepts

### 1. Agent Instantiation

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

### 2. Function Tools (`@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`.

### 3. Dependency Injection (`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`.

### 4. Structured Output

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

---

## Additional Topics

> For these topics, load the named reference file or follow the doc link — no implementation code is provided here.

| Topic | Reference file | Doc 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 applications | doc link only | <https://ai.pydantic.dev/multi-agent-applications/index.md> |
| Graphs (pydantic-graph) | doc link only | <https://ai.pydantic.dev/graph/index.md> |
| Evals (pydantic-evals) | doc link only | <https://ai.pydantic.dev/evals/index.md> |
| Durable execution | doc link only | <https://ai.pydantic.dev/durable_execution/overview/index.md> |
| Retries | doc link only | <https://ai.pydantic.dev/retries/index.md> |
| Testing (`TestModel`, `override`) | doc link only | <https://ai.pydantic.dev/testing/index.md> |
| Logfire integration | doc link only | <https://ai.pydantic.dev/logfire/index.md> |
| Builtin tools | doc link only | <https://ai.pydantic.dev/builtin-tools/index.md> |
| Streaming | doc link only | <https://ai.pydantic.dev/agent/index.md> |

---

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