Building Modular AI Agent Features with Pydantic AI Capabilities

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.

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:

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

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.

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.

I also built a Company Knowledge Capability that combines:

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.

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 →

While you're there, subscribe for more software and AI related content!