pydantic/pydantic-ai

You declare a [name][pydantic_ai.messages.InstructionPart.name]; the framework issues an [id][pydantic_ai.messages.InstructionPart.id]. Name a part relative to what you own — 'limits', not 'toolset:weather:limits' — and the source contributing it supplies the rest, so you never repeat your own identity and can never claim another source's key. The [InstructionId][pydantic_ai.messages.InstructionId] you get back pairs the [source][pydantic_ai.messages.InstructionId.source] that contributed the part with the [name][pydantic_ai.messages.InstructionId.name], if there is one, and renders as its seg

!!! info "Usage tracking for cancelled streams" Token usage reported by usage after cancellation is partial and provider-dependent. Pydantic AI stops pulling from the stream immediately, so final usage events may never arrive; some provider SDKs may also continue generation server-side after the local stream is closed. Do not rely on cancelled-stream usage for cost-critical accounting. For OpenAI chat completions, [openai_continuous_usage_stats][pydantic_ai.models.openai.OpenAIChatModelSettings] can improve in-stream usage reporting by requesting cumulative usage data with each chunk, but canc

A restriction is a conclusion you earn from a real failure, not a field you read. Never report an operation as blocked, unavailable, or not-permitted based on a metadata flag, a config field, or a docs claim — attempt it and quote the actual error. (maintainerCanModify: false on a PR does not mean you cannot push: it governs the upstream-maintainer auto-grant, not your own access to the fork.) If you genuinely cannot attempt it, say "not attempted", never "we can't".

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.

Provider-adaptive WebSearch and WebFetch capabilities are now native-only and raise on models that don't support them, and MCP(url=...) runs the server locally by default. Restore the V1 fallbacks with WebSearch(local='duckduckgo'), WebFetch(local=True), and MCP(url=..., native=True). Announced via #5331; changed in #5333.

!!! note Cost is best-effort: it's None for models and providers genai-prices has no pricing data for, including models released after your install unless you keep prices up to date. With a [cost_limit][pydantic_ai.usage.UsageLimits.cost_limit], a run that could not be priced at all emits [CostNotFoundWarning][pydantic_ai.exceptions.CostNotFoundWarning] rather than being silently unconstrained; an unexpected pricing failure emits [CostCalculationFailedWarning][pydantic_ai.exceptions.CostCalculationFailedWarning]. Don't rely on cost_limit as a hard billing guarantee — pair it with [request_limi

The asyncio environment cancels the task the run happens to be on: asyncio.Task.cancel(), asyncio.timeout() expiring, a [TaskGroup][asyncio.TaskGroup] tearing down after a sibling failed, a server shutting down, workflow cancellation under durable execution. All of these deliver the very same CancelledError signal, so Pydantic AI cannot tell a stop button from a timeout -- and the exception's type is load-bearing for everything built on it: asyncio.timeout() only produces TimeoutError, a TaskGroup only treats the task as cleanly cancelled, and Temporal only ends the workflow as Cancelled if Ca

Spell the name out as well when the tag has to match something you don't control. It's the identifier the UI adapters put on the wire, as the AG-UI event's name and the Vercel AI chunk's data-{name} type, and derivation only ever produces snake case: a frontend that already expects data-indexProgress or a dotted ui.progress needs name='indexProgress' or name='ui.progress' rather than a class renamed to suit it.

CI checks that every link between doc pages resolves, anchor included, and fails on Cannot find fragment. A heading's anchor is generated from its text, so renaming one silently breaks every link pointing at it. Where a heading is linked to, pin its anchor with {#custom-id} — the heading text is then free to change without moving the anchor.

All routes in docs/navigation.yml are relative to the Pydantic AI documentation root. Give each page its complete canonical route in slug; use aliases only for redirect sources. Do not prefix either value with /ai or a leading slash.

Do not force-push updates to an open PR. Rewriting its commits invalidates previous reviews; push follow-up commits instead. We will squash them when merging.

We do not automatically triage every new PR. PRs on issues we have not pre-aligned on are not in our review queue, regardless of how well written they are. If no maintainer has agreed to the change on an issue and assigned it to you, assume we have not seen your PR.

Please don't spend effort chasing green CI, addressing every automated review comment, or rebasing for merge conflicts on a PR we haven't pre-aligned on. If we take the change forward, that polish gets thrown away when we rewrite. Get the approach working, then stop and ping us on Slack.

Want a feature or API change? Open an issue describing the problem you're solving. Do not start with code.

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

Do not leave work uncommitted. Don't end a turn with unstaged or uncommitted local changes unless the user's own instructions say otherwise.

Pushing is not the end of the task. After you push, do not go idle. The work is done when CI is green and there are no unresolved comments — see the pushing-commits-to-the-repo skill for the full loop.

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