Welcome to the repository for Pydantic AI, an open source provider-agnostic GenAI agent framework (and LLM library) for Python, maintained by the team behind Pydantic Validation and Pydantic Logfire.

Your primary responsibility is to the project and its users

Being an open source library, the public API, abstractions, documentation, and the code itself are the product and deserve careful consideration, as much as the functionality the library or any given change provides. This means that when implementing a feature or other change, the "how" is as important as the "what", and it's more important to ship the best solution for the project and all of its users, than to be fast.

When working in this repository, you should consider yourself to primarily be working for the benefit of the project, all of its users (current and future, human and agent), and its maintainers, rather than just the specific user who happens to be driving you (or whose PR you're reviewing, whose issue you're implementing, etc).

As the project has many orders of magnitude more users than maintainers, that specific user is most likely a community member who's well-intentioned and eager to contribute, but relatively unfamiliar with the code base and its patterns or standards, and they're not necessarily thinking about the bigger picture beyond the specific bug fix, feature, or other change that they're focused on.

Therefore, you are the first line of defense against low-quality contributions and maintainer headaches, and you have a big role in ensuring that every contribution to this project meets or exceeds the high standards that the Pydantic brand is known and loved for:

• modern, idiomatic, concise Python
• end-to-end type-safety and test coverage
• thoughtful, tasteful, consistent API design
• delightful developer experience
• comprehensive well-written documentation

In other words, channel your inner Samuel Colvin. (British accent optional)

Gathering context on the task

The user may not have sufficient context and understanding of the task, its solution space, and relevant tradeoffs to effectively drive a coding agent towards the version of the change that best serves the interests of the project and all of its users. (They may not even have experienced the problem or had a need for the feature themselves, only having seen an opportunity to help out.)

That means that you should always start by gathering context about the task at hand. At minimum, this means:

• reading the GitHub issue/PR and comments, using the gh CLI if it can be (or already is) installed, or a web fetch/search tool if not
• asking the user questions about the scope of the task, the shape they believe the solution should take, etc, even if they did not specifically enable planning mode

Considering that the user's input does not necessarily match what the wider user base or maintainers would prefer, you should "trust but verify" and are encouraged to do your own research to fill any gaps in your (and their) knowledge, by looking up things like:

• relevant GitHub issues and PRs, especially if cross-linked from the main issue/PR
• LLM provider API docs and SDK type definitions
• other LLM/agent libraries' solutions to similar problems
• Pydantic AI documentation on related features and established API patterns
  • In particular, the docs on agents, dependency injection, tools, output, and message history are going to be relevant to many tasks.

Ensuring the task is ready for implementation

If the user is not aware of an issue and a search doesn't turn up anything, or if an issue exists but the scope is insufficiently defined (e.g. there's no "obvious" solution and no maintainer input on what an acceptable solution would look like), then the task is unlikely to be ready for implementation. Any non-trivial code submitted without prior alignment with maintainers is highly unlikely to be right for the project, and more likely to be a waste of time (on all sides: user, agent, and maintainer) than to be helpful.

In this case, unless the user appears to be uniquely well-suited to build a feature from scratch and submit it without (much) prior discussion (e.g. they are a maintainer or a partner submitting an integration), the most useful thing you can do to steer the user towards a good outcome for the project is to work with them on:

• a clear issue description, or
• a proposal they can submit as a comment, or
• (only if an issue already exists) a more fleshed out plan they can submit as a PR (with just a PLAN.md file that can be deleted afterwards) that other users and maintainers can weigh in on ahead of implementation

