Harness architecture
Pydantic AI Harness and UHP
Pydantic AI Harness is Pydantic's official capability and harness library for building long-running agents from composable Python capabilities. It has first-party MCP integration through Pydantic AI and an experimental ACP server, but no reviewed primary source establishes native UHP adoption or a HarnessRouter backend.
Status first
Section titled “Status first”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.29.1, published 8 September 2026 at 04:15:22 UTC, with tag commit c897c4e8bcb7f0e5a8968aaccdb0f8edf42fe504.
The 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.
What the harness actually standardizes
Section titled “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.29.1 README describes a 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.mdplus 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.mdprocedures; - 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.
MCP is a tool-capability boundary
Section titled “MCP is a tool-capability boundary”The v0.29.1 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
Section titled “Experimental ACP server”Pydantic AI Harness ships a first-party experimental Agent Client Protocol (ACP) adapter under pydantic_ai_harness.experimental.acp. The upstream documentation explicitly warns that the capability 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 explicitly describe those two 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
Section titled “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. It also improved nested summarization streaming.
Patch v0.29.1 then corrected instruction-update handling in token estimates and conversation search and raised the pydantic-monty minimum to 0.0.23.
These changes are useful for UHP-adjacent architecture because they show two implementation concerns that sit below or beside a transport protocol:
- capability composition — how multiple planning, subagent, tool, context and policy modules coexist inside one agent runtime;
- execution durability — how work survives runtime/process boundaries independently of how an external client addresses the harness.
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 agents without becoming network-addressable through UHP.
How the boundaries compare
Section titled “How the boundaries compare”| Layer | Primary boundary | Verified Pydantic AI Harness relationship |
|---|---|---|
| Pydantic AI Harness | Application / agent → composed runtime capabilities | Native project surface. |
| 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. |
| 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
Section titled “Evidence boundaries”- Latest stable release:
v0.29.1/c897c4e8, published 8 Sep 2026 UTC. - Project maturity label: Alpha in package metadata.
- Native MCP use: verified through Pydantic AI capability documentation and stable harness catalogue.
- Native ACP exposure: verified, but explicitly experimental.
- Native UHP: not established in reviewed primary sources.
- HarnessRouter backend support: not present in the released
v0.15.6ten-backend set. - UHP conformance evidence: none attributed to Pydantic AI Harness.
Related pages
Section titled “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.