pydantic-ai-harness

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Building with Pydantic AI Harness

使用Pydantic AI Harness进行开发

Pydantic AI Harness is the official capability library for Pydantic AI. Capabilities that need model or framework support — and those fundamental to every agent — live in core

pydantic-ai

; optional, batteries-included capabilities live here. Both are composed onto an agent through the same

capabilities=[...]

API.

This skill covers the capabilities shipped by

pydantic-ai-harness

. For the core framework — agents, tools, structured output, hooks, and testing — use the

building-pydantic-ai-agents

skill instead.

Pydantic AI Harness是Pydantic AI的官方功能库。需要模型或框架支持的功能——以及每个Agent必备的基础功能——都位于核心

pydantic-ai

库中；可选的一站式功能则在此库中。两者均可通过相同的

capabilities=[...]

API集成到Agent中。

本技能涵盖

pydantic-ai-harness

提供的功能。若需了解核心框架（Agent、工具、结构化输出、钩子和测试），请使用

building-pydantic-ai-agents

技能。

When to Use This Skill

何时使用本技能

Invoke this skill when:

The user mentions
```
pydantic-ai-harness
```
,
```
CodeMode
```
, code mode, or the Monty sandbox
An agent makes many sequential tool calls that could collapse into one sandboxed Python execution
The user wants the model to write Python that loops, branches, aggregates, or parallelizes tool calls with
```
asyncio.gather
```
The user asks to sandbox or constrain the code an agent runs

Do not use this skill for:

Core Pydantic AI usage — building agents, adding tools, structured output, streaming, or testing (use
```
building-pydantic-ai-agents
```
)
Capabilities that ship in core
```
pydantic-ai
```
, such as web search, tool search, and thinking
The Pydantic validation library on its own (
```
pydantic
```
/
```
BaseModel
```
without agents)

在以下场景调用本技能：

用户提及
```
pydantic-ai-harness
```
、
```
CodeMode
```
、code mode或Monty沙箱
Agent进行多次连续工具调用，可合并为一次沙箱化Python执行
用户希望模型编写可通过
```
asyncio.gather
```
实现循环、分支、聚合或并行化工具调用的Python代码
用户要求对Agent运行的代码进行沙箱化或限制

请勿在以下场景使用本技能：

Pydantic AI核心用法——构建Agent、添加工具、结构化输出、流式传输或测试（请使用
```
building-pydantic-ai-agents
```
）
```
pydantic-ai
```
核心库提供的功能，如网页搜索、工具搜索和思考功能
单独使用Pydantic验证库（无Agent的
```
pydantic
```
/
```
BaseModel
```
）

Supported Capabilities

支持的功能

Capability	Description	Reference
`CodeMode`	Wraps eligible tools into a single sandboxed `run_code` tool so the model orchestrates them in Python	Code Mode

More capability areas are tracked in the capability matrix; as they stabilize, this skill grows to cover them.

功能	描述	参考文档
`CodeMode`	将符合条件的工具封装为单个沙箱化 `run_code` 工具，以便模型通过Python编排这些工具	Code Mode

更多功能领域在功能矩阵中跟踪；待功能稳定后，本技能将逐步覆盖这些内容。

Install

安装

bash

uv add pydantic-ai-harness

Each capability declares its own extra. Code Mode needs the Monty sandbox:

bash

uv add "pydantic-ai-harness[codemode]"   # `code-mode` is also accepted as an alias

Requires Python 3.10+ and

pydantic-ai-slim>=1.95.1

bash

uv add pydantic-ai-harness

每个功能都有自己的扩展依赖。Code Mode需要Monty沙箱：

bash

uv add "pydantic-ai-harness[codemode]"   # `code-mode`也可作为别名使用

要求Python 3.10+和

pydantic-ai-slim>=1.95.1

。

Quick Start

快速开始

A harness capability is added to the agent like any other. Here

CodeMode

wraps an MCP server's tools into a single

run_code

tool that the model drives with Python.

python

from pydantic_ai import Agent
from pydantic_ai.capabilities import MCP  # MCP ships in core pydantic-ai

