pydantic-ai-harness: the capability library that turns a Pydantic AI agent into a long-running worker

The gap pydantic-ai-harness fills in a Pydantic AI agent

Pydantic AI core already gives you a typed agent loop, any model, your own tools and structured output. The README calls that a light harness and says it is enough for simple agents. The problem starts when you set an agent loose on work that takes hours: fixing a codebase, researching a question, running unattended. What the model needs around it grows, and core does not ship it. The README lists the missing pieces explicitly: 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.

This package is the official capability and harness library for Pydantic AI, and the audience is narrow and specific: Python developers who have already chosen Pydantic AI and now want their agent to keep working past the first few turns. It is not a general agent framework and it does not replace Pydantic AI. It bolts onto it.

One primitive repeated: capabilities all the way down

Everything in the package is a capability, described in the README as a self-contained unit of agent behavior you add to capabilities=[...] on any agent. That single design decision is what makes the rest legible. Coder and Researcher are not special framework objects; the README says Coder is a CombinedCapability bundling the same blocks you can use directly, and that complete agents come apart the way they went together.

The README shows the exact agent behind the exported coder_agent, written block by block, importing ClearToolResults, FileSystem, LLM_API_KEY_ENV_PATTERNS, Planning, RepoContext, Shell, SubAgent, SubAgents, ToolOutputLimits and WarnNearLimits. A SubAgent named explorer is constructed with instructions telling it to explore the codebase and answer questions without modifying anything, and a list of allowed_commands covers git, rg, grep, find, ls, cat, sed, head, tail, python, uv, pytest, ruff and make. Constructor arguments such as working directory, command allowlist and window sizes thread through to the underlying capabilities.

Two consequences follow. First, you can start from the whole harness and delete what you do not want, or start from the blocks and build up; the README calls both first-class. Second, there is no hidden behavior to reverse-engineer when something goes wrong, because the composed stack is the same code you could have written. The cost is verbosity: the blown-out example is long, and the README itself carries a comment asking maintainers to keep it in sync across five files, which tells you the duplication is a known maintenance burden.

Installing pydantic-ai-harness and running the Coder agent

The README installs with uv and a provider extra. This pulls in pydantic-ai-slim with the anthropic extra, so you do not have to name the slim package separately.

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

A complete coding agent is then one import and one capability. The README's quick start builds an Agent on anthropic:claude-fable-5 with capabilities=[Coder()] and calls run_sync with a prompt asking the agent to find why tests/test_parser.py fails and fix the bug. The documented output reports that parse() returned None on empty input instead of raising, that the fix landed in src/parser.py, and that tests pass.

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)

That stack includes workspace-rooted file access, an allowlisted shell, repo orientation, planning, a read-only explorer sub-agent and context management. It runs anywhere a Pydantic AI agent runs, and agent.to_cli_sync() opens it as a terminal chat while agent.to_web() serves it in a browser.

If you would rather not write a Python file at all, the README combines the exported coder_agent with clai and uvx. Note the module path and the model string exactly as the README gives them.

uvx --with pydantic-ai-harness clai -a pydantic_ai_harness.coder:coder_agent -m anthropic:claude-fable-5

Adding behavior means adding entries to the same list. The README swaps in gpt-5.6-sol, WebSearch from pydantic_ai.capabilities, and Memory backed by FileStore pointed at a .agent-memory directory, after installing the openai extra on pydantic-ai-slim.

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

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(),
        Memory(FileStore('.agent-memory')),
    ],
)

Skills, Web Fetch, Guardrails and Dynamic Workflow slot in the same way. Skills loads your SKILL.md procedures on demand from a skills/ directory and needs the skills extra.

What the extras do not cover, and the alpha label

The most useful limitation is written in pyproject.toml rather than the README. The optional-dependencies block ships anthropic and cli pass-throughs so that uv add "pydantic-ai-harness[anthropic,cli]" works standalone, but it deliberately omits openai and google. The comment explains why: browser-use pins provider SDKs that conflict with slim's floors when the workspace resolves all extras together. So the OpenAI path in the README requires a separate uv add of pydantic-ai-slim[openai], and there is no pydantic-ai-harness[openai] shorthand to lean on.

