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 for long runs, 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 90+ of them, and complete agents like Coder and Researcher are themselves combinations of capabilities. Use a single capability, compose your own set, or start from the whole coding agent and swap parts out.
Pydantic AI, the Harness, and CLAI
Three packages, each built on the one before it. Start with the one that matches what you are doing:
| Package | What it is | Start here when |
|---|---|---|
Pydantic AI (pydantic-ai) |
The agent framework: the agent loop, models from every major provider, tools, structured output, and the capability system | You are building an agent, or an LLM feature in your own application |
Pydantic AI Harness (pydantic-ai-harness) |
Capabilities for a Pydantic AI agent: workspaces, file and shell tools, memory, sub-agents, context management, and complete agents like Coder |
Your agent needs to edit files, run commands, remember, delegate, or keep working through long runs |
CLAI (pydantic-clai2) |
A coding agent for your terminal, run as clai2, built on the Harness's Coder and extended with plugins |
You want to use a coding agent rather than build one, or chat with your own agent in a terminal |
Each package installs the one it is built on: pydantic-ai-harness installs pydantic-ai-slim, and pydantic-clai2 installs pydantic-ai-harness. CLAI is not the clai chat CLI that ships with Pydantic AI.
Quick start
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, Render, Sprites, Daytona, or boxd); 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-6.1-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 FileMemoryStore
agent = Agent(
'openai:gpt-6.1-sol',
capabilities=[
LocalWorkspace('.'),
Coder(),
WebSearch(), # look up docs and error messages on the web
Memory(FileMemoryStore('.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.
Built from capabilities
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 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 FileMemoryStore 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 FileMemoryStore
from pydantic_ai_harness.tool_output_limits import LocalFileOverflowStore
memory = Memory(FileMemoryStore('.', workspace=LocalWorkspaceBackend('/var/lib/myapp/memory'))) # notes on this machine
limits = ToolOutputLimits(store=LocalFileOverflowStore()) # 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. When the workspace user cannot write to the working directory, Shell keeps its job files in a directory private to that user under the workspace's temp directory ($TMPDIR in its environment, or /tmp) instead.
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.
From problem to capability
Look up a capability by the problem it solves. The Capabilities section below lists all of them by what they give your agent.
| If your problem is... | Capability | How it works |
|---|---|---|
| The model's output must pass a check, and bad output should be retried or blocked | OutputGuardrail |
Its guard returns GuardrailResult.retry(...) to send the output back to the model, or False to raise OutputBlocked. retry needs run(): under run_stream() it raises UnexpectedModelBehavior. |
| One tool result is flooding the context window | ToolOutputLimits |
By default, a result of 10,000 characters or more spills to a file in the run's workspace, and the model gets a preview plus a handle to read the rest. If the write fails, the result is truncated to 4,000 characters. Without a workspace, pass store=LocalFileOverflowStore(). |
| The agent's files and commands must start in a specific directory | Core LocalWorkspace, or a sandbox |
Set the directory on the workspace: LocalWorkspace('./repo'), or working_dir= on a sandbox. Every capability that works in the workspace starts there; Shell(cwd=) and FileSystem(cwd=) warn and are ignored. In your own tool, ctx.workspace.run(..., cwd='subdir') starts one command elsewhere. |
| A run, a day, or a tenant needs a spend ceiling | Core UsageLimits, or SpendLimits |
For one run, pass usage_limits=UsageLimits(cost_limit=Decimal('5')): the run raises UsageLimitExceeded after the response that crosses the limit. For a day or month, per tenant, or across worker processes, SpendLimits(budgets=[Budget(usd=Decimal('100'), window='day')]) refuses the next request once a window is spent. |
| The model should get only a few calls to an expensive tool per run | ToolBudgets |
ToolBudgets(per_tool={'web_search': 3}, refuse_repeats={'web_search'}) answers the fourth call, or an exact repeat, with a tool result saying the budget is used, and the run continues. UsageLimits.tool_calls_limit stays the hard ceiling. |
| The model repeats the same tool call without making progress | DetectLoops |
The default action='nudge' adds a system prompt asking the model to change approach; action='error' stops the run with LoopDetectedError. |
| The model sends malformed JSON in a tool call | RepairToolArguments |
Runs json-repair on the arguments before validation, fixing trailing commas, single-quoted keys and truncated JSON; valid arguments pass through unchanged. Import it from pydantic_ai_harness.repair_tool_arguments and install the repair-tool-arguments extra. Coder includes RepairToolArguments, so its coder extra installs json-repair too. |
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. 90+ 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.
| Harness | Package | What it provides |
|---|---|---|
| Coder | Harness | Six coding tools, persistent shell commands, delegation to itself, autonomous guidance, and context controls |
| Researcher | Harness | A complete web-research stack: search, page fetching, a delegated sub-researcher, and bounded tool output |
Execution environments
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 in the run's workspace, with opt-in ripgrep tools; path-traversal checked, secrets read-only |
| Smart Search | Harness | Code search by behavior in the run's workspace: plain-English queries, ranked excerpts, judged by any model (a decision model over System One, or TypeSafe's Jev, recommended) |
| Shell | Harness | Command execution in the run's workspace 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 |
| E2B Sandbox | Harness | Commands and files in an isolated E2B cloud sandbox |
| Kubernetes Sandbox | Harness | Commands and files in a sandbox pod from a Kubernetes agent-sandbox warm pool |
| Render Sandbox | Harness | Commands and files in an isolated Render sandbox |
| Sprites Sandbox | Harness | Commands and files in a persistent Fly.io Sprite |
| Daytona Sandbox | Harness | Commands and files in an isolated Daytona cloud sandbox |
| boxd Sandbox | Harness | Commands and files in an isolated boxd cloud machine |
| Smol Sandbox | Harness | Commands and files in a smolvm microVM on your own machine; no cloud account |
| BoxLite Sandbox | Harness | Commands and files in a BoxLite micro-VM on your own machine, with an optional egress allow-list; no cloud account |
| OpenSandbox | Harness | Commands and files in a sandbox on your own OpenSandbox server, on Docker or Kubernetes |
| Docker Container | Harness | Commands and files in a local Docker or Podman container |
| SSH Workspace | Harness | Commands and files on a remote host over your ssh client; no isolation |
| Bubblewrapped Workspace | Harness | Wraps another workspace capability so its commands run in a Linux bubblewrap wrapper on that workspace's host (best-effort convenience, not a security boundary) |
Tools & native abilities
Abilities the provider executes natively, and connections to any MCP server.
| 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 |
Integrations
Tools from third-party services, most through the service's own hosted MCP server.
| Capability | Package | What it does |
|---|---|---|
| GitHub | Harness | Read and change GitHub repositories, issues, pull requests, and other accessible resources. |
| Linear | Harness | Read and change Linear issues, projects, teams, and comments. |
| Macroscope | Harness | Run a local Macroscope code review and hand the findings to the agent |
| LocalStack | Harness | An emulated AWS environment with AWS CLI tools |
| Google Workspace | Harness | Use Gmail, Calendar, Drive, and other Google Workspace tools. |
| Notion | Harness | Search and change Notion workspace content. |
| Slack | Harness | Give an agent Slack messages, channels, and canvas tools. |
| Day AI | Harness | Search and update CRM records and meeting context through Day AI's hosted MCP server |
| Grain | Harness | Search and read meetings, transcripts, and notes, and create clips and tag meetings, through Grain's hosted MCP server |
| Pylon | Harness | Work with support issues, accounts, and contacts through Pylon's hosted MCP server |
| StackOne | Harness | Act on linked SaaS accounts (HRIS, ATS, CRM, …) via StackOne |
| PostHog | Harness | Query product analytics and manage feature flags, experiments, and dashboards through PostHog's hosted MCP server |
| Logfire MCP | Harness | Query Logfire telemetry and manage observability resources. |
| Ordinal | Harness | Draft, schedule, and analyze social posts through Ordinal's hosted MCP server |
Web & research
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 |
| Keenable Search | Harness | Web research via Keenable: excerpted search and full-page reads, keyless and with no extra to install |
| 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 |
Reasoning, planning & delegation
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 |
| Peers | Harness | Discover and message other agent sessions without controlling their runs |
| 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 |
Context management
How the agent spends its context window over a long run, and how often it pays for the same tokens.
| 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 |
| IPython Code Mode | Harness | Code Mode with a persistent IPython kernel in place of the Monty sandbox: full CPython and any installed package, with state kept between calls. For local agents only; not a sandbox |
| 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 |
Knowledge & memory
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 |
| Pixeltable | Harness | Read-only, allowlisted tools over Pixeltable tables and embedding indexes, plus a Pixeltable MemoryStore |
| 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 |
Control & safety
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 |
| Artifact Scanning | Harness | Scan memory files and skills for prompt injection, credential exfiltration, and hidden content before they are stored or loaded |
| 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 |
| Tool Call Judge | Harness | A second model answers one risk question per tool call and blocks the call before the tool function runs |
| Approval Reviewer | Harness | A second model answers one risk question per call waiting for approval, approves the low-risk ones, and leaves the rest to a person |
| Permissions | Harness | Ask a person before file writes and commands, by permission mode: full access, auto (asks before risky commands), or read-only |
| Handle Deferred Tool Calls | Core | Resolve approvals, answers and external results on deferred tool calls inside the run, in place or by waiting for them, durably on AWS Lambda |
| System Reminders | Harness | Cache-safe re-injection of guidance mid-run to counter instruction fade |
| Detect Loops | Harness | Notice repeated tool calls, results, alternations, or responses, or a response repeating itself as it streams, and nudge the model, stop the run, or call your handler |
| Tool Budgets | Harness | Cap calls per tool and per run, and refuse exact repeats, with a tool result the model can act on instead of an exception |
| Trajectory Judge | Harness | A second model reviews the live run every N requests over a sliding token window and steers it mid-run |
| Refine Output | Harness | Send the agent back to review and revise its output before the run ends |
Self-extension
| Capability | Package | What it does |
|---|---|---|
| Capability Creation | Harness | The agent writes, validates, and persists new capabilities during a run; the host loads them into a later run via load_active(workspace) and capabilities= |
Execution runtime
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 nine engines: Temporal, DBOS, Prefect, Restate, Airflow, and the Harness engines AWS Lambda, Absurd, pgtask, and Azure Durable Task below. See the workspace guide for Coder, Shell, and FileSystem |
| AWS Lambda durability | Harness | Checkpoint model requests and tool calls into AWS Lambda durable function steps |
| Absurd durability | Harness | Checkpoint model requests, MCP calls, and tool calls into Absurd steps on PostgreSQL |
| pgtask durability | Harness | Checkpoint model requests, MCP calls, and tool calls into pgtask steps on PostgreSQL |
| Azure Durable Task durability | Harness | Run model requests, tool calls and durable operations as activities in Durable Task Scheduler orchestrations |
| Render Workflows | Harness | Run model requests and tool calls as chained task runs with separate retries, timeouts, and compute settings; retrying the task that runs the agent can repeat completed work |
| Step Persistence | Harness | Save, restore, resume (continue_run), and fork (fork_run) runs; file/SQLite/Mongo backends |
| Model Fallback | Core | Fall back to other models when a model request fails or its response is rejected, within the run's own request step |
| 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.
Composing from blocks
A research agent from regular capabilities -- this is 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 LocalFileOverflowStore
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=LocalFileOverflowStore())],
)
)
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=LocalFileOverflowStore()), # 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)
#> ...
logfire.instrument_pydantic_ai() records 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; run uvx logfire-cli wizard --task pydantic-ai once to set up Logfire.
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:
- Start with an issue. Open a feature request so we can discuss approach and priority before code is written.
- Then open a PR and link the issue. We review based on community interest; upvotes on both count.
- 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 to signal API stability, not maturity: the capabilities are tested end-to-end and meant for production use, but their APIs may change between minor releases (0.1 -> 0.2) through renamed parameters, changed defaults, or restructured APIs, 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, lets capabilities change faster than core.
On 0.x, each Harness release ships alongside the Pydantic AI release with the same minor and patch number (Harness 0.51.0 ships with Pydantic AI 2.51.0) and pins that exact pydantic-ai-slim version, so upgrading the Harness upgrades Pydantic AI with it and every installable pair has been tested together.
After 1.0
From 1.0, the Harness follows the rules of Pydantic AI's version policy: no intentional breaking changes in minor releases, and deprecated functionality is not removed until the next major version. The changes that policy does not consider breaking, such as bug fixes for code that relied on undocumented behavior, OpenTelemetry span attributes, and __repr__ output, are not breaking for the Harness either. Neither is a change that follows a third-party service or SDK a capability integrates with, when that service removes or changes what the capability relied on. Capabilities marked experimental on their page (currently ACP) are excluded until they graduate.
A capability's behavior includes what it sends to the model, so stability covers more than signatures:
- Defaults: a minor release does not change a default parameter value in a way that changes what an existing agent does, such as enabling a tool, lowering a limit, or switching a fallback. New behavior arrives behind a new parameter, and a default changes only in a major release.
- Stored history: tool names, argument schemas, and the other records a capability writes into message history and reads back on later runs, such as metadata keys and framing tags, persist in histories that you may store and resume. A minor release can add optional tool arguments but does not rename or remove a tool, an argument, or a record a capability relies on.
- Prompt text: the wording of instructions, tool descriptions, and other text a capability sends to the model can change in a minor release, since improving how models use a capability is part of maintaining it. Release notes list these changes. Where a capability accepts its own instructions or descriptions as parameters, passing them keeps your wording fixed.
From 1.0, Harness version numbers no longer mirror Pydantic AI's, and a Harness major release does not require a Pydantic AI major release. Every Harness release still pins the exact pydantic-ai-slim release it was tested with, and moving that pin to a new Pydantic AI major version is itself a Harness major release, so upgrading the Harness within a major version does not cross a Pydantic AI major. The pin is listed in the package metadata on PyPI, and the release notes name the Pydantic AI release each Harness release ships with.
Part of the Pydantic Stack
Related Pydantic projects:
- 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.
Metadata
Release files for pydantic-ai-harness 0.70.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pydantic_ai_harness-0.70.0.tar.gz | 1.7 MB | With provenance | Details for pydantic_ai_harness-0.70.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pydantic_ai_harness-0.70.0-py3-none-any.whl | Python 3 | none | any | Details for pydantic_ai_harness-0.70.0-py3-none-any.whl |
Total release size: 3.8 MB
Release files / pydantic_ai_harness-0.70.0.tar.gz
| Download URL | pydantic_ai_harness-0.70.0.tar.gz |
|---|---|
| Size | 1.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f110e495921009e46fc66c10771c35329fad4e8976e42848087e0a910abb49c2
|
|
BLAKE2b-256 checksum How to use checksums |
22404eea7cc930004fd0d2d2a92ee68518f5ef7cc0ab4239b1fa3eeeeff2cc20
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / pydantic_ai_harness-0.70.0-py3-none-any.whl
| Download URL | pydantic_ai_harness-0.70.0-py3-none-any.whl |
|---|---|
| Size | 2.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
62a6d329572786ed0dce25f4dbac9ede82739cc6d15e22e8a3a7743850fdc250
|
|
BLAKE2b-256 checksum How to use checksums |
36a56a88c7355370f1e8a64b10bd1c67247bffad128294a50097509a13e3a99d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for pydantic-ai-harness 0.70.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pydantic_ai_harness-0.70.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.