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 →

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