/pydantic-ai-harness

name: pydantic-ai-harness
description: Extend Pydantic AI agents with capabilities from pydantic-ai-harness -- the Coder coding agent, file and shell tools in local or sandboxed workspaces (Modal, E2B, Sprites, smolvm), Code Mode, sub-agents and planning, memory and skills, context compaction, guardrails and spend limits, web research and browsers, hosted SaaS integrations, step persistence, and background agents on Render Workflows. Use when the user mentions pydantic-ai-harness or pydantic_ai_harness, imports a harness capability such as Coder, CodeMode, FileSystem, Shell, SubAgents, Memory, or ToolGuardrail, or wants a Pydantic AI agent that edits files, runs commands or agent-written Python, delegates, remembers, manages long context, stays within limits, or runs model and tool operations as chained Render task runs.
license: MIT
compatibility: Requires Python 3.11+
metadata:
  version: "0.2.0"
  author: pydantic

Building with Pydantic AI Harness

Pydantic AI Harness is the official capability library for Pydantic AI. Core `pydantic-ai` ships the agent loop and the capabilities that need model or framework support (thinking, web search, MCP, tool search, workspaces, and provider-native compaction); the harness ships optional capabilities for longer, more involved work: a coding stack, sandboxes, delegation, memory, context management, and controls. Harness capabilities go in `Agent(capabilities=[...])` and compose with each other and with core capabilities; a few supporting pieces, such as media stores and the ACP server entry point, are used directly instead.

This skill covers `pydantic-ai-harness`. For the core framework -- agents, tools, structured output, hooks, workspaces, and testing -- use the `building-pydantic-ai-agents` skill.

When to Use This Skill

Invoke this skill when:

• The user mentions `pydantic-ai-harness`, or code imports `pydantic_ai_harness`
• The user wants a coding agent, or an agent that reads and edits files or runs shell commands, locally or in a sandbox
• An agent should run model-written Python that calls its tools (Code Mode)
• The user wants sub-agents, planning, a model-written workflow over sub-agents, or a stronger model to advise a cheaper one
• A long-running agent needs memory across sessions, context compaction, tool output limits, or `SKILL.md` skills loaded on demand
• The user wants guardrails, prompt-injection screening, model-based tool-call decisions, spend limits, human questions mid-run, or a second model reviewing the run
• The user wants web research beyond core web search (Exa, You.com), a real browser, or a hosted integration such as GitHub, Linear, Notion, Slack, or Google Workspace
• A run must be saved, resumed, or forked, or an agent should be served over ACP
• The user is using or evaluating Render Workflows for background agent jobs with separate retries, timeouts, and compute settings for model requests and tool calls

Do **not** use this skill for:

• Core Pydantic AI usage -- agents, tools, output types, streaming, hooks, core capabilities, or testing basics (use `building-pydantic-ai-agents`)
• Migrating an application built on LangChain Deep Agents (use `migrating-deep-agents-to-pydantic-ai-harness`)
• The Pydantic validation library on its own (`pydantic`/`BaseModel` without agents)

Quick-Start Patterns

Build a Coding Agent

`Coder` is a complete coding agent as one capability. It needs a workspace: `LocalWorkspace('.')` runs its file tools and commands on this machine, in this directory, with no isolation.

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

from pydantic_ai import Agent
from pydantic_ai.capabilities import LocalWorkspace

from pydantic_ai_harness 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.')
print(result.output)

`Coder` gives the model `read_file`, `write_file`, `edit_file`, `list_files`, `grep`, `shell`, and `delegate_task`, plus repository instructions and context controls. Pass `instructions=` to add your own guidance.

Run the Same Agent in a Sandbox

Swap the workspace capability; the rest of the agent is unchanged.

uv add "pydantic-ai-harness[coder,modal,anthropic]"

from pydantic_ai import Agent

from pydantic_ai_harness import Coder
from pydantic_ai_harness.modal_sandbox import ModalSandbox

agent = Agent('anthropic:claude-opus-5-5', capabilities=[ModalSandbox(), Coder()])

`E2BSandbox`, `SpritesSandbox`, and `SmolSandbox` (a local microVM) work the same way. See [Coding and Workspaces](./references/CODING-AND-WORKSPACES.md) for credentials, lifetimes, and sharing a workspace between runs.

Compose Your Own Stack

`Coder` is built from ordinary capabilities. Compose them yourself to change any setting, such as a read-only file view and a command allowlist:

from pydantic_ai import Agent
from pydantic_ai.capabilities import LocalWorkspace
from pydantic_ai.models.test import TestModel

from pydantic_ai_harness import ClearToolResults, FileSystem, Planning, Shell

model = TestModel(call_tools=[])
agent = Agent(
    model,
    capabilities=[
        LocalWorkspace('.'),
        FileSystem(read_only=True),
        Shell(allowed_commands=['git', 'pytest']),
        Planning(),
        ClearToolResults(max_fraction=0.7),
    ],
)
agent.run_sync('Review the repository.')
print(sorted(t.name for t in model.last_model_request_parameters.function_tools))
"""
[
    'add_task',
    'check_command',
    'file_info',
    'find_files',
    'list_directory',
    'read_file',
    'read_plan',
    'remove_task',
    'run_command',
    'search_files',
    'start_command',
    'stop_command',
    'update_task_status',
    'update_task_statuses',
    'write_plan',
]
"""

The standalone `FileSystem` and `Shell` tool names differ from `Coder`'s six to