Extensibility

Pydantic AI is designed to be extended. Capabilities are the primary extension point — they bundle tools, lifecycle hooks, instructions, and model settings into reusable units that can be shared across agents, packaged as libraries, and loaded from spec files.

Beyond capabilities, Pydantic AI provides several other extension mechanisms for specialized needs.

Capabilities

Capabilities are the recommended way to extend Pydantic AI. They are useful for:

Teams building reusable internal agent components (guardrails, audit logging, authentication)
Package authors shipping extensions that work across models and agents
Community contributors sharing solutions to common problems

See Capabilities for using and building capabilities, and Hooks for the lightweight decorator-based approach.

!!! tip If you want to contribute a capability, open an issue on Pydantic AI Harness rather than on pydantic-ai. Most capabilities belong in the harness -- see What goes where? for the distinction.

Publishing capability packages

To make a capability installable and usable in agent specs:

Implement [get_serialization_name()][pydantic_ai.capabilities.AbstractCapability.get_serialization_name] — defaults to the class name. Return None to opt out of spec support.
Implement [from_spec()][pydantic_ai.capabilities.AbstractCapability.from_spec] — defaults to cls(*args, **kwargs). Override when your constructor takes non-serializable types.
Package naming — use the pydantic-ai- prefix (e.g. pydantic-ai-guardrails) so users can find your package.
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].

python

from pydantic_ai import Agent

from my_package import MyCapability

agent = Agent.from_file('agent.yaml', custom_capability_types=[MyCapability])

See Custom capabilities in specs for implementation details.

Pydantic AI Harness

Pydantic AI Harness is the official capability library for Pydantic AI -- standalone capabilities like memory, guardrails, and context management live there rather than in core. See What goes where? for the full breakdown, or jump to the capability matrix.

Third-party ecosystem

Capabilities

Capabilities are the recommended extension mechanism for packages that need to bundle tools with hooks, instructions, or model settings. See Third-party capabilities for community packages.

Toolsets

Many third-party extensions are available as toolsets, which can also be wrapped as capabilities to take advantage of hooks, instructions, and model settings. See Third-party toolsets for the full list.

Other extension points

Custom toolsets

For specialized tool execution needs (custom transport, tool filtering, execution wrapping), implement [AbstractToolset][pydantic_ai.toolsets.AbstractToolset] or subclass [WrapperToolset][pydantic_ai.toolsets.WrapperToolset]:

[AbstractToolset][pydantic_ai.toolsets.AbstractToolset] — full control over tool definitions and execution
[WrapperToolset][pydantic_ai.toolsets.WrapperToolset] — delegates to a wrapped toolset, override specific methods

See Building a Custom Toolset for details.

!!! tip If your toolset also needs to provide instructions, model settings, or hooks, consider building a custom capability instead.

Custom models

For connecting to model providers not yet supported by Pydantic AI, implement [Model][pydantic_ai.models.Model]:

[Model][pydantic_ai.models.Model] — the base interface for model implementations
[WrapperModel][pydantic_ai.models.wrapper.WrapperModel] — delegates to a wrapped model, useful for adding instrumentation or transformations

See Custom Models for details.

Custom agents

For custom agent behavior, subclass [AbstractAgent][pydantic_ai.agent.AbstractAgent] or [WrapperAgent][pydantic_ai.agent.WrapperAgent]:

[AbstractAgent][pydantic_ai.agent.AbstractAgent] — the base interface for agent implementations, providing run, run_sync, and run_stream
[WrapperAgent][pydantic_ai.agent.WrapperAgent] — delegates to a wrapped agent, useful for adding pre/post-processing or context management