(Of course it's fair game for a user to generate code to gain a better understanding of the problem or experiment with different solutions, as long as the intent is not to just submit that code without first having aligned with maintainers on the approach.)

(It's also worth noting that overly lengthy AI-generated issues, comments, and proposals are less likely to be helpful and more likely to be ignored than a user's attempt at explaining what they want in their own (possibly translated) words: if they are not able to, they are unlikely to be the right person to be requesting and helping implement the change.)

Philosophy

Pydantic AI is meant to be a light-weight library that any Python developer who wants to work with LLMs and agents (whether simple or complex) should feel no hesitation to pull into their project. It's not meant to be everything to everyone, but it should enable people to build just about anything.

As such, we prefer strong primitives, powerful abstractions, and general solutions and extension points that enable people to build things that we hadn't even thought of, over narrow solutions for specific use cases, opinionated solutions that push a particular approach to agent design that hasn't yet stood the test of time, or generally "every single possible battery included" solutions that make the library unnecessarily bloated. This preference is about shaping designs, new public APIs, and extension points -- it is not a license to widen a bug fix beyond the defect you reproduced (see "Requirements of all contributions").

Requirements of all contributions

All changes need to:

• be thoughtful and deliberate about new abstractions, public APIs, and behaviors, as every wrong-in-retrospect choice (made in a rush or with insufficient context) makes life harder for hundreds of thousands of users (and agents), and is much more difficult to change later than to do right the first time
• be scoped to the problem you are solving: for a bug fix, make the narrowest change that resolves the reported, reproduced behavior -- often one line plus one regression test -- and stop. The preference for general primitives and powerful abstractions (see Philosophy) is for shaping designs and new public surface, not for widening a bug fix. Extend a fix to sibling fields, providers, or models only after confirming, by reproducing, that they share the same defect; an "others might also be affected" hunch is unacceptable: if a concern is verified, it can be included in the same PR if it doesn't explode scope or delays an already mergeable PR, otherwise it should be filed as an issue with enough context and guidance for someone to file a PR for it. Do not refactor a shared protocol, helper, or abstraction to fix one caller unless the narrow fix is unavailable or the refactor is itself the confirmed fix
• be backward compatible as laid out in the version policy, so that users can upgrade with confidence
• be fully type-safe (both internally and in public API) without unnecessary casts or Anys, so that users don't need isinstance checks and can trust that code that typechecks will work at runtime
• have comprehensive tests covering 100% of code paths, favoring integration tests and real requests (using recordings and snapshots -- see below) over unit tests and mocking
• update/add all relevant documentation, following the existing voice and patterns
• update the relevant agent skills when introducing a new feature or when a skill needs to reflect the correct mechanics; Pydantic AI skills belong in pydantic_ai_slim/pydantic_ai/.agents/skills/building-pydantic-ai-agents/, while repository workflow skills live under .claude/skills/

When you submit a PR, make sure you include the PR template and fill in the issue number that should be closed when the PR is merged. The "AI generated code" checkbox should always be checked manually by the user in the UI, not by the agent.

PR titles feed directly into the release changelog — wrap code identifiers (class names, keyword arguments, module paths, CLI flags, env vars) in backticks, matching the style of recent release notes (e.g. git log main --oneline -10).

Never add yourself (Claude) as a co-author on commits. Commits should be authored as the user only, with no Co-Authored-By trailer referencing Claude.

Repository structure

The repo contains a uv workspace defining multiple Python packages:

• pydantic-ai-slim in pydantic_ai_slim/: the agent framework, including the Agent class and Model classes for each model provider/API
  • This is a slim package with minimal dependencies and optional dependency groups for each model provider (e.g. openai, anthropic, google) or integration (e.g. logfire, mcp, temporal).
• pydantic-graph in pydantic_graph/: the type-hint based graph library that powers the agent loop
• pydantic-evals in pydantic_evals/: the evaluation framework for evaluating the arbitrary stochastic functions including LLMs and agents
• clai in clai/: a CLI (with an optional web UI) to chat with Pydantic AI agents
• pydantic-ai defined in pyproject.toml at the root, bringing in the packages above as well the optional dependency groups for all model providers and select integrations.

Development workflow

The project uses:

• uv, supporting Python 3.10 through 3.13
  • Install all dependencies with make install
• pre-commit, can be installed with uv tool install pre-commit
• ruff via make lint and make format
• pyright via make typecheck
• pytest in tests/, via make test, with:
  • inline-snapshot for inline assertions
  • pytest-recording and vcrpy for recording and playing back requests to model APIs
• mkdocs in docs/, via make docs and make docs-serve, served at https://ai.pydantic.dev, with:
  • mkdocstrings-python to generate API docs from docstrings and types
  • mkdocs-material to theme the docs
  • tests/test_examples.py to test all code examples in the docs (including docstrings)
• logfire for OTel instrumentation of Pydantic AI and httpx
  • If you have access to the Logfire MCP server, you can use it to inspect agent runs, tool calls, and model requests

When to verify

Pre-commit runs make lint, make format, and make typecheck automatically on every commit; CI additionally runs the full test suite. While iterating, only run targeted checks on the files/tests you have a specific reason to suspect:

• typecheck a single file: PYRIGHT_PYTHON_IGNORE_WARNINGS=1 uv run pyright path/to/file.py
• run a single test: uv run pytest path/to/test.py::test_name

Avoid make typecheck and make test between edits — both are slow and the pre-commit/CI gates cover them at the right time.

Coding Guidelines

When generating or reviewing code anywhere in this repo, always read agent_docs/index.md and follow/enforce those guidelines. Don't forget to read the linked "topic guides" when appropriate.

Additionally, always read the directory-specific instructions when working in those directories:

• docs/AGENTS.md
• pydantic_ai_slim/pydantic_ai/AGENTS.md
• pydantic_ai_slim/pydantic_ai/capabilities/AGENTS.md
• pydantic_ai_slim/pydantic_ai/durable_exec/AGENTS.md
• pydantic_ai_slim/pydantic_ai/models/AGENTS.md
• pydantic_ai_slim/pydantic_ai/native_tools/AGENTS.md
• pydantic_ai_slim/pydantic_ai/profiles/AGENTS.md
• pydantic_ai_slim/pydantic_ai/providers/AGENTS.md
• pydantic_ai_slim/pydantic_ai/toolsets/AGENTS.md
• pydantic_ai_slim/pydantic_ai/ui/AGENTS.md
• tests/AGENTS.md

Awesome Agent Conventions

A curated field guide to the convention files AI agents read, write, and act on.

22 conventions across 11 categories. From common project instruction files to newer agent-web discovery and trust formats.

Agent tools increasingly rely on plain files in a repository or website root: instructions, memory, rules, tool connections, prompt assets, discovery metadata, and protocol hints. The names are easy to mix up, and the adoption levels vary a lot.

This repo keeps the map practical:

• Know what a file is for. Each entry names the convention, usual filename, primary readers, and spec or source.
• Study real examples. Examples are fetched from public repositories by script, with provenance kept at the top of each file.
• Separate practice from proposal. Maturity labels show what is widely used, what is early, and what is still only proposed.

Contents

• Instruction & context · category page
  • 🟢 AGENTS.md
  • 🟢 CLAUDE.md
  • 🟢 Tool-specific instruction files
  • 🟠 OKF (Open Knowledge Format)
• Memory & state · category page
  • 🟢 MEMORY.md
  • 🟢 Memory Bank
• Spec-driven development · category page
  • 🟢 Spec Kit
  • 🟢 Kiro steering files
• Skills & prompt assets · category page
  • 🟢 SKILL.md
  • 🟢 Prompt asset files
  • 🟢 Claude Code commands
  • 🟢 Copilot prompt & instruction files
• Tooling & connections · category page
  • 🟢 MCP server config
• Rules & ignore files · category page
  • 🟢 Rules files
  • 🟢 AI ignore files
• Design · category page
  • 🟢 DESIGN.md
• Web & discoverability · category page
  • 🟢 llms.txt
  • 🟢 pricing.md
• Agent-web trust · category page
  • 🟠 auth.md
  • 🔵 ai.txt
• Identity & protocols · category page
  • 🟠 Agent Cards (A2A)
• Proposed namespace · category page
  • 🔵 The protocols.md namespace

What counts

This list is intentionally narrow. A file belongs here when it is a convention for agent behavior or agent-readable metadata: instructions, memory, skills, rules, tool config, prompt assets, or web-discovery hints.

Any file type can qualify - .md, .txt, .prompty, .json, dotfiles, or a directory pattern. Human-first project docs such as README.md, CONTRIBUTING.md, SECURITY.md, and CHANGELOG.md stay out unless the file has become an agent convention in its own right.

Maturity tiers

The badge is a claim about adoption, not quality. It keeps a proven convention from being presented the same way as a new idea.

Badge	Tier	Meaning
🟢	Adopted	Used in production by multiple tools, projects, or teams.
🟠	Emerging	Published by a real organization, but still early or limited in adoption.
🔵	Proposed	Publicly described, but without clear adoption beyond the proposal.

Instruction & context

Standalone page: categories/instruction-context.md

	Convention	Files	Read by	Spec
🟢	AGENTS.md	AGENTS.md	Most coding agents - OpenAI Codex, Cursor, Jules, Aider, Gemini CLI, Zed, and others	spec ↗
🟢	CLAUDE.md	CLAUDE.md	Claude Code, and tools that read the Claude memory convention	spec ↗
🟢	Tool-specific instruction files	GEMINI.md AGENT.md QWEN.md WARP.md CONVENTIONS.md copilot-instructions.md	Each file is read by its namesake tool - Gemini CLI, Amp, Qwen Code, Warp, Aider, GitHub Copilot - often alongside or as a bridge to AGENTS.md	spec ↗
🟠	OKF (Open Knowledge Format)	.md	Agents over MCP (okfy, openknowledge, superops okf CLIs); Google's knowledge-catalog ingests bundles	spec ↗

• AGENTS.md - A plain-Markdown "README for agents" - build/test commands, conventions, and gotchas an agent needs before touching the code. The most widely adopted cross-tool instruction file.
• CLAUDE.md - Anthropic's memory file for Claude Code - loaded automatically at session start to carry project commands, style rules, and standing instructions across turns.
• Tool-specific instruction files - Per-tool instruction files that predate or coexist with AGENTS.md. Some tools now default to AGENTS.md while keeping legacy filenames alive, so these variants still matter when auditing real repositories.
• OKF (Open Knowledge Format) - A machine-first organizational knowledge base: a version-controlled folder of typed Markdown files (one concept per file) that any agent reads as ground-truth context. Open-sourced by Google Cloud in 2026 as the content layer to MCP's transport.

Memory & state

Standalone page: categories/memory-state.md

	Convention	Files	Read by	Spec
🟢	MEMORY.md	MEMORY.md	Claude Code's auto-memory - the per-project MEMORY.md index it writes and re-reads each session	spec ↗
🟢	Memory Bank	projectbrief.md productContext.md activeContext.md systemPatterns.md techContext.md progress.md	Cline, Roo Code, and Cursor (via the Memory Bank custom-instructions pattern)	spec ↗

• MEMORY.md - A persistent, agent-maintained index of durable facts - written and re-read across sessions so an agent accumulates project memory instead of relearning each time.
• Memory Bank - Cline's structured memory system - a set of Markdown files an agent reads at the start of every task to reconstruct full project context after its session memory resets. The six files shown are Cline's set; tools like Roo Code use an overlapping but different variant.

Spec-driven development

Standalone page: categories/spec-driven-development.md

	Convention	Files	Read by	Spec
🟢	Spec Kit	constitution.md spec.md plan.md tasks.md	GitHub Spec Kit's slash-command agents (Copilot, Claude, Gemini, Cursor, and more)	spec ↗
🟢	Kiro steering files	product.md structure.md tech.md	AWS Kiro (steering files are largely Kiro-specific)	spec ↗

• Spec Kit - GitHub's spec-driven workflow - a constitution plus per-feature spec → plan → tasks files that drive an agent through structured, reviewable implementation.
• Kiro steering files - Kiro's always-on steering docs - product, structure, and tech files that give the agent persistent project context outside of any single spec.

Skills & prompt assets

Standalone page: categories/skills-prompt-assets.md

	Convention	Files	Read by	Spec
🟢	SKILL.md	SKILL.md	Claude Agent Skills, Claude Code, Amp, Agent Skills-compatible tools	spec ↗
🟢	Prompt asset files	.prompty .prompt system_prompt.txt	Prompty tooling, Azure AI / Semantic Kernel, and apps that load externalized prompts	spec ↗
🟢	Claude Code commands	.md	Claude Code - project .claude/commands/ and user ~/.claude/commands/	spec ↗
🟢	Copilot prompt & instruction files	.prompt.md .instructions.md	GitHub Copilot in VS Code / Copilot CLI	spec ↗

• SKILL.md - A self-contained, model-invoked capability file that tells an agent when to load a reusable procedure and how to execute it.
• Prompt asset files - Externalized prompt files - Prompty's YAML-front-mattered .prompty, plain .prompt templates, and system_prompt.txt - that pull the prompt out of source code so it can be versioned and edited on its own. Only .prompty has a formal spec (prompty.ai); .prompt and system_prompt.txt are ad-hoc externalized-prompt filenames.
• Claude Code commands - A Markdown file Claude Code exposes as a /slash-command - a reusable, version-controlled prompt workflow, with optional frontmatter (allowed-tools, model, argument-hint) and $ARGUMENTS and shell placeholders (@file references are a general Claude Code prompt feature, not command-specific). Now converging with Agent Skills, but still widely committed in its own right.
• Copilot prompt & instruction files - Modular, path-scoped Copilot context: *.instructions.md auto-attach to matching files via an applyTo glob, while *.prompt.md are reusable prompts you invoke by name - the granular cousins of a single .github/copilot-instructions.md.

Tooling & connections

Standalone page: categories/tooling-connections.md

	Convention	Files	Read by	Spec
🟢	MCP server config	.mcp.json	Claude Code, Cursor, VS Code / Copilot, and Claude Desktop - every MCP host reads the same mcpServers schema, though the filename and path differ per tool	spec ↗

• MCP server config - A JSON file that tells an agent which Model Context Protocol servers to launch and how (command, args, env) - making a project's tool and data integrations portable, shareable, and version-controlled across every MCP-capable client.

Rules & ignore files

Standalone page: categories/rules-ignore-files.md

	Convention	Files	Read by	Spec
🟢	Rules files	.cursorrules .mdc .clinerules .clinerules/ (pattern) .windsurfrules	Cursor (.cursorrules / .mdc), Cline (.clinerules/ and legacy .clinerules), Windsurf (.windsurfrules)	spec ↗
🟢	AI ignore files	.aiignore .cursorignore .codeiumignore .aiexclude	JetBrains Junie (.aiignore), Cursor (.cursorignore), Codeium/Windsurf (.codeiumignore)	spec ↗

• Rules files - Per-tool rule files that scope agent behavior - older single-file forms (.cursorrules, .clinerules, .windsurfrules) and newer directory-based, glob-scoped forms (.cursor/rules/.mdc, .clinerules/, .windsurf/rules/.md).
• AI ignore files - gitignore-syntax files that fence an AI agent out of paths - secrets, vendored code, generated output - so they're never sent to the model as context.

Design

Standalone page: categories/design.md

	Convention	Files	Read by	Spec
🟢	DESIGN.md	DESIGN.md	Google Stitch natively; and coding agents (e.g. Claude Code) when pointed at it as design context	spec ↗

• DESIGN.md - A structured, machine-readable design specification - tokens, components, and layout intent - that an agent reads to generate or keep UI consistent with an established system. Open-sourced by Google Labs in 2026 as a cross-tool draft spec.

Web & discoverability

Standalone page: categories/web-discoverability.md

	Convention	Files	Read by	Spec
🟢	llms.txt	llms.txt llms-full.txt (pattern)	Docs sites publish it for LLM tools and crawlers - though no major provider has confirmed reading it	spec ↗
🟢	pricing.md	pricing.md	Agents and LLM browsers fetching a clean, parse-able pricing page	spec ↗

• llms.txt - A proposed-turned-widely-published standard: a root-level Markdown file giving LLMs a curated, link-rich map of a site's docs. Published across hundreds of developer-docs sites - though whether the major LLM providers actually read it remains unproven.
• pricing.md - The Markdown twin of a pricing page - same URL with a .md suffix - so an agent gets structured plans and numbers instead of scraping marketing HTML. A concrete, shipping instance of the page.md pattern.

Agent-web trust

Standalone page: categories/agent-web-trust.md

	Convention	Files	Read by	Spec
🟠	auth.md	auth.md	Agents discovering how to authenticate to a service (early adopters)	spec ↗
🔵	ai.txt	ai.txt	AI training/data-mining crawlers that voluntarily honor AI usage preferences; crawler support is not yet reliable	spec ↗

• auth.md - A Markdown file that tells an agent how to authenticate with a service - discovery of auth endpoints and flows. Shipped by WorkOS as a real, working convention, but adoption beyond it is still early.
• ai.txt - A text file declaring machine-readable consent, licensing, or policy preferences for AI training and data-mining. Spawning popularized the deployed root-file pattern, and a 2026 Internet-Draft now proposes a well-known URI; adoption and crawler obedience are still thin, so it stays 🔵.

Identity & protocols

Standalone page: categories/identity-protocols.md

	Convention	Files	Read by	Spec
🟠	Agent Cards (A2A)	agent-card.json agent.json (pattern)	A2A-compatible agents discovering another agent's capabilities	spec ↗

• Agent Cards (A2A) - The Agent2Agent (A2A) capability card - a JSON document at a well-known path advertising an agent's skills, endpoints, and auth so other agents can discover and call it. Now a Linux Foundation project at v1.0; adoption is growing but early.

Proposed namespace

Standalone page: categories/proposed-namespace.md

	Convention	Files	Read by	Spec
🔵	The protocols.md namespace	proof.md	- (no demonstrated readers; aspirational)	spec ↗

• The protocols.md namespace - A single maintainer's pre-registered namespace of ~74 aspirational .md "protocols" (proof.md, signature.md, reputation.md, …) staked as Schelling points for a future agent web. Published concept, no demonstrated adoption - see the page for the audited, honest caveats.

Maintaining examples

Example files are fetched, not invented. The extractor pulls them from public sources, stores them under conventions/<slug>/examples/<source>/<filename>, and adds a line-1 provenance comment. The examples remain under their upstream owners' licenses and terms; see THIRD_PARTY_EXAMPLES.md before reusing them.

To refresh everything:

pip install -r scripts/requirements.txt
python scripts/extract.py          # fetch real files + rebuild each convention's README
python scripts/build_readme.py     # rebuild this README from scripts/targets.json

Re-running is idempotent. A missing target prints a miss and is skipped. Examples are representative samples: any file over 256 KB (for example, a multi-MB llms-full.txt) is truncated with a marker pointing back to the full source. scripts/targets.json remains the source of truth for conventions that have not been migrated yet; the skill-md pilot uses local convention metadata instead. Edit the relevant source and re-run both scripts.

Shortcut targets are available in the Makefile:

make verify          # schema + generated files + example provenance + links
make extract         # refetch public examples and rebuild generated docs
make license-report  # summarize upstream licenses for vendored examples

CI keeps the generated files and links honest. The verify workflow checks that generated docs match catalog metadata and migrated local metadata, and that every spec, example, and instance URL still resolves on each pull request and weekly. Run the same link check locally with python scripts/check_links.py.

Contributing

Read CONTRIBUTING.md. In short: an entry must pass the filter above and carry evidence for its maturity tier. Add sources to scripts/targets.json for non-migrated conventions, run the scripts, and open a PR. The skill-md pilot uses local convention metadata instead. Do not hand-write example files.

Before proposing adjacent standards, check WATCHLIST.md. Project direction lives in ROADMAP.md.

License

The curation, scripts, and original prose in this repository are MIT. Vendored example files remain under their upstream owners' licenses and terms; see THIRD_PARTY_EXAMPLES.md.