Building Modular AI Agent Features with Pydantic AI Capabilities

Blessed Josiah — Sun, 14 Jun 2026 08:30:00 +0000

If you're building AI Agents with Pydantic AI, understanding Capabilities is invaluable - it's the recommended way to add modular, reusable features to your agents.

This tutorial is part of my ongoing Pydantic AI series on YouTube, where I build a full no-code AI agent platform from scratch.

What is a Capability?

A capability in Pydantic AI is a modular unit of behavior that can be passed to an AI agent.

A capability can give your agent:

Custom toolsets
Instructions
Model settings
Lifecycle hooks

Think of it as a plug-and-play feature module - build it once, attach it to any agent.

How to Create a Capability

Capabilities are created using the Capability or AbstractCapability class:

from pydantic_ai.capabilities import AbstractCapability

Using AbstractCapability gives you full control over instructions, tools, and behavior. It's Pydantic AI's recommended pattern if you're building a library or platform on top of the framework.

Example: A Research Capability

In this tutorial, I build a Research Capability powered by the Tavily Search API, and an Email Capability powered by Resend.

Here's the research capability:

from pydantic_ai import FunctionToolset
from pydantic_ai.capabilities import AbstractCapability
from dataclasses import dataclass
from pydantic_ai.common_tools.tavily import tavily_search_tool
from settings import settings


@dataclass
class ResearchCapability(AbstractCapability):
    def get_instructions(self):
        return "You can use the Tavily search tool for research"

    def get_toolset(self):
        toolset = FunctionToolset()
        toolset.add_tool(tavily_search_tool(api_key=settings.tavily_api_key))
        return toolset

That's it - get_instructions() tells the agent what it can do, and get_toolset() gives it the tools to do it. Attach this to any agent, and it instantly gains web research abilities.

Going Further: RAG + GraphRAG

I also built a Company Knowledge Capability that combines:

pgvector for semantic search over your own data
Neo4j + Graphiti for knowledge graph retrieval (GraphRAG)

This lets an agent answer questions from your company's documents, website content, or any knowledge base with both vector search and relationship-aware graph queries.

Watch the Full Tutorial

This post covers the concept — the full video walks through building both capabilities live, plus the RAG/GraphRAG ingestion pipeline, observability with Logfire, and wiring it all into a working agent.

🎥 Watch on YouTube →
💻 Full source code →