The second constraint is maturity. pyproject.toml classifies the package as Development Status 3 - Alpha, and the release history backs that up: v0.25.0, v0.26.0 and v0.27.0 all landed between 2026-08-24 and 2026-08-27. Three minor versions in four days is a fast-moving surface. The repository is not archived and the last push was on 2026-08-27, so the project is current, but current is not the same as stable, and a pre-1.0 minor bump can rename an import.

The third constraint is scope. The README frames the harness around long-running work, and the pieces it advertises (planning, compaction, durable execution, cross-session memory) are answers to problems that short-lived agents do not have. If your agent answers a question in one turn, you are paying for a workspace, a plan file and a memory store you will never read. The README says as much when it notes that for simple agents the light harness in core is enough.

pydantic-ai-harness against LangGraph and hand-rolled loops

The obvious comparison is LangGraph, and the difference is where state lives. LangGraph models an agent as an explicit graph of nodes and edges with a checkpointer persisting state between steps; you draw the control flow, and the framework executes it. Pydantic AI Harness does not ask you to draw anything. The agent loop stays the one Pydantic AI already runs, and the harness contributes capabilities that the loop consults: a filesystem rooted at a workspace, a shell restricted to an allowlist, a plan the agent keeps current, memory backed by a FileStore, sub-agents it delegates to, and context compaction that trims the transcript. There is no graph to inspect, which is easier to adopt and harder to visualize.

The second alternative is the one most teams actually have: a hand-rolled loop that appends messages to a list, calls tools, and truncates when the context window fills. That works until it does not, and the failure is usually silent, because truncation drops the constraint the agent needed. The harness replaces that with named capabilities you can reason about, and because Coder is just a CombinedCapability, you can lift a single block out of it rather than adopting the whole stack. The trade is that you inherit the package's release cadence and its alpha status.

Maintenance, upgrades and the MIT licence

Upgrade cost is the real question with an alpha package. Three releases in four days means the changelog is the thing to read before any version bump, and the version is dynamic (pyproject.toml uses uv-dynamic-versioning with hatchling), so the number in your lockfile is the one that matters. The Makefile shows the project's own quality gate: install runs uv sync --frozen --all-extras --group lint and installs pre-commit hooks via prek, and all chains format, lint, typecheck and testcov, where typecheck is pyright and testcov runs coverage over pytest. Integration tests for localstack, MongoDB and Redis skip unless a server is reachable; the Makefile comments give docker run -d -p 27017:27017 mongo:8 and docker run -d -p 6379:6379 redis:8, with MONGODB_TEST_URL and REDIS_TEST_URL to point elsewhere. That tells you the persistence-backed capabilities have live tests behind them, which is a better signal than any badge.

Licensing is straightforward: the package is MIT, declared both in pyproject.toml and as a classifier. MIT permits commercial use and modification with the copyright notice retained, but this is not legal advice and your own dependency chain (pydantic-ai-slim, genai-prices, httpx, and any provider SDK) carries its own terms. The dependency floor is pydantic-ai-slim>=2.40.0 and Python >=3.10, with classifiers through 3.14.

Who should pick this up

The fit is a team already committed to Pydantic AI that needs an agent to survive a long session. You get a workspace, a plan, memory, sub-agents and compaction as named capabilities, and the README's promise that you can take the stack apart later is backed by the blown-out Coder example. If you only need one block, import that block; SubAgent, Shell, Planning and FileSystem are all importable on their own.

The misfit is a team that wants a frozen API or a visual control flow. The alpha classifier, the sub-1.0 version and the three releases in four days all point the same way, and the missing openai and google extras mean the provider story is not uniform across vendors. A one-turn agent does not need this package at all. Before committing, check that your provider resolves through the extras that exist, and read the release notes for the version you pin.

Editorial conclusion

Adopt pydantic-ai-harness if you already run Pydantic AI agents and need a workspace, a plan, cross-session memory or sub-agents without writing those primitives yourself; the Coder and Researcher stacks are a reasonable starting point that you can pull apart later. Do not adopt it if you need a stable API surface: pyproject.toml marks the package Development Status 3 - Alpha and the version has moved from 0.25.0 to 0.27.0 within four days in August 2026, so pin the version and read the release notes before upgrading. Verify first that the provider you want resolves: the extras list ships anthropic and cli pass-throughs but deliberately omits openai and google, and the comment in pyproject.toml explains that browser-use pins provider SDKs which conflict with slim's floors when the workspace resolves all extras together.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes