Pydantic AI Harness

Your agent's favorite harness, built on Pydantic AI

Pydantic AI Harness is the official capability and harness library for Pydantic AI. Every Pydantic AI agent already has a light harness: the typed agent loop, any model, your own tools, structured output. For simple agents that's enough. But set an agent loose on complex, long-running work (fix a codebase, research a question, run for hours unattended) and what it needs around the model grows: a workspace to act in, a plan it keeps current, memory that carries across sessions, sub-agents to hand work to, context management that holds up in hour ten, and durable execution that survives a restart. Pydantic AI Harness ships that harness.

Everything here is one primitive: a capability, a self-contained unit of agent behavior you add to capabilities=[...] on any agent. There are 30+ of them, and complete agents like Coder and Researcher are themselves capabilities combined: they come apart the way they went together. Snap on a single block, compose your own stack, or start from the whole coding agent and take it apart later.

Quick start

Install with uv:

uv:

uv add "pydantic-ai-harness[coder,anthropic]"

pip:

pip install "pydantic-ai-harness[coder,anthropic]"

from pydantic_ai import Agent
from pydantic_ai.capabilities import LocalWorkspace
from pydantic_ai_harness.coder import Coder

agent = Agent(
    'anthropic:claude-opus-5-5',
    capabilities=[LocalWorkspace('.'), Coder()],
)
result = agent.run_sync('Find out why tests/test_parser.py fails and fix the bug it caught.')
print(result.output)

LocalWorkspace('.') is where the agent works: its file tools and commands run on your machine, in this directory. It is not a sandbox, so commands can reach anything you can. To run the same agent in an isolated cloud machine, swap it for a sandbox capability (Modal, E2B, or Sprites); see Workspaces.

With Modal, for example:

from pydantic_ai_harness.modal_sandbox import ModalSandbox

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

Coder provides six tools: read_file, write_file, edit_file, list_files, grep, and shell, plus delegate_task to hand a sub-task to a fresh run of the same agent, repository context, and context controls. Shell commands are unrestricted and can persist beyond individual runs. Default instructions guide autonomous investigation, editing, and verification; pass instructions= to add your own guidance.

uvx --with "pydantic-ai-harness[coder]" clai -a pydantic_ai_harness.coder:coder_agent -m anthropic:claude-opus-5-5

The bundled coder_agent is the example above without a model.

Every model works: swap the string for any provider's. Need more? Add capabilities to the list; here's the same coder on gpt-5.6-sol, with web search and cross-session memory:

uv:

uv add "pydantic-ai-slim[openai]"

pip:

pip install "pydantic-ai-slim[openai]"

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

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

Skills (your SKILL.md procedures, loaded on demand; point it at a skills/ directory and add the skills extra), Web Fetch, Guardrails, and Dynamic Workflow slot in the same way; the Coder README lists what pairs well.

No magic: it's capabilities all the way down

Coder is a regular combined capability: FileSystem with five of its tools and content hashes off, Shell with its persistent shell tool and no allowlist, RepoContext, SubAgents delegating to the agent itself, ClearToolResults and WarnNearLimits, and a bounded ToolOutputLimits, plus its default instructions and JSON argument repair. Use it whole, or build the same agent from those capabilities to change any setting; the Coder page lists the exact configuration, tool signatures, delegation, and the persistent shell lifecycle.

Workspaces

A workspace is where the agent's files and commands live: your machine with LocalWorkspace, or an isolated sandbox. Harness capabilities never pick one for you. Attach one, or the run fails at its start and tells you what to attach.

Coder, FileSystem, Shell, Repo Context, and Macroscope work in the run's workspace, starting in its working directory. To work in a subdirectory, set it on the workspace: LocalWorkspace('./repo'). To continue in the same files from a later run or another agent, see Sharing a workspace.

Skills, SubAgents, ToolOutputLimits, and Memory's FileStore use the run's workspace for their own files too. To keep those files on your machine while the agent works in a sandbox, point them at a local location:

from pydantic_ai.workspaces import LocalWorkspaceBackend
from pydantic_ai_harness import Memory, ToolOutputLimits
from pydantic_ai_harness.memory import FileStore
from pydantic_ai_harness.tool_output_limits import LocalFileStore

memory = Memory(FileStore('.', workspace=LocalWorkspaceBackend('/var/lib/myapp/memory')))  # notes on this machine
limits = ToolOutputLimits(store=LocalFileStore())  # spills in this machine's temp directory

