• Closes #

Checklist

• Any AI generated code has been reviewed line-by-line by the human PR author, who stands by it.
• No breaking changes in accordance with the version policy.
• PR title is fit for the release changelog.

Summary

Adds support for dynamic capabilities — a function that takes a RunContext and returns a capability — passed alongside static capabilities in the Agent(capabilities=[...]) or agent.run(capabilities=[...]) argument. Mirrors the existing dynamic-toolset pattern (Agent(toolsets=[fn])).

from pydantic_ai import Agent, RunContext
from pydantic_ai.capabilities import AbstractCapability


@dataclass
class Skill(AbstractCapability[str]):
    """Per-user skill loaded from a database at run time."""

    name: str

    def get_instructions(self) -> str:
        return f'You can use the {self.name} skill.'


SKILLS = {
    'alice': Skill(name='refunds'),
    'bob': Skill(name='lookup'),
}


def user_skill(ctx: RunContext[str]) -> AbstractCapability[str] | None:
    return SKILLS.get(ctx.deps)


agent = Agent('openai:gpt-5.2', deps_type=str, capabilities=[user_skill])

The factory is invoked once per run via for_run. The resolved capability's instructions, model settings, toolset, builtin tools, and hooks all flow through normally — no bespoke handling at every step of the agent loop, since for_run resolution + the existing CombinedCapability.for_run recursion already handles the swap.

Motivating use case: per-user skills loaded from a database (the Jack Collins champion call) — the agent receives a user_id via deps, the dynamic capability factory looks up the user's skills, and contributes their per-user instructions for the run. Same pattern also fits multi-tenant agents, feature-flagged capabilities, A/B-tested capabilities, and admin-vs-regular scoping.

What's added

• pydantic_ai.capabilities.DynamicCapability(capability_func) — wraps a CapabilityFunc so it can sit alongside static capabilities in the agent's tree. Exported from pydantic_ai.capabilities.
• pydantic_ai.capabilities.CapabilityFunc — sync/async type alias (RunContext) -> AbstractCapability | None.
• pydantic_ai.capabilities.AgentCapability = Union[AbstractCapability, CapabilityFunc] — item type for the capabilities= lists. Bare callables get auto-wrapped in DynamicCapability.
• All capabilities= parameters (Agent ctor + run/iter overloads in Agent, AbstractAgent, WrapperAgent, TemporalAgent, DBOSAgent, PrefectAgent) widened from Sequence[AbstractCapability] to Sequence[AgentCapability].

Durable execution

A dynamic capability whose resolved capability contributes only instructions, model settings, builtin tools, hooks, or prepare_tools/get_wrapper_toolset (i.e. no get_toolset()) works seamlessly with Temporal/DBOS/Prefect today — the factory runs in the workflow alongside the rest of the agent loop. Covers the Jack-Collins skills-from-DB pattern.

Dynamic capabilities that contribute their own toolset via get_toolset() are not yet supported with durable execution: the toolset is only known at run time and bypasses the durable wrapper's construction-time toolset registration. Documented in docs/capabilities.md. Tracked in a follow-on issue (will reference once created), to land on top of #4977 (TemporalDurability/DBOSDurability/PrefectDurability capabilities) and the planned capability id / get_description PR.

A prototype Temporal interop landed earlier in this PR's history and was reverted after the design discussion concluded the work belongs inside TemporalDurability.for_agent() (the new capability-based path), not on the legacy wrapper-agent path. The issue captures the design and code that's ready to port.

Test plan

• 12 new tests in tests/test_capabilities.py covering: factory called per-run with RunContext; sync vs async factories; factory returning None (no contribution); contributing instructions/toolset/hooks/builtin_tools dynamically; called once per run not per step; returning a CombinedCapability; passed via agent.run(capabilities=[...]); composition with static capabilities; per-run isolation across concurrent runs; constructor wraps bare callables.
• Doc example in docs/capabilities.md runs as part of tests/test_examples.py.
• Full agent / capabilities / toolsets / temporal / dbos / prefect / examples test suites pass (1734+ tests).
• No type-check regressions (pyright clean across changed files).