pydantic/pydantic-ai-harness

Batteries for your Pydantic AI agent.

TL;DR

Pydantic AI Harness is a library of plug‑in‑style capabilities that turn a Pydantic AI agent into a fully‑featured autonomous worker. It bundles tools for file‑system access, shell commands, web search, memory, planning, sub‑agents, safety guards, durable execution, and many SaaS integrations. You compose the pieces you need (e.g., the ready‑made Coder harness) and drop them into an Agent’s capabilities list.

What it does

  • Provides a catalog of 50+ capabilities – each a self‑contained unit (tool, memory store, guard, etc.) that can be added to any pydantic_ai.Agent.
  • Ready‑made harnesses such as:
    • Coder – file editing, persistent shell, delegation, and autonomous coding workflow.
    • Researcher – web‑search, page fetch, sub‑researcher delegation.
  • Execution environment helpers: safe file‑system access, sandboxed shells, optional Modal cloud sandbox.
  • Tool integrations for GitHub, Linear, Notion, Google Workspace, Slack, and many other SaaS services via MCP or hosted APIs.
  • Web & research utilities: DuckDuckGo fallback search, Exa, You.com, Playwright browser control, etc.
  • Planning & orchestration – model‑owned task plans, sub‑agents, dynamic workflows, background concurrent tools.
  • Context management – compaction, tool‑output limits, code‑mode execution, sliding‑window trimming.
  • Memory & knowledge – persistent notebooks, conversation search, on‑demand skill loading, repo‑context hints.
  • Safety & control – guardrails, prompt‑injection defense, spend limits, human‑in‑the‑loop tool approval, trajectory judging.
  • Self‑extension – agents can generate and persist new capabilities during a run.
  • Durable execution – runs survive restarts via Temporal, DBOS, Prefect, Airflow, etc.; AWS Lambda checkpointing; step persistence back‑ends.
  • Observability – OpenTelemetry spans, Logfire integration, managed prompts.

Who it’s for

  • Developers building autonomous agents that need to run for long periods (e.g., fixing a codebase, researching a topic) and require robust tooling, memory, and safety.
  • Teams that want to compose custom AI‑agent stacks without writing low‑level plumbing; they simply import the needed capabilities.
  • Ops / production teams that need durable, observable, and cost‑controlled runs.

How to get started

# using uv (recommended)
uv add "pydantic-ai-harness[anthropic]"
# or with pip
pip install "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('Fix the bug in tests/test_parser.py')
print(result.output)

For a full CLI experience:

uvx --with "pydantic-ai-harness[coder]" clai -a pydantic_ai_harness.coder:coder_agent -m anthropic:claude-fable-5

Add more capabilities as needed, e.g., memory or web search:

from pydantic_ai.capabilities import WebSearch
from pydantic_ai_harness.memory import FileStore
from pydantic_ai_harness import Memory

agent = Agent(
    'openai:gpt-5.6-sol',
    capabilities=[Coder(), WebSearch(), Memory(FileStore('.agent-memory'))],
)

What’s inside (selected highlights)

Category Example Capability Core idea
Harnesses Coder, Researcher Pre‑built stacks you can drop in.
Filesystem FileSystem Safe read/write/list under a root, optional ripgrep.
Shell Shell Execute commands with allow/deny lists, timeouts, persistent state.
SaaS integrations GitHub, Slack, Notion, Linear … Direct API‑level access via MCP or hosted servers.
Web WebSearch, Exa, Playwright Search the web, fetch pages, drive a real browser.
Planning Planning Model‑owned task plan with live reminders.
Memory Memory (FileStore, Postgres, etc.) Persistent, searchable notebook across runs.
Safety Guardrails, PromptInjectionDefender, Spend Validate inputs/outputs, enforce cost limits, block risky tool results.
Durability Durable execution, Step Persistence, AWS Lambda durability Checkpoint runs, survive restarts, integrate with workflow engines.
Observability Instrumentation, Logfire MCP OpenTelemetry spans, Logfire tracing.

Why it matters

Pydantic AI already gives you a typed agent loop and tool‑calling support. Pydantic AI Harness turns that into a production‑ready platform: you can build agents that edit code, browse the web, interact with SaaS tools, remember past work, stay within budgets, and keep running even if the process crashes. All pieces are modular, typed, and documented, letting you start with a ready‑made harness and then peel away or replace individual capabilities to fit your exact use‑case.

Links & resources

All information above is taken directly from the repository’s README; no additional features are inferred.

Related

  • Project
    DougTrajano/pydantic-ai-skills

    A companion library for Pydantic AI that enables agents to load modular skills from local or remote registries, execute bundled scripts, and manage resources via progressive disclosure.

  • Project
    chujianyun/skills

    A Chinese‑language repo that bundles dozens of reusable “Agent Skills” – small, documented plugins for Claude Code and similar LLM‑agent platforms. Skills cover wiki look‑ups, prompt optimisation, career assessments, diagram generation, document interpretation, audio‑to‑text, image watermarking, web‑scraping, and service run‑books. They are organized under `skills/`, registered in `config/skills.json`, and installed via Claude Code’s marketplace, an installer agent, or the `openskills` CLI.

  • Project
    pydantic/pydantic-ai

    A typed Python AI SDK for building extensible agents with structured outputs, durable execution, and support for multiple model providers and interfaces.

  • Project
    BuilderIO/skills

    BuilderIO / skills is a plug‑in catalog that adds ready‑made slash‑commands (e.g., `/factory‑collect`, `/visual‑plan`, `/rewind`) to LLM agents. The skills let agents safely read from Slack, GitHub, Sentry, local UI, etc., generate visual plans/recaps, enforce policy‑gated PR workflows, and keep expensive models in the loop only for high‑level judgment. Install via `npx @agent-native/skills@latest add`, then invoke commands inside any supported agent (Claude, Codex, ChatGPT, etc.).

  • Project
    strands-agents/tools

    Strands Agents Tools is a Python library that supplies a large catalogue of ready‑to‑use tools (file I/O, shell execution, web search, API calls, AWS access, memory stores, image/video generation, browser/desktop automation, multi‑agent orchestration, etc.) so LLM‑based agents can act on the real world. Install via `pip install strands‑agents‑tools` (optional extras for specific capabilities) and attach the desired tools to a Strands `Agent` instance. The package is experimental and emphasizes security reviews before production use.