Pydantic AI Harness and UHP

Follow the maintained repository and explicit workspace API

Pydantic AI Harness has moved. The former repository now says it is frozen at v0.36.0; current development lives in pydantic/pydantic-ai. On 4 October, the maintained repository’s latest release is v2.54.0 and the PyPI harness package is 0.54.0. The harness 0.N version follows Pydantic AI 2.N; it is not the same package version.

The current harness README separates the workspace capability from Coder:

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

This construction is source-checked, not run. Installation uses the documented pydantic-ai-harness[coder,anthropic] extras and requires Python 3.10+. The provider/model remains an authenticated execution choice.

LocalWorkspace('.') is not a sandbox. The README says commands run on your machine with your access and can persist beyond individual runs. Choose a supported sandbox capability when isolation is required; do not infer command confinement from a workspace-rooted file API.

Existing integration assumption	Current check
Old repository is the release authority	Follow maintained monorepo/package releases
Coder implicitly supplies all execution context	Declare the workspace capability explicitly
agents/ definitions load automatically	Current release says that default changed; opt in deliberately
Durable engine stacking is harmless	v2.54.0 rejects a second durable engine before binding

Use workspace trust and instruction provenance when admitting local agents, instructions or commands. The older CodeMode/ACP cases below remain historical and are not refreshed merely by this repository move.

Release check — 4 October 2026

The final release in the former standalone repository is v0.36.0, published 2026-09-25. The release adds hosted MCP tool integrations, updates Monty with WebSocket support and changes compaction-window and self-delegation behavior. The older CodeMode and ACP case studies below retain their original release scope.

Evidence scope: the integration details, commands, measurements and development-head references below preserve the 12 Sep 2026 source snapshot. They are not presented as a fresh test of this newer release. For the current UHP protocol, HarnessRouter release and suite coordinates, use the release tracker and conformance guide. Adapter support does not establish upstream-native UHP adoption.

Source snapshot — 12 Sep 2026

Pydantic AI Harness is a distinct upstream agent-harness library, not a UHP implementation. Pydantic describes it as the official capability and harness library for Pydantic AI. The latest observed stable release is v0.31.0, published 12 September 2026 at 00:54:49 UTC, with tag/current-main commit d8787b74fa043908bca6dd0f5cc7f1f2e1c3a50a at this cutoff.

The v0.31.0 package metadata still classifies the project as Alpha. That matters when treating its APIs as integration contracts: the project is active and substantial, but capability surfaces can continue to change.

Caution

No native UHP adoption is established. The reviewed Pydantic AI Harness repository and release sources do not name UHP. HarnessRouter v0.16.1 also does not list Pydantic AI Harness among its ten released backends. ACP and MCP support described below are separate protocol boundaries and must not be reclassified as UHP support.

What the harness actually standardizes

Pydantic AI already supplies the typed agent loop, model abstraction, tools and structured output. Pydantic AI Harness adds higher-level execution capabilities for agents that need to operate over longer or more complex tasks.

The stable v0.31.0 line retains the capability-composition model rather than one monolithic coding-agent runtime. The published capability set includes:

• workspace-rooted file access and allowlisted shell execution;
• repository context that can load AGENTS.md / CLAUDE.md plus repository structure;
• planning and model-owned task state;
• named subagents and dynamic multi-agent workflow composition;
• memory across sessions;
• context compaction, tool-output controls and cache-boundary diagnostics;
• local or isolated execution environments;
• Agent Skills loaded from SKILL.md procedures;
• browser, search and research capabilities;
• durable-execution integrations that can survive process interruption.

Coder and Researcher are complete harnesses built by composing the same capability primitives available to application authors. This makes Pydantic AI Harness especially relevant to harness interoperability research: it exposes the internal composition problem that a network protocol such as UHP must remain distinct from.

v0.31.0: eager CodeMode changes the execution boundary

Stable v0.31.0 adds opt-in CodeMode(eager=True). Normal CodeMode waits for the model to finish a run_code call before running the snippet. Eager mode can execute complete top-level statements while the model is still streaming the remainder of that same tool call, then validates the executed prefix and runs only the remaining tail at normal dispatch.

The important boundary is not just latency. Early statements may already have produced side effects before the final run_code dispatch and its own hooks occur. Upstream therefore documents eager mode as a trust-sensitive option: it is disabled by default, should only be enabled when the provider preserves emitted tool-call parts and names, and cannot undo side effects if a later provider rewrite or restart invalidates or repeats an already executed prefix. Nested tools still run their own hooks, and eager execution is disabled under the harness’s durable-execution integrations because those concurrent streamed effects are not checkpointed as ordinary durable steps.

That makes eager=True a concrete harness execution-policy primitive, not an ACP, MCP or UHP wire feature. An outer protocol can carry the task and events, but it does not retroactively make speculative/streamed local side effects transactional.