from pydantic_ai_harness import CodeMode

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    capabilities=[
        # native=False routes the MCP tools through a local toolset so CodeMode can wrap them.
        # Without it, providers with native MCP run the tools server-side and bypass the sandbox.
        MCP('https://hn.caseyjhand.com/mcp', native=False),
        CodeMode(),
    ],
)

result = agent.run_sync(
    'Across the top and best Hacker News feeds, find the most-discussed story with at '
    'least 100 points and summarize its comment thread in one paragraph.'
)
print(result.output)
#> The most-discussed story clearing 100 points is ...

Instead of one model round-trip per tool call, the model writes a single Python script that fetches both feeds with

asyncio.gather

, dedupes and ranks them in plain Python, and pulls the winning thread — collapsing many calls into one

run_code

可像添加其他功能一样，将Harness功能添加到Agent中。以下示例中，

CodeMode

将MCP服务器的工具封装为单个

run_code

工具，由模型通过Python驱动。

python

from pydantic_ai import Agent
from pydantic_ai.capabilities import MCP  # MCP属于pydantic-ai核心库

from pydantic_ai_harness import CodeMode

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    capabilities=[
        # native=False将MCP工具路由到本地工具集，以便CodeMode封装它们。
        # 若不设置此参数，支持原生MCP的提供商将在服务器端运行工具，从而绕过沙箱。
        MCP('https://hn.caseyjhand.com/mcp', native=False),
        CodeMode(),
    ],
)

result = agent.run_sync(
    '在Hacker News的头条和最佳feed中，找到讨论量最多且至少获得100分的文章，并将其评论线程总结为一段话。'
)
print(result.output)
#> 获得100分以上且讨论量最多的文章是 ...

无需每次工具调用都进行一轮模型交互，模型只需编写单个Python脚本，通过

asyncio.gather

获取两个feed，用纯Python去重并排序，然后提取最优线程——将多次调用合并为一次

run_code

执行。

Key Practices

关键实践

Confirm a harness capability is actually needed. If core Pydantic AI tools and capabilities are enough, use the
```
building-pydantic-ai-agents
```
skill instead — don't reach for the harness by default.
Read the reference before writing code. Each capability has its own configuration, constraints, and gotchas — load the linked reference (e.g. Code Mode) first.
Install the capability's extra. Importing
```
CodeMode
```
without
```
pydantic-ai-harness[codemode]
```
raises an
```
ImportError
```
; the Monty sandbox is an optional dependency.

确认是否确实需要Harness功能。若Pydantic AI核心工具和功能已足够，请使用
```
building-pydantic-ai-agents
```
技能——不要默认使用Harness。
编写代码前阅读参考文档。每个功能都有自己的配置、约束和注意事项——请先查看关联的参考文档（如Code Mode）。
安装功能对应的扩展依赖。若未安装
```
pydantic-ai-harness[codemode]
```
就导入
```
CodeMode
```
，会触发
```
ImportError
```
；Monty沙箱是可选依赖。

Common Gotchas

常见陷阱

native=True
tools bypass
CodeMode
. Provider-native MCP servers and web search execute server-side, so
```
run_code
```
never sees them. Construct them with
```
native=False
```
to keep them local and wrappable.
The Monty sandbox is a Python subset. No class definitions, no third-party imports, and only a small stdlib allowlist — read Code Mode before debugging generated code that fails to run.
CodeMode
needs its extra. Install
```
pydantic-ai-harness[codemode]
```
, not the bare package.

native=True
的工具会绕过
CodeMode
。提供商原生的MCP服务器和网页搜索在服务器端执行，因此
```
run_code
```
无法感知它们。请将其构造为
```
native=False
```
，以保持本地可封装状态。
Monty沙箱仅支持Python子集。不允许类定义、第三方导入，仅支持一小部分标准库白名单——调试无法运行的生成代码前，请阅读Code Mode。
CodeMode
需要对应的扩展依赖。请安装
```
pydantic-ai-harness[codemode]
```
，而非基础包。