---

name: pydantic-ai description: "Routes agents working with Pydantic AI, pydantic-graph, pydantic-evals, clai, examples, and repository maintenance across focused workflow sub-skills." disable-model-invocation: true metadata: disco-role: operating license: MIT

Pydantic AI Repo Skill

Use this repo skill when a task mentions Pydantic AI, imports pydantic_ai, edits the Pydantic AI monorepo, uses pydantic-graph, pydantic-evals, clai, or asks about agents, tools, models, providers, MCP, evals, graph workflows, CLI apps, tests, docs, cassettes, or maintainer workflows for this ecosystem.

Start Here

• Read references/repo-provenance.md before deciding whether this skill is current for a checkout or whether refresh-repo-skill is needed.
• Read references/installation-and-extras.md for package names, Python version support, extras, and minimal import checks.
• Read references/capability-map.md when choosing the best sub-skill or checking coverage boundaries.
• Read references/troubleshooting.md for cross-cutting install/import/provider/CLI/configuration problems.
• Run scripts/check_environment.py for a safe no-network diagnostic of installed Pydantic AI packages, optional extras, and CLI help.

Route by Task

User task	Read
Build, configure, run, stream, test, or compose Agent instances; use deps, instructions, message history, usage limits, AgentSpec, or TestModel	sub-skills/agent-core/SKILL.md
Define function tools, validate schemas, use RunContext, ModelRetry, approvals, deferred tools, tool search, or reusable toolsets	sub-skills/tools-and-toolsets/SKILL.md
Design structured outputs, output functions, ToolOutput, NativeOutput, multimodal inputs, message parts, or history serialization	sub-skills/outputs-and-messages/SKILL.md
Choose model strings, provider classes, optional extras, profiles, native tools, embeddings, fallback, concurrency, or provider troubleshooting	sub-skills/models-and-providers/SKILL.md
Connect MCP/FastMCP, capabilities, hooks, Logfire, A2A, durable execution, AG-UI, Vercel AI, or web integration surfaces	sub-skills/mcp-and-integrations/SKILL.md
Build Pydantic Evals datasets/evaluators/reports or pydantic-graph GraphBuilder workflows	sub-skills/evals-and-graph/SKILL.md
Use clai, pai, clai web, Agent.to_cli, Agent.to_web, custom agent loading, or app/example scaffolds	sub-skills/cli-and-apps/SKILL.md
Edit this repository, choose targeted tests, record cassettes, update docs/examples, follow contribution rules, or refresh generated skills	sub-skills/repo-development/SKILL.md

Install Baseline

Pydantic AI targets Python 3.10+ and is distributed as several related packages:

pip install pydantic-ai
pip install pydantic-ai-slim
pip install pydantic-graph pydantic-evals clai

Use pydantic-ai-slim[...] extras for optional providers and integrations. Do not install every extra by default; choose only the extras needed for the selected workflow.

Minimal import check:

import pydantic_ai
import pydantic_graph
import pydantic_evals
import clai

For deterministic code examples and tests, prefer pydantic_ai.models.test.TestModel or pydantic_ai.models.function.FunctionModel before making live provider requests.

Working Rules

• Use provider-prefixed model strings such as openai:gpt-5.2, anthropic:claude-opus-4-6, and google:gemini-3-pro-preview when examples intentionally call real providers.
• Treat provider SDKs, credentials, native tools, MCP servers, durable backends, UI servers, and cloud resources as optional surfaces that need explicit install/config checks.
• Do not run live model requests, record cassettes, start durable services, upload files, or mutate cloud resources unless the user explicitly asks and provides credentials/configuration.
• For repository edits, follow the scoped AGENTS.md and agent_docs/ guidance summarized in sub-skills/repo-development/SKILL.md.
• Keep generated skill usage self-contained: use these bundled references and scripts instead of depending on the original source docs, examples, tests, or scripts unless the task is explicitly about maintaining a Pydantic AI checkout.