By default, harness files (Shell's background job logs, tool-output spills) go in .pydantic-ai-harness/ in the workspace's working directory, which is git-ignored.

Step Persistence's file and SQLite stores, Media's disk and SQLite stores, and Code Mode mounts use paths on the machine running the agent, not the run's workspace.

FileSystem's root_dir limits only the file tools, not Shell commands.

Upgrading from an earlier release? The Coder page lists what changed.

Capabilities

Every capability is a self-contained unit you drop into capabilities=[...], and they all compose, with each other and with your own. Some come with pydantic-ai itself, the rest with this package; the Package column says which. 50+ in all, grouped by what they give your agent:

Harnesses

Complete agent stacks as regular combined capabilities: one import gives you a working agent, and you can take either apart into the blocks below.

Execution environments

The workspace the agent acts in: the files it edits and the commands it runs, local or isolated.

Tools & native abilities

Connections to systems outside the agent's workspace, and abilities the provider executes natively.

Web & research

Finding and reading things on the open web.

Reasoning, planning & delegation

How the agent thinks and divides the work.

Context management

How the agent spends its context window: the difference between an agent that degrades over a long run and one that doesn't, and between paying for tokens N times or once.

Knowledge & memory

What the agent knows and remembers, loaded when relevant instead of carried in every prompt.

Control & safety

Bounding what the agent may do, and keeping it on-instructions.

Self-extension

Execution runtime

Outside the loop: how runs persist, survive failures, and get observed and configured in production.

Core also ships loop-customization capabilities for production servers: Select Model, Resolve Model ID, Prepare Tools / Prepare Output Tools, Prefix Tools, Set Tool Metadata, Include Tool Return Schemas, Process History, Process Event Stream, Reinject System Prompt, and Raise Content Filter Error.

And the agent plugs into any interface: ACP (experimental, Harness) serves it to editors like Zed over the Agent Client Protocol, and core ships the web chat UI, CLI, frontend adapters (AG-UI, Vercel AI), and realtime voice.

Community packages extend the same capability system further; see third-party capabilities.

Composing from blocks

A research agent from regular capabilities -- this is literally Researcher's composition, minus its short default instructions:

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

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(store=LocalFileStore())],
    )
)

agent = Agent(
    'anthropic:claude-opus-5-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(store=LocalFileStore()),  # 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)
#> ...

Everything is observable: logfire.instrument_pydantic_ai() gives you a full trace of every run: every model call and tool call, with token and cost tracking. It's standard OpenTelemetry, so any OTLP backend works; Logfire is the easiest way to see it during development.

When do you need the Harness?

"Harness" is the field's term for everything around the model that turns it into an agent: the loop, the tools, the context management. Reach for this package when your agent should do more than core's lean harness covers: touch files, run code, browse, remember, delegate, or stay coherent through hours-long runs. The boundary between the packages is mechanical, not a maturity tier: core ships the capabilities that require model or framework support (provider-native tools like image generation, provider APIs like compaction, deep loop integration like tool search, and fundamentals like thinking, MCP, and web search) and the Harness ships everything else, as a separate package so capabilities can iterate at the speed the field moves while Pydantic AI itself stays lean.

Installation

uv:

uv add pydantic-ai-harness

pip:

pip install pydantic-ai-harness

This installs pydantic-ai-slim with it, so it works on its own; you don't need to install Pydantic AI separately. Model providers and the CLI come via extras that pass through to Pydantic AI: pydantic-ai-harness[anthropic], [cli]. Some capabilities need their own extra for optional dependencies; each capability's page gives its exact install line. Requires Python 3.11+.

Build your own

Capabilities are the primary extension point for Pydantic AI, and every capability in this repo doubles as a worked example. Publishing a standalone package? Use the pydantic-ai-<name> naming convention; see Publishing capability packages.

Contributing

We welcome capability contributions:

1. Start with an issue. Open a feature request so we can discuss approach and priority before code is written.
2. Then open a PR and link the issue. We review based on community interest; upvotes on both count.
3. Don't chase green CI. Get the approach working and let us know; we may push to your branch or follow up, and you'll be credited as the original author. (See the Pydantic AI contributing guide.)

Development

make install   # install dependencies
make format    # ruff format
make lint      # ruff check
make typecheck # pyright strict
make test      # pytest
make testcov   # pytest with 100% branch coverage

Version policy

Pydantic AI Harness uses 0.x versioning, and that's a statement about API stability, not maturity: these capabilities are tested end-to-end and meant for production use, but their APIs may still move between minor releases (0.1 -> 0.2): renamed parameters, changed defaults, restructured APIs, always with deprecation warnings where practical. Patch releases will not intentionally break existing behavior, and every breaking change is documented in release notes with migration guidance your agent can follow. Keeping the Harness a separate package from Pydantic AI, which has a stricter version policy, is what lets capabilities iterate at the speed the field moves.

Part of the Pydantic Stack

Everything you need to ship production-grade AI agents:

• Pydantic AI: the type-safe agent framework
• Pydantic Logfire: AI-first, full-stack observability
• Logfire AI Gateway: unified LLM proxy
• Pydantic Evals: evaluate any Python function, agents included
• genai-prices: model pricing data, kept current

License

MIT; see LICENSE.