Pydantic AI Harness: Enhancing Your AI Agents with Robust Capabilities

Introduction

Pydantic AI Harness, built on Pydantic AI, provides a comprehensive set of "capabilities" to empower your AI agents for complex and long-running tasks. It extends the core Pydantic AI framework by offering advanced functionalities like workspace management, planning, persistent memory, sub-agent delegation, and robust context management.

Important Note: This repository is being merged into Pydantic AI and will be archived. Development for pydantic-ai-harness and pydantic-clai2 now continues within the pydantic/pydantic-ai repository, specifically in src/pydantic_ai_harness and src/pydantic_clai2. Please direct new issues and pull requests to the Pydantic AI repository. The PyPI package names will remain the same, with future releases published from Pydantic AI.

Why Use and Key Benefits

While Pydantic AI provides a lean harness for simple agents, Pydantic AI Harness steps in when agents need to tackle more demanding work, such as fixing a codebase, conducting extensive research, or operating unattended for hours. It ships with a rich set of primitives, each a "capability," a self-contained unit of agent behavior that you can easily add to your agent's configuration.

Key benefits include:

Extended Functionality: Provides essential components like a workspace for agent actions, a dynamic plan, memory that persists across sessions, and sub-agents for task delegation.
Robust Context Management: Ensures agents remain coherent and efficient during long runs with advanced context management and durable execution capabilities.
Modularity and Composability: With over 50 capabilities, you can snap on single blocks, compose your own stacks, or start with complete agents like Coder and Researcher and customize them as needed.
Comprehensive Tooling: Offers a wide array of tools for execution environments (FileSystem, Shell), external system integrations (GitHub, Linear, Notion), web and research (Web Search, Exa Search), reasoning and planning, context management, knowledge and memory, and control and safety.

Installation

Pydantic AI Harness requires Python 3.10 or newer. It installs pydantic-ai-slim automatically, so you don't need to install Pydantic AI separately.

Using uv:

uv add pydantic-ai-harness

Using pip:

pip install pydantic-ai-harness

Model providers and the CLI can be added via extras, for example: pydantic-ai-harness[anthropic] or pydantic-ai-harness[cli]. Some capabilities may also require their own specific extras for optional dependencies.

Examples

Here are a few examples demonstrating how to use Pydantic AI Harness capabilities:

Quick Start with Coder Agent

The Coder capability provides six tools, including read_file, write_file, edit_file, list_files, grep, and shell, plus delegate_task for sub-tasks.

from pydantic_ai import Agent
from pydantic_ai_harness import Coder

agent = Agent('anthropic:claude-fable-5', capabilities=[Coder()])

result = agent.run_sync('Find out why tests/test_parser.py fails and fix the bug it caught.')
print(result.output)
#> Found it: `parse()` returned None on empty input instead of raising. Fixed in src/parser.py; tests pass now.

Enhancing Coder with Web Search and Memory

You can easily combine capabilities to create more powerful agents. Here, a Coder agent is augmented with WebSearch for online lookups and Memory for cross-session persistence.

from pydantic_ai import Agent
from pydantic_ai.capabilities import WebSearch
from pydantic_ai_harness import Coder, Memory
from pydantic_ai_harness.memory import FileStore

agent = Agent(
    'openai:gpt-5.6-sol',
    capabilities=[
        Coder(),
        WebSearch(),  # look up docs and error messages on the web
        Memory(FileStore('.agent-memory')),  # remembers across sessions
    ],
)
# agent.run_sync(...)

Composing a Research Agent from Blocks

Capabilities are modular, allowing you to build custom agents by combining individual components. This example shows how to construct a research agent, similar to the pre-built Researcher capability.

from pydantic_ai import Agent
from pydantic_ai.capabilities import WebFetch, WebSearch
from pydantic_ai_harness import SubAgent, SubAgents, ToolOutputLimits

sub_researcher = SubAgent(
    Agent(
        name='researcher',
        description='Research a focused sub-question on the web and report back with findings and source links',
        capabilities=[WebSearch(local=True), WebFetch(local=True), ToolOutputLimits()],
    )
)

agent = Agent(
    'anthropic:claude-fable-5',
    capabilities=[
        WebSearch(local=True),  # native provider search, DuckDuckGo fallback elsewhere
        WebFetch(local=True),  # read the pages behind the results, native or local
        SubAgents(agents=[sub_researcher], agent_folders=None),
        ToolOutputLimits(),  # fetched pages don't flood the context
    ],
)

result = agent.run_sync('What changed in the top three Python agent frameworks this month? Cite sources.')
print(result.output)
#> ...