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.
Install with uv:
pip install "pydantic-ai-harness[anthropic]"
uv add "pydantic-ai-harness[anthropic]"
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.
Coder provides six tools: read_file, write_file, edit_file, list_files, grep, and shell, plus 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-fable-5
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:
pip install "pydantic-ai-slim[openai]"
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(), # 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 page lists what pairs well.
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, 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.
from pydantic_ai import Agent
from pydantic_ai_harness.coder import Coder
agent = Agent(
'anthropic:claude-fable-5',
name='coder',
capabilities=[Coder('.')],
)
See the Coder documentation for tool signatures, persistent shell lifecycle, and migration from the previous planning/delegation composition.
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:
Complete agent stacks as regular combined capabilities: one import gives you a working agent, and you can take either apart into the blocks below.
| Harness | Package | What it provides |
|---|---|---|
| Coder | Harness | Six coding tools, persistent shell commands, autonomous guidance, and context controls |
| Researcher | Harness | A complete web-research stack: search, page fetching, a delegated sub-researcher, and bounded tool output |
The workspace the agent acts in: the files it edits and the commands it runs, local or isolated.
| Capability | Package | What it does |
|---|---|---|
| FileSystem | Harness | Read, write, edit, list, and search files under a root, with opt-in ripgrep tools; path-traversal and symlink safe, secrets read-only |
| Shell | Harness | Command execution with allowlists, denylists, timeouts, credential-stripping, and opt-in commands that outlive the run |
| Modal Sandbox | Harness | Commands and files in an isolated Modal cloud sandbox |
Connections to systems outside the agent’s workspace, and abilities the provider executes natively.
| Capability | Package | What it does |
|---|---|---|
| MCP | Core | Connect any MCP server’s tools; local by default, provider-native connectors opt-in |
| Image Generation | Core | Generate and edit images; provider-native where supported, sub-agent fallback elsewhere |
| StackOne | Harness | Act on linked SaaS accounts (HRIS, ATS, CRM, …) via StackOne |
| LocalStack | Harness | An emulated AWS environment with AWS CLI tools |
| Macroscope | Harness | Run a local Macroscope code review and hand the findings to the agent |
Finding and reading things on the open web.
| Capability | Package | What it does |
|---|---|---|
| Web Search | Core | Provider-native search where available, local DuckDuckGo fallback everywhere |
| Web Fetch | Core | Fetch and read URLs, native or local |
| X Search | Core | Search X; native on xAI, subagent fallback elsewhere |
| Exa Search | Harness | Web research via Exa: excerpted search, full-page reads, opt-in cited deep search |
| Exa Agent | Harness | Delegate open-ended research to the Exa Agent API |
| You.com Search | Harness | Web search and page reads via You.com: query-relevant excerpts or full-page markdown |
| You.com Research | Harness | Cited answers and multi-step research via the You.com Answer, Research, and Finance Research APIs |
| Browser Use | Harness | Hand web tasks to an autonomous browser-use agent driving a real browser |
| Playwright Browser | Harness | Drive a real Chromium page yourself: navigate, click, type, read, and inspect what the page did |
How the agent thinks and divides the work.
| Capability | Package | What it does |
|---|---|---|
| Thinking | Core | Provider-adaptive extended thinking at configurable effort |
| Planning | Harness | Model-owned task plans with a cache-safe live reminder |
| Subagents | Harness | Delegate self-contained tasks to named child agents |
| Dynamic Workflow | Harness | The model orchestrates sub-agents from one Python script: fan-out, chain, vote in a single tool call, with hard max_agent_calls budgets |
| Advisor | Harness | Let an executor consult a stronger model mid-run |
| Background Tools | Harness | Run selected tools concurrently; results arrive as follow-up messages |
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.
| Capability | Package | What it does |
|---|---|---|
| Code Mode | Harness | The model writes one Python script that calls many tools inside a Monty sandbox: one round-trip instead of N, and intermediate results never enter the context window. The answer to tool-call token bloat |
| Tool Search | Core | Load tool definitions on demand instead of carrying hundreds in every prompt |
| Compaction | Core | Provider-native compaction on OpenAI and Anthropic; the provider summarizes history server-side |
| Compaction | Harness | Model-agnostic strategies: tool-result clearing, sliding-window trimming, LLM summarization, tiered; all window-relative, with live usage reporting |
| Tool Output Limits | Harness | Truncate, spill to a queryable file, or summarize oversized tool returns at the source |
| Warn On Cache Busts | Harness | Detect prompt-cache prefix collapses between requests, from the provider’s own numbers |
What the agent knows and remembers, loaded when relevant instead of carried in every prompt.
| Capability | Package | What it does |
|---|---|---|
| Memory | Harness | A persistent, namespaced notebook: bounded prompt injection, on-demand search; in-memory/file/Postgres stores |
| Conversation Search | Harness | BM25 search over stored history, including turns compaction dropped |
| Skills | Harness | Load Agent Skill (SKILL.md) instructions on demand |
| Repo Context | Harness | Start runs oriented: AGENTS.md/CLAUDE.md + repository structure |
| Pydantic AI Docs | Harness | On-demand Pydantic AI documentation lookup |
Bounding what the agent may do, and keeping it on-instructions.
| Capability | Package | What it does |
|---|---|---|
| Repair Tool Arguments | Harness | Repair malformed JSON tool arguments before schema validation. |
| Guardrails | Harness | Validate/block/redact user input, tool calls, tool results, and output, including secret masking and parallel async guards |
| Prompt Injection Defender | Harness | Classify local tool results for indirect prompt injection and optionally withhold high-risk results |
| Spend Limits | Harness | Cross-window USD/token budgets and per-response cost tracking, per model and per tenant |
| Ask User | Harness | Let the model ask the user multiple-choice questions mid-run; you supply the answerer (terminal, web, test) |
| Tool approval | Core | Flag tool calls that need human approval before they run |
| Handle Deferred Tool Calls | Core | Resolve approval-deferred tool calls programmatically |
| System Reminders | Harness | Cache-safe re-injection of guidance mid-run to counter instruction fade |
| Trajectory Judge | Harness | A second model reviews the live run every N requests over a sliding token window and steers it mid-run |
| Capability | Package | What it does |
|---|---|---|
| Capability Creation | Harness | The agent writes, validates, and persists new capabilities during a run, loaded on the next run: self-extension with typed, inspectable units instead of arbitrary code |
Outside the loop: how runs persist, survive failures, and get observed and configured in production.
| Capability | Package | What it does |
|---|---|---|
| Durable execution | Core | Runs that survive restarts and failures on Temporal, DBOS, or Prefect, with Restate, Kitaru, and Airflow integrations |
| AWS Lambda durability | Harness | Checkpoint model requests and tool calls into AWS Lambda durable function steps |
| Step Persistence | Harness | Save, restore, resume (continue_run), and fork (fork_run) runs; file/SQLite/Mongo backends |
| Instrumentation | Core | OpenTelemetry GenAI spans for every model and tool call; the raw material for Logfire traces |
| Managed Prompt | Harness | Back instructions with a Logfire-managed prompt; version and roll out without redeploying |
| Thread Executor | Core | Run sync tools on a shared thread pool |
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.
“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.
pip install pydantic-ai-harness
uv add 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.10+.
New to Pydantic AI itself? Start with its docs: the agent you mount these capabilities on is defined there.
Everything the harness does is observable: core’s Instrumentation capability (or logfire.instrument_pydantic_ai()) emits 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.
Capabilities are the primary extension point for Pydantic AI, and every capability in this library doubles as a worked example. Publishing a standalone package? Use the pydantic-ai-<name> naming convention; see Publishing capability packages.
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.
- Capabilities: what capabilities are, built-in capabilities, building your own
- Hooks: lifecycle hooks reference, ordering, error handling
- Extensibility: publishing packages, third-party ecosystem
- Toolsets: building tools for capabilities
- API reference: full API docs