Pydantic AI Agent Rules

A typed, provider-independent Python framework for building agents and working with language models.

Overview

Pydantic AI tells contributors to protect both the project and its users, then limits scope, compatibility changes, and verification claims. Topic and directory guides hold coding details; broad design principles do not justify broadening a fix.

Behavioral framing Verification by change type Nested instruction files

Documents

├── 
├──  · symlink → AGENTS.md
├── .claude
│   └── skills
│       └──  — Repository workflow skills
├── .github
│   ├── workflows
│   │   ├── 
│   │   └──  · symlink → AGENTS.md
│   └── 
├── agent_docs
│   └── 
├── docs
│   ├── realtime
│   │   ├── 
│   │   └──  · symlink → AGENTS.md
│   ├── 
│   ├── 
│   ├──  · symlink → AGENTS.md
│   ├── 
│   ├── 
│   ├── 
│   ├── 
│   ├── 
│   ├── 
│   ├── 
│   ├── 
│   ├── 
│   └── 
├── pydantic_ai_slim
│   └── pydantic_ai
│       ├── .agents
│       │   └── skills
│       │       └── building-pydantic-ai-agents
│       │           └──  — Product skills for building Pydantic AI agents
│       ├── capabilities
│       │   └── 
│       ├── durable_exec
│       │   └── 
│       ├── models
│       │   ├── 
│       │   └──  · symlink → AGENTS.md
│       ├── native_tools
│       │   ├── 
│       │   └──  · symlink → AGENTS.md
│       ├── profiles
│       │   └── 
│       ├── providers
│       │   └── 
│       ├── realtime
│       │   ├── 
│       │   └──  · symlink → AGENTS.md
│       ├── toolsets
│       │   └── 
│       ├── ui
│       │   ├── 
│       │   └──  · symlink → AGENTS.md
│       ├── 
│       └──  · symlink → AGENTS.md
└── tests
    └──

Techniques in this file

01 / Behavioral framing

Keep general design philosophy from widening a bug fix

The guide prefers extensible primitives for new designs but explicitly limits a fix to reproduced behavior. Sibling providers or fields enter the patch only after their shared defect has been confirmed.

63- 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. Every rule in this bullet binds your response to review feedback exactly as it binds your first commit: a reviewer's finding is not itself a license to enlarge the PR's scope, and a finding that claims a defect clears the same reproduce-and-confirm bar as anything else

02 / Behavioral framing

Define compatibility through existing behavior

Adding a defaulted parameter is not sufficient if users must pass a new argument to retain what they already had. The guide requires the default to preserve behavior and makes the new behavior opt-in.

65- be backward compatible as laid out in the [version policy](docs/version-policy.md), so that users can upgrade with confidence. A default doesn't make a new parameter non-breaking: if existing code only keeps its current behavior once the user passes a new argument (`id=None`, `strict=False`), that's a break, and it leaves behind a permanent parameter whose only purpose is to say "keep doing what you did". The default must preserve existing behavior; the new behavior is what users opt into

03 / Behavioral framing

Protect wider APIs from narrow fixes

The file describes product surfaces as nested: users of an adapter or durable engine also use the base Agent. A fix for the narrower layer must not change behavior for unaffected users of the wider one.

64- leave behavior unchanged for users who aren't hitting the problem you are solving. Pydantic AI's surfaces are nested, not peer: everyone using a durable execution engine, a single provider, a UI adapter, or an opt-in capability is also a plain `Agent` user, but not the reverse -- so a fix motivated by a narrow surface must not move observable behavior on a wider one. Documenting it doesn't make it acceptable, only expected; if no scoping leaves the wider surface untouched, that's a design question for maintainers, not a docs note. (Fixing the same *confirmed* defect in sibling providers, fields, or models in the same PR is the previous point, not this one.)

04 / Verification by change type

Reserve process isolation for process-dependent behavior

The test guidance explains the cost of starting another interpreter. It permits subprocesses for CLI, startup, or import isolation while keeping ordinary logic tests in process.

123Do not use subprocesses to test logic that can run in-process. Starting another interpreter and importing the project again makes the full test suite materially slower. Reserve subprocesses for behavior that depends on the process boundary, such as CLI invocation, interpreter startup, or import isolation.

05 / Nested instruction files

Use scoped guides for implementation details

The root file requires the topic index, then routes models, providers, tools, durable execution, UI, and other work to local guides. Global rules stay separate.

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