The same release adds two other execution-integrity improvements:

• Subagent delegation events. SubAgents now emits DelegationStartEvent and DelegationEndEvent, giving hosts and adapters a first-class lifecycle signal for delegation rather than requiring them to infer delegation from tool arguments or results. This is harness observability and can improve ACP-facing presentation, but it is not a new ACP method.
• CodeMode sandbox value-shape fidelity. Tool results crossing into the Monty sandbox now better match the JSON-schema-derived stubs. Values such as Decimal, UUID and datetime-shaped data are converted to the declared string shape; mapping keys are stringified; supported binary/set/Ellipsis values retain their usable Python representation; and key stringification collisions fail visibly instead of silently dropping one value.

v0.30.0 foundation: live trajectory review and capability events

The preceding stable v0.30.0 introduced TrajectoryJudge, a harness capability that reviews a live run with a second model on a configurable cadence. The judge receives a bounded recent transcript window, evaluates concurrently with the main run, and can return a Steer verdict whose attributed correction is enqueued for the next model request. At most one evaluation per judge is in flight, usage participates in the parent run’s limits, and judge failures are surfaced rather than silently discarded.

That is a meaningful harness-control boundary: the runtime can evaluate and correct an agent trajectory while the run is still executing, rather than relying only on fixed-boundary guardrails or post-run evals. Upstream rejects TrajectoryJudge inside durable workflow/flow execution because its concurrent model calls are not checkpointed and could repeat on replay.

The same release moved more internal coordination toward capability events. FileSystem traversal emits events consumed by RepoContext through @on_event, while traversal-tool-name sniffing is deprecated. Older callback surfaces including on_spend, on_usage, on_fire and PlanEventEmitter are deprecated toward capability event subscriptions, and capabilities are required to make their OpenTelemetry behavior explicit.

These remain Pydantic AI Harness runtime/control and observability semantics. They do not change UHP, MCP or ACP wire behavior and do not establish UHP adoption.

v0.31.0 promotes the ACP and persistence corrections

Three corrections that were previously tracked as post-v0.30.0 main behavior are now part of stable v0.31.0.

PR #849 corrects an ACP presentation-integrity problem for approval-gated tools that only become visible per run. The adapter’s pre-run tool scan cannot see toolsets created by a capability’s for_run(), the callable arm of AgentToolset, or other non-FunctionToolset cases. Before the fix, such a call could be announced to the ACP client as in_progress and then rejected without ever executing. The adapter now uses the run’s DeferredToolRequests.approvals result as ground truth and corrects scan-invisible calls to pending before the decision. A statically known tool that raises ApprovalRequired from inside its body remains in_progress, because that body may already have produced side effects.

PR #848 fixes durable-history reconstruction for serializing SqliteStepStore and FileStepStore backends. Framework metadata can be stamped after a boundary snapshot is serialized, so hashing the complete before/after message previously broke overlap detection and could duplicate one six-message reproduction into fourteen recovered messages. The history hash now canonicalizes only those framework-stamped fields before overlap comparison, preserving distinct substantive message content while preventing duplicate recovery and duplicate ConversationSearch indexing.

PR #851 raises the general pydantic-ai-slim floor to >=2.40.0, matching the documented Agent.on_event surface used by the event-oriented capability examples. These are now released harness/adapter correctness facts, not unreleased current-main observations.

MCP is a tool-capability boundary

The stable capability catalogue lists MCP as a Core Pydantic AI capability for connecting MCP-server tools. That is a tool/resource integration inside a Pydantic AI agent. It is not a replacement for the surrounding harness lifecycle and is not a UHP task/session transport.

The experimental ACP adapter adds a second MCP path. An ACP client may provide MCP-server descriptions during session setup, but the adapter does not connect them automatically. A supplied session_config must translate session.mcp_servers into Pydantic AI toolsets; otherwise a session that supplies MCP servers is rejected rather than silently ignoring them. HTTP/SSE MCP support is advertised only when the adapter is configured to consume those servers.

That fail-visible behavior is an important integration boundary: protocol metadata is not treated as equivalent to an actually wired tool connection.

Experimental ACP server

Pydantic AI Harness ships a first-party experimental Agent Client Protocol (ACP) adapter under pydantic_ai_harness.experimental.acp. The stable v0.31.0 documentation still explicitly warns that ACP support may change or even be removed without a deprecation period.

run_acp_stdio / run_acp_stdio_sync expose a Pydantic AI Agent as an ACP agent over stdin/stdout. The adapter maps several editor-facing concerns:

ACP surface	Pydantic AI Harness behavior
Streamed assistant/reasoning output	Pydantic AI deltas are translated into ACP updates.
Tool presentation	File and shell operations can carry ACP kind, location and diff metadata.
Human approval	ACP permission requests map to Pydantic AI deferred-approval tools.
Workspace context	Per-session configuration can root tools at the ACP client’s cwd.
Client-native execution	Optional filesystem and terminal tools can route through the ACP client instead of the local agent process.
Session lifecycle	Cancellation, close, multi-turn history and optional session/load persistence are handled per session.

Session persistence and run durability remain separate. A SessionStore can reopen a prior ACP conversation, while step-durability capabilities can make the individual Pydantic AI run crash-resilient. The upstream docs describe those layers as composable rather than interchangeable.

This is native ACP exposure by Pydantic AI Harness, but the ACP adapter remains experimental. It does not establish UHP support.

Durable execution and capability composition

Stable v0.29.0, published 4 September 2026, added AWSLambdaDurability for AWS Lambda durable functions and clarified how repeated capabilities compose, including identities for SubAgents and StackOne. Patch v0.29.1 corrected instruction-update handling in token estimates and conversation search and raised the pydantic-monty minimum to 0.0.23.

Stable v0.30.0 extended the composition/control model with TrajectoryJudge, capability events and explicit observability decisions. Stable v0.31.0 then adds eager streamed CodeMode execution, explicit delegation events, additional compaction/truncation controls, planning-cache durability, consistent FileSystem content hashes, the durable-history reconstruction fix and the CodeMode sandbox boundary corrections described above.

These changes are useful for UHP-adjacent architecture because they show implementation concerns that sit below or beside a transport protocol: capability composition, execution durability, live trajectory control, delegation observability and the exact point at which streamed model output may become a real side effect.

UHP can normalize client-to-harness task and session semantics without standardizing Pydantic’s internal capability graph. Conversely, Pydantic AI Harness can build durable, composable and self-reviewing agents without becoming network-addressable through UHP.

How the boundaries compare

Layer	Primary boundary	Verified Pydantic AI Harness relationship
Pydantic AI Harness	Application / agent → composed runtime capabilities	Native project surface; stable v0.31.0 adds eager streamed CodeMode execution, delegation events and multiple correctness fixes on top of v0.30.0 trajectory/event work.
MCP	Agent → tools/resources/context servers	First-party Pydantic AI capability; ACP-provided MCP servers require explicit wiring.
ACP	Editor/TUI client → agent	First-party experimental ACP server adapter; v0.31.0 includes the approval-status correction for scan-invisible per-run tools.
UHP	Client → UHP server → complete harness	No native adoption established.
HarnessRouter	UHP reference implementation → supported upstream harnesses	Pydantic AI Harness is not in the released ten-backend set at this cutoff.

The practical distinction is scope. Pydantic AI Harness is a Python capability/runtime architecture for constructing an agent. ACP gives an editor/client a way to drive such an agent. MCP supplies tool integrations. UHP addresses a separate network-level contract for complete harness execution.

Evidence boundaries

• Latest stable release: v0.31.0 / d8787b74, published 12 Sep 2026 at 00:54:49 UTC.
• Checked upstream main: d8787b74; it equals the release tag at this cutoff.
• Project maturity label: Alpha in v0.31.0 package metadata.
• Eager CodeMode: stable v0.31.0, opt-in and disabled under durable execution; streamed side effects may precede final run_code dispatch.
• Delegation lifecycle: DelegationStartEvent / DelegationEndEvent are stable harness events, not ACP wire methods.
• ACP correction: PR #849 is released in v0.31.0; it corrects presentation truth without changing the ACP specification.
• Persistence correction: PR #848 is released in v0.31.0; it prevents duplicate reconstructed history for serializing step stores.
• Native MCP use: verified through Pydantic AI capability documentation and stable harness catalogue.
• Native ACP exposure: verified at v0.31.0, but explicitly experimental.
• Native UHP: not established in reviewed primary sources.
• HarnessRouter backend support: not present in the released v0.16.1 ten-backend set.
• UHP conformance evidence: none attributed to Pydantic AI Harness.

Related pages

Read AI SDK Harnesses for another application-side harness abstraction, harness composition for runtime topology, UHP vs ACP for the editor/client boundary, UHP vs MCP for tool/context interoperability, and ecosystem for adoption classifications.

Primary sources

• Pydantic AI Harness repository
• Pydantic AI Harness v0.31.0
• v0.31.0 tag/current-main d8787b74
• v0.31.0 ACP documentation
• v0.31.0 package metadata
• PR #746 — eager streamed execution for CodeMode
• PR #855 — SubAgents delegation lifecycle events
• PR #681 — CodeMode sandbox value-shape fidelity
• PR #849 — correct per-run approval-required ACP calls to pending
• PR #848 — stop serialized snapshot history duplication
• PR #851 — floor Pydantic AI on 2.40.0
• Pydantic AI Harness v0.30.0
• v0.30.0 Trajectory Judge documentation
• HarnessRouter v0.16.1