fix xrefs

dsfaccini · dsfaccini · commit a2772d2ce85e · 2026-03-27T10:25:42.000-05:00
diff --git a/docs/agent-spec.md b/docs/agent-spec.md
@@ -26,15 +26,15 @@ capabilities:
 
 ## Loading specs
 
-[`Agent.from_file`][pydantic_ai.Agent.from_file] loads a spec from a YAML or JSON file and constructs an agent:
+[`Agent.from_file`][pydantic_ai.agent.Agent.from_file] loads a spec from a YAML or JSON file and constructs an agent:
 
 ```python {title="from_file_example.py" test="skip"}
 from pydantic_ai import Agent
 
 agent = Agent.from_file('agent.yaml')
 ```
 
-[`Agent.from_spec`][pydantic_ai.Agent.from_spec] accepts a dict or [`AgentSpec`][pydantic_ai.agent.spec.AgentSpec] instance and supports additional keyword arguments that supplement or override the spec:
+[`Agent.from_spec`][pydantic_ai.agent.Agent.from_spec] accepts a dict or [`AgentSpec`](#agentspec-reference) instance and supports additional keyword arguments that supplement or override the spec:
 
 ```python {title="from_spec_example.py"}
 from dataclasses import dataclass
@@ -71,15 +71,15 @@ For more control over spec loading, use [`AgentSpec.from_file`][pydantic_ai.agen
 
 ## Template strings
 
-[`TemplateStr`][pydantic_ai.TemplateStr] provides Handlebars-style templates (`{{variable}}`) that are rendered against the agent's [dependencies](dependencies.md) at runtime. In spec files, strings containing `{{` are automatically converted to template strings:
+[`TemplateStr`][pydantic_ai._template.TemplateStr] provides Handlebars-style templates (`{{variable}}`) that are rendered against the agent's [dependencies](dependencies.md) at runtime. In spec files, strings containing `{{` are automatically converted to template strings:
 
 ```yaml {test="skip"}
 instructions: "You are assisting {{name}}, who is a {{role}}."
 ```
 
 Template variables are resolved from the fields of the `deps` object. When a `deps_type` (or [`deps_schema`](#deps_schema)) is provided, template variable names are validated at construction time.
 
-In Python code, [`TemplateStr`][pydantic_ai.TemplateStr] can be used explicitly, but a callable with [`RunContext`][pydantic_ai.tools.RunContext] is generally preferred for IDE autocomplete and type checking:
+In Python code, [`TemplateStr`][pydantic_ai._template.TemplateStr] can be used explicitly, but a callable with [`RunContext`][pydantic_ai.tools.RunContext] is generally preferred for IDE autocomplete and type checking:
 
 ```python {title="template_instructions.py"}
 from dataclasses import dataclass
@@ -117,7 +117,7 @@ See [Publishing capabilities](capabilities.md#publishing-capabilities) for how t
 
 ## `AgentSpec` reference
 
-The [`AgentSpec`][pydantic_ai.agent.spec.AgentSpec] model represents the full spec structure:
+The [`AgentSpec`](#agentspec-reference) model represents the full spec structure:
 
 | Field | Type | Description |
 |---|---|---|
diff --git a/docs/api/agent_spec.md b/docs/api/agent_spec.md
@@ -0,0 +1,11 @@
+# `pydantic_ai.agent.spec`
+
+::: pydantic_ai.agent.spec
+    options:
+        members:
+            - AgentSpec
+
+::: pydantic_ai._template
+    options:
+        members:
+            - TemplateStr
diff --git a/docs/api/toolsets.md b/docs/api/toolsets.md
@@ -3,6 +3,7 @@
 ::: pydantic_ai.toolsets
     options:
         members:
+        - AgentToolset
         - AbstractToolset
         - CombinedToolset
         - ExternalToolset
diff --git a/docs/capabilities.md b/docs/capabilities.md
@@ -362,11 +362,11 @@ The callable receives a [`RunContext`][pydantic_ai.tools.RunContext] where `ctx.
 
 | Method | Return type | Purpose |
 |---|---|---|
-| [`get_toolset()`][pydantic_ai.capabilities.AbstractCapability.get_toolset] | [`AgentToolset`][pydantic_ai.toolsets.AgentToolset] `\| None` | A [toolset](toolsets.md) to register (or a callable for [dynamic toolsets](toolsets.md#dynamically-building-a-toolset)) |
+| [`get_toolset()`][pydantic_ai.capabilities.AbstractCapability.get_toolset] | [`AgentToolset`][pydantic_ai.toolsets.AgentToolset] \| `None` | A [toolset](toolsets.md) to register (or a callable for [dynamic toolsets](toolsets.md#dynamically-building-a-toolset)) |
 | [`get_builtin_tools()`][pydantic_ai.capabilities.AbstractCapability.get_builtin_tools] | `Sequence[`[`AgentBuiltinTool`][pydantic_ai.tools.AgentBuiltinTool]`]` | [Builtin tools](builtin-tools.md) to register (including callables) |
-| [`get_wrapper_toolset()`][pydantic_ai.capabilities.AbstractCapability.get_wrapper_toolset] | [`AbstractToolset`][pydantic_ai.toolsets.AbstractToolset] `\| None` | [Wrap the agent's assembled toolset](#toolset-wrapping) |
-| [`get_instructions()`][pydantic_ai.capabilities.AbstractCapability.get_instructions] | [`AgentInstructions`][pydantic_ai.agent.AgentInstructions] `\| None` | [Instructions](agent.md#instructions) (static strings, [template strings](agent-spec.md#template-strings), or callables) |
-| [`get_model_settings()`][pydantic_ai.capabilities.AbstractCapability.get_model_settings] | [`AgentModelSettings`][pydantic_ai.agent.AgentModelSettings] `\| None` | [Model settings](agent.md#model-run-settings) dict, or a callable for per-step settings |
+| [`get_wrapper_toolset()`][pydantic_ai.capabilities.AbstractCapability.get_wrapper_toolset] | [`AbstractToolset`][pydantic_ai.toolsets.AbstractToolset] \| `None` | [Wrap the agent's assembled toolset](#toolset-wrapping) |
+| [`get_instructions()`][pydantic_ai.capabilities.AbstractCapability.get_instructions] | [`AgentInstructions`][pydantic_ai.agent.AgentInstructions] \| `None` | [Instructions](agent.md#instructions) (static strings, [template strings](agent-spec.md#template-strings), or callables) |
+| [`get_model_settings()`][pydantic_ai.capabilities.AbstractCapability.get_model_settings] | [`AgentModelSettings`][pydantic_ai.agent.AgentModelSettings] \| `None` | [Model settings](agent.md#model-run-settings) dict, or a callable for per-step settings |
 
 ### Hooking into the lifecycle
 
diff --git a/docs/extensibility.md b/docs/extensibility.md
@@ -25,7 +25,7 @@ To make a capability installable and usable in [agent specs](agent-spec.md):
 
 3. **Package naming** — use the `pydantic-ai-` prefix (e.g. `pydantic-ai-guardrails`) so users can find your package.
 
-4. **Registration** — users pass custom capability types via `custom_capability_types` on [`Agent.from_spec`][pydantic_ai.Agent.from_spec] or [`Agent.from_file`][pydantic_ai.Agent.from_file].
+4. **Registration** — users pass custom capability types via `custom_capability_types` on [`Agent.from_spec`][pydantic_ai.agent.Agent.from_spec] or [`Agent.from_file`][pydantic_ai.agent.Agent.from_file].
 
 ```python {test="skip" lint="skip"}
 from pydantic_ai import Agent
diff --git a/docs/thinking.md b/docs/thinking.md
@@ -91,7 +91,7 @@ agent = Agent(model, model_settings=settings)
 To enable thinking, use the [`AnthropicModelSettings.anthropic_thinking`][pydantic_ai.models.anthropic.AnthropicModelSettings.anthropic_thinking] [model setting](agent.md#model-run-settings).
 
 !!! note
-    Extended thinking (`type: 'enabled'` with `budget_tokens`) is deprecated on `claude-opus-4-6`+. For those models, use [adaptive thinking](#adaptive-thinking--effort) instead.
+    Extended thinking (`type: 'enabled'` with `budget_tokens`) is deprecated on `claude-opus-4-6`+. For those models, use [adaptive thinking](#adaptive-thinking-effort) instead.
 
 ```python {title="anthropic_thinking_part.py"}
 from pydantic_ai import Agent
diff --git a/pydantic_ai_slim/pydantic_ai/agent/__init__.py b/pydantic_ai_slim/pydantic_ai/agent/__init__.py
@@ -800,7 +800,7 @@ def from_file(
         The file format is inferred from the extension (`.yaml`/`.yml` or `.json`)
         unless overridden with the `fmt` argument.
 
-        All other arguments are forwarded to [`from_spec`][pydantic_ai.Agent.from_spec].
+        All other arguments are forwarded to [`from_spec`][pydantic_ai.agent.Agent.from_spec].
         """
         spec = AgentSpec.from_file(path, fmt=fmt)
         return cls.from_spec(
diff --git a/pydantic_ai_slim/pydantic_ai/capabilities/abstract.py b/pydantic_ai_slim/pydantic_ai/capabilities/abstract.py
@@ -73,7 +73,7 @@ class AbstractCapability(ABC, Generic[AgentDepsT]):
 
     [`get_serialization_name`][pydantic_ai.capabilities.AbstractCapability.get_serialization_name]
     and [`from_spec`][pydantic_ai.capabilities.AbstractCapability.from_spec] support
-    YAML/JSON specs (via [`Agent.from_spec`][pydantic_ai.Agent.from_spec]); they have
+    YAML/JSON specs (via [`Agent.from_spec`][pydantic_ai.agent.Agent.from_spec]); they have
     sensible defaults and typically don't need to be overridden.
     """
 
@@ -113,7 +113,7 @@ def get_instructions(self) -> AgentInstructions[AgentDepsT] | None:
         This method is called once at agent construction time. To get dynamic
         per-request behavior, return a callable that receives
         [`RunContext`][pydantic_ai.tools.RunContext] or a
-        [`TemplateStr`][pydantic_ai.TemplateStr] — not a dynamic string.
+        [`TemplateStr`][pydantic_ai._template.TemplateStr] — not a dynamic string.
         """
         return None
 
@@ -272,10 +272,10 @@ async def wrap_node_run(
         the returned next node, call `handler` multiple times (retry), or
         return a different node to redirect graph progression.
 
-        Note: this hook fires when using [`agent.run()`][pydantic_ai.Agent.run],
-        [`agent.run_stream()`][pydantic_ai.Agent.run_stream], and when manually driving
-        an [`agent.iter()`][pydantic_ai.Agent.iter] run with
-        [`next()`][pydantic_ai.result.AgentRun.next], but it does **not** fire when
+        Note: this hook fires when using [`agent.run()`][pydantic_ai.agent.AbstractAgent.run],
+        [`agent.run_stream()`][pydantic_ai.agent.AbstractAgent.run_stream], and when manually driving
+        an [`agent.iter()`][pydantic_ai.agent.Agent.iter] run with
+        [`next()`][pydantic_ai.run.AgentRun.next], but it does **not** fire when
         iterating over the run with bare `async for` (which yields stream events, not
         node results).
 
@@ -419,7 +419,7 @@ async def on_tool_validate_error(
 
         This is the error counterpart to
         [`after_tool_validate`][pydantic_ai.capabilities.AbstractCapability.after_tool_validate].
-        Fires for [`ValidationError`][pydantic.ValidationError] (schema mismatch) and
+        Fires for `ValidationError` (schema mismatch) and
         [`ModelRetry`][pydantic_ai.exceptions.ModelRetry] (custom validator rejection).
 
         **Raise** the original `error` (or a different exception) to propagate it.
diff --git a/pydantic_ai_slim/pydantic_ai/capabilities/builtin_tool.py b/pydantic_ai_slim/pydantic_ai/capabilities/builtin_tool.py
@@ -22,7 +22,7 @@ class BuiltinTool(AbstractCapability[AgentDepsT]):
     [`AbstractBuiltinTool`][pydantic_ai.builtin_tools.AbstractBuiltinTool] instance or a callable
     that dynamically produces one.
 
-    When `builtin_tools` is passed to [`Agent.__init__`][pydantic_ai.Agent.__init__], each item is
+    When `builtin_tools` is passed to [`Agent.__init__`][pydantic_ai.agent.Agent.__init__], each item is
     automatically wrapped in a `BuiltinTool` capability.
     """
 
diff --git a/pydantic_ai_slim/pydantic_ai/mcp.py b/pydantic_ai_slim/pydantic_ai/mcp.py
@@ -339,7 +339,7 @@ class MCPServer(AbstractToolset[Any], ABC):
 
     When enabled (default), tools are fetched once and cached until either:
     - The server sends a `notifications/tools/list_changed` notification
-    - [`MCPServer.__aexit__`][pydantic_ai.mcp.MCPServer.__aexit__] is called (when the last context exits)
+    - `MCPServer.__aexit__` is called (when the last context exits)
 
     Set to `False` for servers that change tools dynamically without sending notifications.
 
@@ -354,7 +354,7 @@ class MCPServer(AbstractToolset[Any], ABC):
 
     When enabled (default), resources are fetched once and cached until either:
     - The server sends a `notifications/resources/list_changed` notification
-    - [`MCPServer.__aexit__`][pydantic_ai.mcp.MCPServer.__aexit__] is called (when the last context exits)
+    - `MCPServer.__aexit__` is called (when the last context exits)
 
     Set to `False` for servers that change resources dynamically without sending notifications.
     """
