Pydantic AI Docs
PydanticAIDocs gives an agent a single tool, read_pyai_docs(topic), that locates a Pydantic AI documentation page and returns it in full. Nothing is bundled into context up front. Each call resolves the topic from a configured checkout inside the run workspace first, then falls back to fetching the page from pydantic/pydantic-ai:main (the remote fallback needs network access).
While Pydantic AI Harness is on 0.x releases, the API may change between minor releases; when it does, deprecation warnings and release-note migration guidance tell you (or your agent) exactly how to upgrade. See the version policy.
An agent that authors Pydantic AI capabilities, hooks, tools, or toolsets needs the current docs for those APIs. Preloading the docs into the system prompt spends context the agent rarely needs in full, and pins a snapshot that drifts from main.
PydanticAIDocs exposes one tool, read_pyai_docs(topic), that locates the requested page and returns it in full, with its model aliases resolved. Each call resolves the topic from a configured checkout inside the run workspace first, then falls back to fetching the page from pydantic/pydantic-ai:main (the remote fallback needs network access).
The available topics are capabilities, hooks, tools, tools-advanced, toolsets, and agent.
Construct an Agent with PydanticAIDocs() in its capabilities. Point local_docs_path at a Pydantic AI docs checkout inside the run workspace, or omit it to always fetch from the remote source. Relative paths use the workspace working directory:
from pathlib import Path
from pydantic_ai import Agent
from pydantic_ai.capabilities import LocalWorkspace
from pydantic_ai_harness import PydanticAIDocs
agent = Agent(
'anthropic:claude-sonnet-5-5',
capabilities=[LocalWorkspace('.'), PydanticAIDocs(local_docs_path=Path('docs'))],
)
result = agent.run_sync('Read the toolsets docs, then explain how to build a FunctionToolset.')
print(result.output)
A configured local checkout is read through the run’s workspace, so a run with a local path and no workspace fails at its start. With no local path configured, every call goes to the remote source and no workspace is needed.
The capability also adds a short static instruction telling the model that the read_pyai_docs tool exists and to read the relevant topic before authoring or modifying a Pydantic AI capability, hook, tool, or toolset, rather than relying on memory. The instruction is cache-stable, so it does not invalidate the prompt-cache prefix between turns.
Each call resolves in this order:
- Workspace checkout — when
local_docs_path(or thePYDANTIC_AI_HARNESS_DOCS_PATHenvironment variable) is set and the topic’s page exists under it inside the run workspace ({path}/{topic}.md, or{path}/capabilities/overview.mdforcapabilities), that file is read and returned. - Remote fetch — otherwise the page is fetched from the same path under
https://raw.githubusercontent.com/pydantic/pydantic-ai/main/docs/. - Neither resolves — a descriptive error naming the local path tried and the URL.
Docs pages name models through aliases, which the docs site replaces with current models. Before returning a page that uses one, the tool reads the alias file, model_aliases/aliases.json, in the same order and replaces each alias with the model it names. An alias the file does not define is left as written, and so is every alias when neither source can provide the file. A page without aliases reads nothing else, so a checkout from before the alias file existed keeps working.
The capability never runs git. Keep the local checkout current yourself; the remote path always reads main, so it is the fresh fallback.
local_docs_path takes precedence over the PYDANTIC_AI_HARNESS_DOCS_PATH environment variable. ~ is not expanded — use an absolute workspace path or a path relative to its working directory. With neither path set, every call goes straight to the remote source.
| Option | Default | Purpose |
|---|---|---|
local_docs_path | None | Pyai docs checkout inside the run workspace. Relative paths use the workspace working directory. Falls back to the PYDANTIC_AI_HARNESS_DOCS_PATH environment variable, then to the remote source. |
cache | True | Memoize each returned doc for one agent run, so repeated reads within that run do not repeat workspace or network I/O. |
Caching is isolated per run so content read from one workspace is not reused in another. Set cache=False to re-read or re-fetch on every call within a run.
PydanticAIDocs declares the default id 'pydantic_ai_docs'. The id keys the capability’s instructions, so they
can be addressed, and lets defer_loading=True work without one. Two PydanticAIDocss on one agent that
share it are one docs source stated twice: they become one when they agree, and the agent raises a
UserError when it’s built if they differ. To keep two, give each its own id and wrap them
in PrefixTools, since both register read_pyai_docs.
Earlier releases declared no default id, so two always failed on the tool name when the run
started. Two identical ones now become one, and two that differ fail when the agent is built.
PydanticAIDocs works with Pydantic AI’s agent spec feature for defining agents in YAML or JSON. Its serialization name is PydanticAIDocs:
# agent.yaml
model: anthropic:claude-sonnet-5-5
capabilities:
- PydanticAIDocs: {}
from pydantic_ai import Agent
from pydantic_ai_harness import PydanticAIDocs
agent = Agent.from_file('agent.yaml', custom_capability_types=[PydanticAIDocs])
result = agent.run_sync('...')
print(result.output)
Pass custom_capability_types so the spec loader knows how to instantiate PydanticAIDocs.
Specs saved before the rename from PyaiDocs use the old block name. To keep loading
them, pass the deprecated PyaiDocs class (imported from pydantic_ai_harness.docs,
which emits a deprecation warning) alongside or instead of PydanticAIDocs — it keeps
the PyaiDocs serialization name. Re-save with PydanticAIDocs to migrate.
Bases: AbstractCapability[AgentDepsT]
Locate and return Pydantic AI documentation on demand.
Exposes a single read_pyai_docs(topic) tool. Docs are located and returned
when asked for — never bundled into context. Each call resolves the topic
from a configured local checkout first, then falls back to fetching the page
from pydantic/pydantic-ai:main, so it works in any environment.
The local checkout path comes from local_docs_path, or the
PYDANTIC_AI_HARNESS_DOCS_PATH env var when that is unset; with neither set
every call goes straight to the remote source. The checkout is read through
the run’s workspace, and a run with a local path but no workspace fails at its
start. The capability never runs git — keep
the local checkout current yourself; the remote path always reads main.
from pathlib import Path
from pydantic_ai import Agent
from pydantic_ai.capabilities import LocalWorkspace
from pydantic_ai_harness.pydantic_ai_docs import PydanticAIDocs
agent = Agent(
'anthropic:claude-sonnet-4-6',
capabilities=[LocalWorkspace('.'), PydanticAIDocs(local_docs_path=Path('docs'))],
)
Pyai docs checkout inside the workspace. Relative paths use the workspace
working directory. When None, falls back to the
PYDANTIC_AI_HARNESS_DOCS_PATH env var, then to the remote source.
Type: Path | None Default: None
If True, each returned doc is memoized for one agent run.
Type: bool Default: True
Stable capability ID, so its instructions are addressable and defer_loading=True needs none.
An agent has one read_pyai_docs tool, so two PydanticAIDocs sharing this id are one docs source
stated twice when they agree, and an error when they differ. To keep two, give each its own id and
wrap them in PrefixTools, since their tool names are the same.
Type: str | None Default: 'pydantic_ai_docs'
@classmethod
def combine(
cls,
capabilities: Sequence[AbstractCapability[AgentDepsT]],
) -> AbstractCapability[AgentDepsT]
Two under one id are one docs source stated twice; two that disagree raise rather than merge.
AbstractCapability[AgentDepsT]
@async
def for_run(ctx: RunContext[AgentDepsT]) -> PydanticAIDocs[AgentDepsT]
Return a fresh per-run cache so workspace-local content cannot cross runs.
PydanticAIDocs[AgentDepsT]
@async
def before_run(ctx: RunContext[AgentDepsT]) -> None
Fail the run at its start when a local checkout is configured but no workspace holds it.
def get_instructions() -> AgentInstructions[AgentDepsT] | None
Static, cache-stable guidance on using the docs tool.
AgentInstructions[AgentDepsT] | None
def get_toolset() -> AgentToolset[AgentDepsT] | None
Toolset providing read_pyai_docs over the resolved local path and shared cache.
AgentToolset[AgentDepsT] | None
@classmethod
def get_serialization_name(cls) -> str | None
Serialization name for agent-spec support.