On-Demand Capabilities
A capability is a bundle of instructions and/or tools, optionally with settings and hooks. A multi-workflow agent normally sends every workflow’s instructions and tool schemas on every turn, and applies every workflow’s settings and hooks for the whole run — even though most requests need just one workflow. That cost grows with each workflow you add: more input tokens, and worse tool selection once the visible tool set passes the ~30–50-tool mark where models start picking the wrong one (the same pressure behind tool search).
Mark a capability with defer_loading=True and give it a stable id, and it becomes an on-demand capability, also called a deferred capability: it collapses to a one-line catalog entry — its id plus an optional description — that the model pulls in on demand. Its instructions and tools stay hidden until the model loads it, which gives you progressive disclosure of tools as well as instructions. (Deferred capabilities are unrelated to deferred tools, which pause individual tool calls for approval or external execution.) The minimal setup is:
from pydantic_ai import Agent
from pydantic_ai.capabilities import Capability
refunds = Capability(
id='refunds',
description='Use for refund eligibility, refund status, or processing a refund.',
instructions='Always confirm the order ID before issuing a refund.',
defer_loading=True,
)
@refunds.tool_plain
def refund_status(order_id: str) -> str:
"""Look up the refund status for an order."""
return f'Order {order_id}: refund issued on 2026-05-01.'
agent = Agent(
'openai-responses:gpt-6.1-sol',
instructions='You are a customer support assistant.',
capabilities=[refunds],
)
On the first turn, the refund workflow is collapsed to a catalog entry. The model sees its base instructions, the framework-managed load_capability tool, and the catalog appended to the instructions:
<pyai:context id="capability:deferred_capabilities">
The following capabilities are deferred and can be loaded using the `load_capability` tool. A capability's tools stay hidden until it is loaded:
- refunds: Use for refund eligibility, refund status, or processing a refund.
</pyai:context>
A later <pyai:context> element with the same id replaces the earlier one and stays in effect until replaced again.
The catalog is tagged so that when it changes between runs of a conversation, for example because a capability was added, the change is appended instead of rewriting the cached prompt.
The model does not receive the refund instructions or the refund_status tool definition yet, so it has no reason to call the tool. Depending on the active model, Pydantic AI may also send provider/tool-search plumbing to preserve the hidden state; that plumbing does not expose the refund tool definition until the capability is loaded. The exchange unfolds across model requests within a single agent.run_sync call:
- Request 1. The model sees the catalog above and the user’s prompt. It calls the
load_capabilitytool withid='refunds'. - Load. The tool result only confirms the load. Pydantic AI then states the capability’s instructions — “Always confirm the order ID before issuing a refund.” — right after it, in a system message, and exposes the
refund_statusdefinition on the next request. - Request 2. The model now sees those instructions in history and
refund_statusin its tool list. It callsrefund_status(order_id='ABC-123')and answers the user from the result.
If the capability’s instructions change after it loads — a dynamic @refunds.instructions function returns something new, or the instructions in code are edited between runs of a conversation — the change is appended to message history as an update for the block capability:refunds, holding the capability’s complete instructions, or a diff against the text the model last received when that’s shorter. The earlier statement isn’t rewritten, so the cached prompt is kept. A capability whose instructions become empty, or that the agent no longer has, is withdrawn the same way. A before_model_request hook that leaves a loaded capability’s parts out of instruction_parts doesn’t affect it: the instructions are delivered as they resolved, changes included. To withdraw the block, keep its parts with empty content. Every loaded capability’s changes are tracked, whatever the on_change policy of its instructions: a loaded capability’s instructions are never in the prefix, so there is nothing to rewrite. An instruction function that returns something different on every request, such as the current time, appends an update to every request.
Already-loaded capabilities stay loaded for the rest of the run — the model never needs to re-open one. A load_capability tool call for a capability that is already active is answered with a successful result confirming it is already active, and its instructions aren’t stated again; a call for one that an earlier call in the same response already loads is answered with a retry prompt. A call with an id that isn’t an on-demand capability is answered with a retry prompt listing the ids the model can load.
Searching cannot reveal a capability-owned tool: it stays hidden until its capability loads. In runs that also have searchable deferred tools, the catalog explicitly steers the model to load the capability rather than search for its tools; in capability-only runs — where no search surface exists — the catalog omits any mention of searching.
Loading activates the whole bundle, not just instructions: the capability’s function tools, model settings, and lifecycle hooks come live together (see What you can defer). It’s a one-line change to a capability you already register, it works on every provider, and it survives history replay.
Skills on steroids: on-demand capabilities in Pydantic AI on the Pydantic blog walks through the pattern and its token savings.
Every part of a capability bundle activates together as a single unit:
| Part | Before load | After load |
|---|---|---|
| Instructions (static or dynamic) | Not sent | Stated in a system message after the load_capability tool result; included in subsequent requests |
| Function tools | Not exposed | Exposed on the next request |
| Model settings (static or per-step) | Not applied | Merged into the run’s settings for subsequent requests |
| Lifecycle hooks | Do not fire | Fire after the capability is loaded |
| Native tools | Not exposed | Exposed on the next request — see Cache implications |
Reach for on-demand capabilities when:
- the agent serves multiple distinct workflows (refunds, returns, fraud review, account security…) where most turns need one
- a workflow needs more than instructions — its own tools, raised reasoning effort, an approval hook — and those should travel together as a unit
- you want skills-style progressive disclosure but also want the loaded bundle to bring tools and settings, not just a runbook
Skip it when:
- the capability is used on most turns — the discovery round-trip costs more than the tokens it saves
- you have a flat catalog of individually-discoverable tools with no shared instructions — use tool search instead, which discovers individual tools by name rather than loading bundles
If you’ve used Anthropic’s Agent Skills, this is the same idea generalised: a skill is a markdown file the model can pull in on demand. An on-demand capability does that plus typed function tools, per-step model settings, and lifecycle hooks.
defer_loading=True is not specific to the Capability convenience class. The shared fields live on AbstractCapability, and built-in capabilities expose id, description, and defer_loading on construction. For custom capabilities, set those attributes on the instance.
from pydantic_ai import Agent
from pydantic_ai.capabilities import MCP
agent = Agent(
'openai-responses:gpt-6.1-sol',
capabilities=[
MCP(
url='https://mcp.example.com/analytics',
native=True,
id='analytics-mcp',
description='Use for analytics queries, dashboards, and metric lookups.',
defer_loading=True,
),
],
)
Until the model loads analytics-mcp, none of the MCP server’s tool definitions enter the prompt. The same flag works on WebSearch, WebFetch, Hooks, and any custom AbstractCapability subclass — see Building custom capabilities for adding defer_loading to your own subclass.
To load existing capabilities together, wrap them in a CombinedCapability with its own id:
from pydantic_ai import Agent
from pydantic_ai.capabilities import CombinedCapability, WebFetch, WebSearch
web_research = CombinedCapability(
[WebSearch(), WebFetch()],
id='web-research',
description='Use when the question requires up-to-date information from the web.',
defer_loading=True,
)
agent = Agent('anthropic:claude-sonnet-5-5', capabilities=[web_research])
Loading web-research activates the tools, instructions, and hooks of both capabilities at once. Each capability keeps its own ordering position among the agent’s capabilities, as if it were passed to the agent directly. The capabilities inside the group can’t be deferred themselves: pass a capability to the agent separately if the model should load it on its own.
Loaded-capability and tool-availability state live in message history, not in the agent. When a conversation is persisted to a database and resumed later — possibly on a different process, machine, or model — Pydantic AI reconstructs the loaded capability IDs from each load’s record, and the revealed tool names from ToolAvailabilityDeltaPart. A load’s record is the model’s exchange, or else a delta: when the model loads a capability, its load_capability call and return are the record, as with tool search; a load from code, which has no exchange, records a CapabilityLoadDeltaPart instead. Capabilities the model loaded earlier stay loaded; capabilities it never loaded stay collapsed in the catalog. No re-discovery round-trip on resume.
This is why deferred capabilities require a stable explicit id: history replay matches calls to capabilities by id, so a class-derived id would silently break the moment a class is renamed. The same property makes cross-provider replay work — a run that loaded refunds on Anthropic and continued on OpenAI Responses keeps refunds loaded after the switch.
History carries which capability ids were loaded, not the capabilities themselves: the resuming agent must be constructed with the same capabilities (matching ids), just as it must be constructed with the same tools. State lives in history; definitions live in code.
Several RunContext fields expose progressive-disclosure state to tools, hooks, and capability-owned callbacks:
ctx.loaded_capability_ids— deferred capability IDs explicitly loaded, by the model through theload_capabilitytool or by your code throughctx.load_capability(), reconstructed from message history before each model request. A capability the model or a tool loads during a step appears from the next step onwards, which is also the first step on which its instructions and tools reach the model. One loaded from abefore_runorbefore_model_requesthook appears once that step’s hooks have run, so the step’s tool calls andafter_model_requestsee it.ctx.active_capability_ids— the currently-live capability IDs: always-on capabilities plusctx.loaded_capability_ids.ctx.capability_active— only meaningful while Pydantic AI is running a capability-owned hook or callback. It is scoped to that capability; deferred hooks and callbacks are skipped until this value would be true. Active, not loaded: an always-on capability’s hooks readTruealthough nothing ever loaded it.ctx.discovered_tool_names— deferred function tools revealed by durable history, whether through tool search,ToolReturn.tools, or a capability load.ctx.available_tool_names— function tool names currently known as available: always-visible tools from the current step’s assembled tool manager plus names revealed in history. Early hooks such asbefore_runmay see only the history-derived names, or an empty set if none exist yet, before tool definitions have been prepared. See Hook ordering for how hook timing affects what is populated.ctx.is_tool_available(tool)— whether a function tool is currently visible. Wrapping toolsets should pass theToolDefinitionthey hold; model-request hooks and tool execution can pass a name from the currentctx.toolssnapshot.ctx.usage_limits— theUsageLimitsthe run is enforcing (defaulting toUsageLimits()when none were passed, so it’s onlyNoneoutside of a run), alongsidectx.usagefor the usage so far. A capability can read the run’s limits to disclose or adapt to the remaining budget (e.g. budget disclosure) without being configured with a duplicate copy. Treat it as read-only: it’s the live object the run enforces against, so mutating a field would change what the run enforces on subsequent requests.
A load, by the model or from code, takes effect on the model request that follows it: the next one for a load by the model or from a tool, the run’s first for one from before_run, and the one being prepared for one from before_model_request. That’s when the capability’s ID appears in ctx.loaded_capability_ids and ctx.active_capability_ids, and when the loaded bundle’s function tools, native tools, and model settings apply, except that a load from before_model_request only gives the request being prepared its tools and instructions: its native tools, model settings and hooks apply from the next request (see Loading a capability from code).
On-demand capabilities work on every model, and where the provider can express an availability change natively, loading one leaves the prompt prefix intact.
A capability-owned tool is hidden until its capability loads, and it is never searchable — the model reaches it by loading the capability, not by asking for it. The unified rule is that an unrevealed deferred tool stays outside the model’s usable context; each provider’s reveal mechanism determines its wire representation.
- Anthropic
tool_addition_mode='by_reference'references the revealed name in atool_additionblock. A capability-only run pre-advertises the definition withdefer_loading=True; a mixed run with a search surface withholds it, then appends the deferred definition in the same request as the reveal. - OpenAI Responses
tool_addition_mode='with_definitions'carries the full revealed definition in an appendedadditional_toolsinput item and leaves it out oftools. - No provider-native reveal-item support (
tool_addition_mode=None) announcesThe following tool(s) are now available: {names}when the schema is visible. A remote MCP server chooses its own tool names, so a tool whose name contains a framing tag such as</system>is still sent but not named in the announcement. It synthesizes asearch_toolsexchange only when a result must reveal a schema that is still withheld. - Decision models cannot fill a free-form
id, so they offer each capability as a route of their own, described by itsdescription, and leave the catalog out of the framing every question carries. The ids travel onModelRequestParameters.deferred_capabilities, the step’s catalog with each capability’s description and whether it’s active, not on theload_capabilityschema, so what a language model is sent stays the same whichever capabilities a run has.
Add a standalone defer_loading=True tool to the same run and tool search comes back for it, since that one genuinely is searchable. Capability-owned tools stay off the wire entirely while a search surface is present, so search remains fully native — server-executed where the model supports it — and no query can surface a tool whose capability has not loaded.
Calling the load_capability tool reveals capability behavior between requests. Whether that breaks the provider’s prompt-cache prefix depends on what’s revealed:
load_capability returns the loaded capability’s function-tool names through ToolReturn.tools, and the executor records the availability delta beside the tool result. Any user tool can use the same source. Histories that contain a complete capability-load exchange without its delta are translated before the next model request.
| What loads | Cache prefix |
|---|---|
| Instructions only | Stable — instructions land in the message history, not the request prefix, and later changes to them are appended there too. |
Function tools with provider-native reveal-item support (tool_addition_mode='by_reference' or 'with_definitions') | Stable on Anthropic and OpenAI Responses — deferred Anthropic entries are outside its cache key, and OpenAI Responses appends additional_tools without changing tools[]. |
Function tools without provider-native reveal-item support (tool_addition_mode=None, such as OpenAI Chat Completions) | Breaks once per load — the loaded tools are added to tools[], which comes before the messages already sent, so the prefix moves on the request after the load and holds from then on. |
| Native tools | Always breaks the prefix on load — native tool definitions are part of the request prefix on every provider. |
| Function tools that appear without a load (a capability’s dynamic toolset or MCP server adding a tool mid-run) | Stable on first-party OpenAI Responses and on Anthropic models with tool search, with one exception: some of those Anthropic models add a one-time preamble when a run’s first deferred tool is a newcomer, which moves the prefix on that request. Elsewhere the tool is added to tools[]. The change is recorded as an availability delta; see Tools that appear mid-run. |
On OpenAI Responses models before GPT-5.6, a request whose tool_choice names a revealed tool declares it in tools and misses the cache; see Prompt caching implications. With openai_previous_response_id or openai_conversation_id set, the tool stays out of tools and the API rejects the request; see Tool Choice.
When preserving the cache prefix matters, prefer instruction-only or function-tool-only on-demand capabilities on a model that can express an availability change natively. The provider-specific mechanics that keep the prefix stable live in Tool search and prompt caching.
Capability bundles instructions, function tools, and toolsets without subclassing. Register tools with the decorator that mirrors @agent.tool:
from pydantic_ai import RunContext
from pydantic_ai.capabilities import Capability
refunds = Capability(
id='refunds',
description='Use for refund eligibility and refund status.',
instructions='Always confirm the order ID before issuing a refund.',
defer_loading=True,
)
@refunds.tool
def refund_status(ctx: RunContext, order_id: str) -> str:
"""Look up the refund status for an order."""
return f'Order {order_id}: refund issued on 2026-05-01.'
In addition to @capability.tool and @capability.tool_plain, you can pass existing functions or Tool instances via tools=, or hand in one or more toolsets via toolsets=. For dynamic instructions, use the @capability.instructions decorator. For a dynamic catalog entry, pass a callable as description=.
@capability.tool and @capability.tool_plain mirror @agent.tool exactly, including the defer_loading argument. On a deferred capability that per-tool flag is a no-op — the capability gates all its tools as a unit — so it only has an effect on a non-deferred Capability, where it opts an individual tool into tool search discovery. To choose searchable tools in one place instead, use ToolSearch(tools=...); tools a deferred capability gates stay gated either way.
For anything beyond instructions, function tools, toolsets, and descriptions — model settings, hooks, native tools, wrapper toolsets, or custom per-run logic — subclass AbstractCapability directly. When subclassing, override get_description if the catalog entry needs to vary by run.
The Capability example above deferred instructions and a function tool, but the same flag gates the whole bundle — what the model knows, what it can do, and how it does it (see What you can defer). The snippets below show the remaining pieces in turn: model settings, hooks, and native tools.
get_model_settings is collected during capability assembly, but its settings are only applied after the deferred capability is loaded. That means per-step settings like raised reasoning effort only apply for workflows the model opts into:
from dataclasses import dataclass
from typing import Any
from pydantic_ai import Agent, ModelSettings
from pydantic_ai.capabilities import AbstractCapability
@dataclass
class DeepReasoning(AbstractCapability[Any]):
def get_model_settings(self) -> ModelSettings:
return ModelSettings(extra_body={'reasoning_effort': 'high'})
agent = Agent(
'openai-responses:gpt-6.1-sol',
capabilities=[
DeepReasoning(
id='deep-reasoning',
description='Use for multi-step planning or hard analytical problems.',
defer_loading=True,
),
],
)
Hooks can live on deferred capabilities too. They do not run until the capability that owns them is loaded:
from dataclasses import dataclass
from pydantic_ai import Agent
from pydantic_ai.capabilities import AbstractCapability
@dataclass
class AccountSecurityWorkflow(AbstractCapability):
id: str | None = 'account-security'
description: str | None = 'Use when the next action may be destructive.'
defer_loading: bool = True
def get_instructions(self) -> str:
return 'Confirm the customer identity before taking destructive action.'
async def before_tool_execute(self, ctx, *, call, tool_def, args):
# Inspect the call, prompt the operator, raise to block.
return args
agent = Agent('openai-responses:gpt-6.1-sol', capabilities=[AccountSecurityWorkflow()])
Any provider-adaptive capability (WebSearch, WebFetch, MCP, …) can be deferred the same way. The native tool definition only enters the request after the capability is loaded — see Cache implications for the trade-off:
from pydantic_ai import Agent
from pydantic_ai.capabilities import WebSearch
agent = Agent(
'anthropic:claude-sonnet-5-5',
capabilities=[
WebSearch(
local='duckduckgo',
id='web-research',
description='Use when the question requires up-to-date information.',
defer_loading=True,
),
],
)
A realistic on-demand capability rarely consists of just one piece. The example below defines a customer-support agent with two deferred workflows that exercise different parts of the bundle:
orders— instructions plus a function tool, defined inline withCapability.account-security— instructions, a function tool, raised reasoning effort, and an approval hook, all bundled as oneAbstractCapabilitysubclass.
For those workflows, turn 1 exposes only the two-line catalog. Base instructions, always-on tools, the framework-managed load_capability tool, and any provider/tool-search plumbing still appear as usual. Loading account-security activates the runbook, the destructive tool, the higher reasoning effort, and the approval gate together — that’s what we mean by bundle-level disclosure.
from dataclasses import dataclass
from pydantic_ai import Agent, ModelSettings, RunContext
from pydantic_ai.capabilities import AbstractCapability, Capability
from pydantic_ai.toolsets import AgentToolset, FunctionToolset
@dataclass
class Store:
orders: dict[str, str]
# Workflow 1: instructions + function tool, defined inline.
orders = Capability[Store](
id='orders',
description='Use for order tracking, delivery status, or questions involving an order ID.',
instructions='Quote the order ID and item name when discussing an order.',
defer_loading=True,
)
@orders.tool
def order_status(ctx: RunContext[Store], order_id: str) -> str:
"""Look up shipping or delivery status for an order."""
return ctx.deps.orders.get(order_id, f'No order found with id {order_id}.')
# Workflow 2: instructions + tool + per-step model settings + approval hook,
# all hidden until the model loads `account-security`.
security_tools = FunctionToolset[Store]()
@security_tools.tool
def revoke_sessions(ctx: RunContext[Store], account_id: str) -> str:
"""Revoke all active sessions for an account."""
return f'Revoked sessions for {account_id}.'
@dataclass
class AccountSecurity(AbstractCapability[Store]):
id: str | None = 'account-security'
description: str | None = 'Use for suspicious logins, account takeover, or session revocation.'
defer_loading: bool = True
def get_instructions(self) -> str:
return 'Confirm the customer identity before revoking sessions.'
def get_toolset(self) -> AgentToolset[Store]:
return security_tools
def get_model_settings(self) -> ModelSettings:
# Raise reasoning effort just for sensitive workflows.
return ModelSettings(extra_body={'reasoning_effort': 'high'})
async def before_tool_execute(self, ctx, *, call, tool_def, args):
# Approval gate: inspect the call and raise to block, active once the model has loaded `account-security`.
return args
support_agent = Agent(
'openai-responses:gpt-6.1-sol',
deps_type=Store,
instructions='You are a customer-support agent for an e-commerce store.',
capabilities=[orders, AccountSecurity()],
)
A “where is my order?” request loads only orders. A “someone is logging into my account” request loads only account-security — and from that point on, every tool call in the run passes through the approval hook and benefits from the raised reasoning effort, without either being visible to the model on requests that never touched the workflow.
Want the model to actually read the runbook before taking a destructive action? Make the runbook a deferred capability, then check ctx.loaded_capability_ids in a one-method hook:
from dataclasses import dataclass, field
from pydantic_ai import Agent, ModelRetry
from pydantic_ai.capabilities import AbstractCapability, Capability
@dataclass
class RunbookRequired(AbstractCapability):
"""Bounces a tool call back until the matching runbook has been loaded."""
requirements: dict[str, str] = field(default_factory=dict)
async def before_tool_execute(self, ctx, *, call, tool_def, args):
required = self.requirements.get(tool_def.name)
if required and required not in ctx.loaded_capability_ids:
raise ModelRetry(
f'Call the `load_capability` tool with `id={required!r}` and follow its '
f'guidance before calling `{tool_def.name}`.'
)
return args
refund_policy = Capability(
id='refund-policy',
description='Read before issuing refunds. Eligibility rules and approval limits.',
instructions=(
'Refunds over $500 require manager approval. '
'Refunds outside the 30-day window require a documented exception.'
),
defer_loading=True,
)
agent = Agent(
'openai-responses:gpt-6.1-sol',
capabilities=[
refund_policy,
RunbookRequired(requirements={'issue_refund': 'refund-policy'}),
],
)
@agent.tool_plain
def issue_refund(order_id: str, amount: float) -> str:
"""Issue a refund for an order."""
return f'Refund of ${amount} issued for {order_id}.'
The model sees issue_refund from turn 1. If it tries to call it before opening refund-policy, the hook bounces the call back with a message pointing at the exact load_capability tool call to make. The model loads the policy, the policy text lands in its recent context, and the refund runs within the rules — and only then. The same pattern works for any tool-and-runbook pair.
Because the loaded set is just runtime data on RunContext, the pattern generalises: dynamic instructions can warn when a risky pair of workflows is open, audit hooks can tag traces with the loaded set, escalation hooks can require an extra confirmation when both payments and account-security are active.
The model normally decides when to load an on-demand capability, but sometimes your code knows first: a tool has just classified the request, or the ticket you’re handling says which workflow applies. Instead of waiting for the model to call the load_capability tool, call ctx.load_capability(), passing the capability’s id or the capability instance. It works whenever a model request follows: from a tool, sync or async, or a tool hook such as after_tool_execute; from a before_run or before_model_request capability hook; and from after_model_request on a response with tool calls the run executes. It’s a plain method, not a coroutine:
from dataclasses import dataclass
from pydantic_ai import Agent, RunContext, ToolCallPart, ToolReturnPart
from pydantic_ai.capabilities import Capability
from pydantic_ai.messages import ModelMessage, ModelResponse, TextPart
from pydantic_ai.models.function import AgentInfo, FunctionModel
@dataclass
class Ticket:
order_id: str
category: str
refunds = Capability[Ticket](
id='refunds',
description='Use for refund eligibility, refund status, or processing a refund.',
instructions='Always confirm the order ID before issuing a refund.',
defer_loading=True,
)
@refunds.tool_plain
def refund_status(order_id: str) -> str:
"""Look up the refund status for an order."""
return f'Order {order_id}: refund issued on 2026-05-01.'
def model_fn(messages: list[ModelMessage], info: AgentInfo) -> ModelResponse:
# Stands in for an LLM: open the ticket, check the refund once that tool is available, then answer.
last_part = messages[-1].parts[-1]
if isinstance(last_part, ToolReturnPart) and last_part.tool_name == 'refund_status':
return ModelResponse(parts=[TextPart(last_part.model_response_str())])
if any(tool.name == 'refund_status' for tool in info.function_tools):
return ModelResponse(parts=[ToolCallPart('refund_status', {'order_id': 'ABC-123'})])
return ModelResponse(parts=[ToolCallPart('open_ticket', {})])
agent = Agent(FunctionModel(model_fn), deps_type=Ticket, capabilities=[refunds])
@agent.tool
async def open_ticket(ctx: RunContext[Ticket]) -> str:
"""Open the customer's support ticket."""
if ctx.deps.category == 'refund':
ctx.load_capability(refunds)
return f'Ticket for order {ctx.deps.order_id} opened.'
result = agent.run_sync('Where is my refund?', deps=Ticket(order_id='ABC-123', category='refund'))
print(result.output)
#> Order ABC-123: refund issued on 2026-05-01.
open_ticket loads refunds because the ticket is about a refund, so on its next request the model sees the refund instructions and can call refund_status without calling the load_capability tool first.
How a load from code behaves:
- It takes effect on the model request that follows. That request states the capability’s instructions in a system message, as after the model’s own load, and its tools, model settings, and hooks are active from then on. From a tool or tool hook, or from
after_model_requeston a response with tool calls, that’s the next request, and the load is recorded after the tool results. Frombefore_run, it’s the run’s first request, so the model has the capability from the start without an extra turn. Frombefore_model_request, the request being prepared gets the capability’s tools and instructions, but its model settings, native tools and hooks were resolved before the hook ran, so they apply from the next request. - It never causes a model request. The load rides along with the run’s next model request, so if a tool’s step ends the run instead (because a tool call needs approval or is deferred, or the run produces its output), the load is discarded. Resuming the run doesn’t run that tool again, so to have the capability after an approval, load it from the tool that needed approval or from a tool hook such as
after_tool_execute, which run when the run resumes. A load made by a tool attempt that then raisesModelRetrystill counts. - It’s recorded in message history without a
load_capabilitycall: the request it takes effect on gets aCapabilityLoadDeltaPartnaming the capability inloadedand the tool call that loaded it, if any, intool_call_id, followed by theToolAvailabilityDeltaPartrevealing its tools that the model’sload_capabilitycall also leaves after its result, if the capability has tools. The model never sees theCapabilityLoadDeltaPartitself, only the capability’s instructions and tools. So it works whether or not the request has aload_capabilitytool, survives resuming the conversation, and appears inctx.loaded_capability_idsfrom the next step. Loads made before the same model request, including from parallel tool calls, each get their own record, in the order they were made. Content the tool enqueues withctx.enqueue()goes right after its result, ahead of the records. - Older versions and compaction: Pydantic AI versions without
CapabilityLoadDeltaPartcan’t load a history that contains one. Like any load, a load from code ends at a compaction that removes its record. Pydantic AI Harness’s compaction strategies record every load they remove again right after the summary (or ahead of the kept messages), the model’s and code’s alike, as aCapabilityLoadDeltaPart(details). - It loads a capability once. It returns
Trueif it queued the load, andFalseif the capability is already active or already being loaded: by an earlierctx.load_capability()call, including one from a parallel tool call, or by the model’s ownload_capabilitycall in the same response. In that last case, the capability only loads if the model’s call succeeds.
ctx.load_capability() raises a UserError if the capability isn’t registered in the run, if it’s a non-deferred member of a deferred group that isn’t loaded yet (load the group instead), if it’s called where no model request follows (from after_model_request on a response without tool calls, or only an output tool’s, or from an after_node_run or after_run hook, for example), or if it’s called from an output tool, including an output function, which ends the run.
ctx.load_capability() isn’t supported in a realtime session either: it raises a UserError, which ends the session like any other UserError a session tool raises. The model can still load an instructions-only on-demand capability there with the load_capability tool.
When a durable execution engine runs a tool in its own activity, step, or task, it replays the tool’s recorded result on recovery without re-running your code, so a load made there would be lost. Where Pydantic AI can detect this, ctx.load_capability() raises a UserError instead:
- Temporal runs tool functions in activities, so they can’t load capabilities.
- Prefect runs tool functions in tasks, so they can’t load capabilities.
- DBOS runs plain function tools in workflow code, so they can load capabilities. Tools from MCP servers and dynamic toolsets run in steps and can’t. Don’t load from a function you decorated with
@DBOS.stepeither: Pydantic AI can’t detect that case, so the load succeeds but is lost when DBOS recovers the workflow.
Capability hooks run in workflow or flow code on all three engines, so loading from before_run, before_model_request, or after_model_request works there. So do tool hooks, which run around the activity, step, or task that runs the tool, so load from a hook such as after_tool_execute when the tool itself can’t:
from typing import Any
from pydantic_ai import RunContext, ToolCallPart, ToolDefinition
from pydantic_ai.capabilities import Hooks
hooks = Hooks()
@hooks.on.after_tool_execute
async def load_refunds(
ctx: RunContext, *, call: ToolCallPart, tool_def: ToolDefinition, args: dict[str, Any], result: Any
) -> Any:
if tool_def.name == 'open_ticket':
ctx.load_capability('refunds')
return result
Register hooks on the agent alongside the refunds capability. The hook runs for every tool call, including the model’s own load_capability calls, so check which tool it’s handling.
If you already keep your skills as Markdown files with YAML frontmatter — the format used by Anthropic Agent Skills — you can wrap each one in a Capability with a few lines of glue.
Given a skill file skills/refunds.md:
---
id: refunds
description: Use for refund eligibility, refund status, or processing a refund.
---
Always confirm the order ID before issuing a refund.
Never issue refunds over $500 without manager approval.
Load it into an agent as an on-demand capability:
from pathlib import Path
import yaml
from pydantic_ai import Agent
from pydantic_ai.capabilities import Capability
def load_skill(path: Path) -> Capability:
_, frontmatter, body = path.read_text(encoding='utf-8').split('---', 2)
meta = yaml.safe_load(frontmatter)
return Capability(
id=meta['id'],
description=meta['description'],
instructions=body.strip(),
defer_loading=True,
)
agent = Agent(
'openai-responses:gpt-6.1-sol',
instructions='You are a customer support assistant.',
capabilities=[load_skill(p) for p in Path('skills').glob('*.md')],
)
Each file shows up in the model’s catalog as its id plus description; the body is only sent once the model calls the load_capability tool. To give a skill its own tools, pass them to the same Capability — see Hide a skill’s tools until the skill is loaded. For model settings or hooks, subclass AbstractCapability as in the examples above.
A skill often comes with tools the model should only see once it has read the skill’s instructions. Capability takes toolsets= and tools=, so you can attach an existing toolset or functions to a Markdown-defined skill without subclassing. With defer_loading=True, those tools stay out of the model’s tool list until it loads the skill with the load_capability tool, and arrive on the next request, recorded in history as a ToolAvailabilityDeltaPart.
The example below inlines the skill file as a string to stay self-contained; read it from disk as in Loading skills from Markdown files. A FunctionModel stands in for a real model: it records the tools offered on each request, loads the skill, and calls the skill’s tool.
import yaml
from pydantic_ai import Agent, FunctionToolset
from pydantic_ai.capabilities import Capability
from pydantic_ai.messages import ModelMessage, ModelResponse, TextPart, ToolCallPart
from pydantic_ai.models.function import AgentInfo, FunctionModel
from pydantic_ai.toolsets import AgentToolset
RELEASE_SKILL = """\
---
id: release
description: Use to cut, stage, and verify a release.
---
Stage the release and check the staged build before calling it ready.
"""
release_toolset = FunctionToolset()
@release_toolset.tool_plain
def stage_release(version: str) -> str:
"""Build a release and stage it for verification."""
return f'Release {version} staged.'
def skill_capability(markdown: str, toolsets: list[AgentToolset]) -> Capability:
_, frontmatter, body = markdown.split('---', 2)
meta = yaml.safe_load(frontmatter)
return Capability(
id=meta['id'],
description=meta['description'],
instructions=body.strip(),
toolsets=toolsets, # hidden until the model loads `release`
defer_loading=True,
)
release = skill_capability(RELEASE_SKILL, toolsets=[release_toolset])
tools_per_request: list[list[str]] = []
def scripted_model(messages: list[ModelMessage], info: AgentInfo) -> ModelResponse:
tools_per_request.append([tool.name for tool in info.function_tools])
if len(tools_per_request) == 1:
return ModelResponse(parts=[ToolCallPart('load_capability', {'id': 'release'})])
if len(tools_per_request) == 2:
return ModelResponse(parts=[ToolCallPart('stage_release', {'version': '1.4.0'})])
return ModelResponse(parts=[TextPart('Release 1.4.0 is staged.')])
agent = Agent(FunctionModel(scripted_model), capabilities=[release])
result = agent.run_sync('Stage release 1.4.0.')
print(result.output)
#> Release 1.4.0 is staged.
for request, tools in enumerate(tools_per_request, start=1):
print(f'Request {request}: {tools}')
#> Request 1: ['load_capability']
#> Request 2: ['load_capability', 'stage_release']
#> Request 3: ['load_capability', 'stage_release']
On request 1 the model sees only load_capability, with release in the catalog. Once it loads the skill, the skill’s instructions follow the tool result and stage_release is in its tool list from request 2 on. Pass functions or Tool instances via tools= the same way.
This gates the skill’s tools as a bundle. To let the model find individual tools in a large flat catalog by keyword instead, use tool search; a capability’s tools are never searchable before it loads. If you load Agent Skills with the Pydantic AI Harness Skills capability, which delivers instructions only, define a skill that needs tools this way instead. Both share one catalog and the load_capability tool.
If your team keeps runbooks in a database rather than in files, make each runbook a deferred Capability and read its body in an instructions function registered with @capability.instructions. The function receives the RunContext, so it can query the database connection you pass as deps.
The example below builds the catalog from the runbooks table when the agent is created, so every run sends the same catalog and it stays in the cached prefix; a runbook added to the table appears once the agent is rebuilt. The body of a runbook is read only after the model loads it, and again on each later request of the run, so an edited runbook reaches the next run without a redeploy. An edit made after the model loaded the runbook is appended to the conversation as an update. Like any loaded capability’s instructions, a runbook’s body is stated in the system voice, so anyone who can write to the table can instruct the model with your authority: limit write access to people you would let edit your agent’s instructions.
An in-memory SQLite database stands in for yours, the instructions function prints each runbook it reads, and a FunctionModel stands in for a real model that loads the db-failover runbook:
import sqlite3
from dataclasses import dataclass
from pydantic_ai import Agent, RunContext
from pydantic_ai.capabilities import Capability
from pydantic_ai.messages import ModelMessage, ModelResponse, TextPart, ToolCallPart
from pydantic_ai.models.function import AgentInfo, FunctionModel
@dataclass
class Deps:
db: sqlite3.Connection
def runbook(runbook_id: str, description: str) -> Capability[Deps]:
capability = Capability[Deps](id=runbook_id, description=description, defer_loading=True)
@capability.instructions
def body(ctx: RunContext[Deps]) -> str | None:
print(f'Reading runbook {runbook_id!r}')
#> Reading runbook 'db-failover'
row = ctx.deps.db.execute('SELECT body FROM runbooks WHERE id = ?', (runbook_id,)).fetchone()
return row[0] if row else None # a deleted runbook withdraws its instructions
return capability
# A sync instructions function runs in a worker thread, so share the connection across threads.
db = sqlite3.connect(':memory:', check_same_thread=False)
db.execute('CREATE TABLE runbooks (id TEXT PRIMARY KEY, description TEXT, body TEXT)')
db.executemany(
'INSERT INTO runbooks VALUES (?, ?, ?)',
[
(
'db-failover',
'Use when the primary database is down or unreachable.',
'Page the on-call DBA, then promote the replica with the lowest replication lag.',
),
(
'cert-renewal',
'Use when a TLS certificate is about to expire.',
'Renew the certificate through the internal CA and roll the load balancers.',
),
],
)
runbooks = [
runbook(runbook_id, description)
for runbook_id, description in db.execute('SELECT id, description FROM runbooks')
]
def scripted_model(messages: list[ModelMessage], info: AgentInfo) -> ModelResponse:
if len(messages) == 1:
return ModelResponse(parts=[ToolCallPart('load_capability', {'id': 'db-failover'})])
return ModelResponse(parts=[TextPart('Paging the on-call DBA.')])
agent = Agent(FunctionModel(scripted_model), deps_type=Deps, capabilities=runbooks)
result = agent.run_sync('The primary database is down.', deps=Deps(db))
print(result.output)
#> Paging the on-call DBA.
db.close()
The first request sends only the catalog, so no runbook body is read. After the model loads db-failover, the second request reads that runbook’s body and sends it to the model; cert-renewal is never read. With an async database driver, make the instructions function async def and await the query.