Pydantic AI Harness

harness yêu thích của agent của bạn, được xây dựng trên Pydantic AI

---

Pydantic AI Harness là khả năng chính thức và thư viện harness cho Pydantic AI. Mọi AI agent Pydantic đều đã có một harness nhẹ: vòng lặp agent typed, bất kỳ mô hình nào, công cụ của riêng bạn, kết quả đầu ra có cấu trúc. Đối với các agent đơn giản như vậy là đủ. Tuy nhiên, hãy thả lỏng một agent đối với công việc phức tạp, kéo dài (sửa cơ sở mã, nghiên cứu một câu hỏi, chạy hàng giờ mà không cần giám sát) và những gì nó cần xung quanh mô hình sẽ tăng lên: một không gian làm việc để hành động, một kế hoạch nó giữ hiện tại, bộ nhớ truyền qua các phiên, subagent để thực hiện công việc, quản lý bối cảnh có thể duy trì trong giờ thứ 10 và thực thi bền vững vẫn tồn tại sau khi khởi động lại. Pydantic AI Harness vận chuyển harness đó.

Mọi thứ ở đây đều là một nguyên thủy: a khả năng, một đơn vị hành vi agent độc lập mà bạn thêm vào capabilities=[...] trên bất kỳ agent nào. Có 30+ trong số đó và các agent hoàn chỉnh như Coder và Researcher là những khả năng được kết hợp: chúng tách rời nhau theo cách chúng đi cùng nhau. Gắn vào một khối duy nhất, soạn ngăn xếp của riêng bạn hoặc bắt đầu từ toàn bộ coding agent và tách nó ra sau.

Bắt đầu nhanh

Cài đặt với uv:

uv add "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('Find out why tests/test_parser.py fails and fix the bug it caught.')
print(result.output)
#> Found it: `parse()` returned None on empty input instead of raising. Fixed in src/parser.py; tests pass now.

Đó là một coding agent hoàn chỉnh: quyền truy cập tệp có nguồn gốc từ không gian làm việc, vỏ được liệt kê cho phép, định hướng repo, lập kế hoạch, một subagent của Explorer chỉ đọc và quản lý bối cảnh tồn tại trong các phiên dài và chạy ở bất kỳ nơi nào mà AI agent Pydantic chạy. agent.to_cli_sync() mở nó dưới dạng cuộc trò chuyện trong terminal của bạn, agent.to_web() trong trình duyệt và Coder được xuất khẩu coder_agent chạy mà không cần ghi tập tin nào cả, kết hợp với clai (Pydantic AI CLI) và uvx:

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

Mọi mô hình đều hoạt động: trao đổi chuỗi cho bất kỳ nhà cung cấp nào. Cần thêm nữa? Thêm khả năng vào danh sách; đây là cùng một lập trình viên trên gpt-5.6-sol, với tìm kiếm trên web và bộ nhớ phiên chéo:

uv add "pydantic-ai-slim[openai]"

from pydantic_ai import Agent
from pydantic_ai.capabilities import WebSearch
from pydantic_ai_harness import Coder, Memory
from pydantic_ai_harness.memory import FileStore

agent = Agent(
    'openai:gpt-5.6-sol',
    capabilities=[
        Coder(),
        WebSearch(),  # look up docs and error messages on the web
        Memory(FileStore('.agent-memory')),  # remembers across sessions
    ],
)

Kỹ năng (của bạn SKILL.md thủ tục, nạp theo yêu cầu; chỉ nó vào một skills/ thư mục và thêm skills bổ sung), Tìm nạp web, Guardrails và Quy trình làm việc động khe cắm theo cách tương tự; Coder README liệt kê những cặp tốt nhất.

Không có phép thuật: đó là tất cả các khả năng

Coder không phải là một khuôn khổ bên trong khuôn khổ; đó là một CombinedCapability gói các khối giống nhau mà bạn có thể sử dụng trực tiếp. Đây chính xác là agent được xuất khẩu coder_agent cung cấp cho bạn, được viết ra từng khối:

from pathlib import Path

from pydantic_ai import Agent
from pydantic_ai_harness import (
    ClearToolResults,
    FileSystem,
    LLM_API_KEY_ENV_PATTERNS,
    Planning,
    RepoContext,
    Shell,
    SubAgent,
    SubAgents,
    ToolOutputLimits,
    WarnNearLimits,
)

allowed_commands = [
    'git', 'rg', 'grep', 'find', 'ls', 'cat', 'sed', 'head', 'tail',
    'python', 'uv', 'pytest', 'ruff', 'make',
]

explorer = SubAgent(
    Agent(
        name='explorer',
        description='Explore the codebase and answer questions without modifying anything',
        instructions='Answer with concrete paths and evidence.',
        capabilities=[
            FileSystem('.', read_only=True),
            RepoContext(workspace_dir=Path('.')),
        ],
    )
)

agent = Agent(
    'anthropic:claude-fable-5',
    name='coder',
    instructions='You are a coding agent built on Pydantic AI.',
    capabilities=[
        FileSystem('.'),  # read/write/edit/search, path-traversal safe
        Shell(  # allowlisted commands, LLM API keys stripped from their environment
            cwd='.',
            allowed_commands=allowed_commands,
            denied_env_patterns=LLM_API_KEY_ENV_PATTERNS,
        ),
        RepoContext(workspace_dir=Path('.')),  # loads AGENTS.md/CLAUDE.md + repo structure
        Planning(),  # structured task plans the model maintains
        SubAgents(agents=[explorer], agent_folders=None),  # delegate exploration off the main context
        ClearToolResults(max_fraction=0.7),  # clears old tool results near the limit
        WarnNearLimits(max_context_fraction=0.9),  # warns the model before it hits limits
        ToolOutputLimits(),  # bounds oversized tool results
    ],
)

Bắt đầu từ harness và loại bỏ những gì bạn không muốn hoặc bắt đầu từ các khối và tích tụ lại; cả hai đều là hạng nhất. Các đối số của hàm tạo (thư mục làm việc, danh sách lệnh cho phép, kích thước cửa sổ) xuyên suốt các khả năng cơ bản.

Khả năng

Mỗi khả năng là một đơn vị độc lập mà bạn có thể tham gia capabilities=[...], và tất cả đều sáng tác, cùng nhau và với chính bạn. Một số đi kèm với pydantic-ai chính nó, phần còn lại với gói này; cột Gói cho biết điều đó. Tổng cộng có hơn 50, được nhóm theo những gì họ cung cấp cho agent của bạn:

harness

Các ngăn agent hoàn chỉnh dưới dạng các khả năng kết hợp thông thường: một lần nhập sẽ cung cấp cho bạn một agent đang hoạt động và bạn có thể tách một trong hai agent đó thành các khối bên dưới.

Môi trường thực thi

Không gian làm việc mà agent hành động trong: các tệp mà nó chỉnh sửa và các lệnh mà nó chạy, cục bộ hoặc tách biệt.

Công cụ & khả năng bản địa

Các kết nối với các hệ thống bên ngoài không gian làm việc của tổng đài viên và các khả năng mà nhà cung cấp thực thi nguyên bản.

Web & nghiên cứu

Tìm và đọc mọi thứ trên web mở.

Lý luận, lập kế hoạch và ủy quyền

Người đại diện suy nghĩ và phân chia công việc như thế nào.

Quản lý bối cảnh

Cách agent sử dụng cửa sổ ngữ cảnh của nó: sự khác biệt giữa một agent xuống cấp trong thời gian dài và một agent không xuống cấp và giữa việc trả tiền cho token N lần hoặc một lần.

Kiến thức và trí nhớ

Những gì agent biết và ghi nhớ, được tải khi có liên quan thay vì được đưa vào mọi lời nhắc.

Kiểm soát & an toàn

Giới hạn những gì agent có thể làm và tuân thủ các hướng dẫn.

Tự mở rộng

runtime thực thi

Bên ngoài vòng lặp: cách các lần chạy vẫn tồn tại, tồn tại khi xảy ra lỗi cũng như được quan sát và định cấu hình trong quá trình sản xuất.

Core cũng cung cấp khả năng tùy chỉnh vòng lặp cho các máy chủ sản xuất: Select Model, Giải quyết ID mẫu, Chuẩn bị công cụ / Chuẩn bị công cụ đầu ra, Công cụ tiền tố, Đặt siêu dữ liệu công cụ, Bao gồm lược đồ trả về công cụ, Lịch sử quy trình, Luồng sự kiện xử lý, Tiêm lại lời nhắc hệ thống và Tăng lỗi bộ lọc nội dung.

Và agent cắm vào bất kỳ giao diện nào: ACP (thử nghiệm, Khai thác) phục vụ nó cho các biên tập viên như Zed qua Giao thức khách hàng agent và lõi cung cấp giao diện người dùng trò chuyện trên web, CLI, bộ điều hợp giao diện người dùng (AG-UI, Vercel AI) và giọng nói thời gian thực.

Các gói cộng đồng mở rộng hệ thống khả năng tương tự hơn nữa; xem khả năng của bên thứ ba.

Soạn từ các khối

Một agent nghiên cứu từ các khả năng thông thường -- đây đúng là Researcher, trừ đi các hướng dẫn mặc định ngắn gọn của nó:

from pydantic_ai import Agent
from pydantic_ai.capabilities import WebFetch, WebSearch
from pydantic_ai_harness import SubAgent, SubAgents, ToolOutputLimits

sub_researcher = SubAgent(
    Agent(
        name='researcher',
        description='Research a focused sub-question on the web and report back with findings and source links',
        capabilities=[WebSearch(local=True), WebFetch(local=True), ToolOutputLimits()],
    )
)

agent = Agent(
    'anthropic:claude-fable-5',
    capabilities=[
        WebSearch(local=True),  # native provider search, DuckDuckGo fallback elsewhere
        WebFetch(local=True),  # read the pages behind the results, native or local
        SubAgents(agents=[sub_researcher], agent_folders=None),
        ToolOutputLimits(),  # fetched pages don't flood the context
    ],
)

result = agent.run_sync('What changed in the top three Python agent frameworks this month? Cite sources.')
print(result.output)
#> ...

Mọi thứ đều có thể quan sát được: logfire.instrument_pydantic_ai() cung cấp cho bạn dấu vết đầy đủ của mỗi lần chạy: mọi lệnh gọi mô hình và lệnh gọi công cụ, với token và theo dõi chi phí. Đó là OpenTelemetry tiêu chuẩn, vì vậy mọi chương trình phụ trợ OTLP đều hoạt động; Cháy rừng là cách dễ nhất để thấy nó trong quá trình phát triển.

Khi nào bạn cần harness?

"Khai thác" là thuật ngữ của trường cho mọi thứ xung quanh mô hình biến nó thành một agent: vòng lặp, công cụ, quản lý bối cảnh. Hãy tiếp cận gói này khi agent của bạn cần làm nhiều việc hơn vỏ bọc khai thác tinh gọn của lõi: chạm vào tệp, chạy mã, duyệt, ghi nhớ, ủy quyền hoặc duy trì mạch lạc trong suốt runtime kéo dài hàng giờ. Ranh giới giữa các gói là cơ học, không phải là cấp độ trưởng thành: cốt lõi cung cấp các khả năng yêu cầu hỗ trợ mô hình hoặc khung (các công cụ gốc của nhà cung cấp như tạo hình ảnh, các API của nhà cung cấp như nén, tích hợp vòng lặp sâu như tìm kiếm công cụ và các nguyên tắc cơ bản như suy nghĩ, MCP và tìm kiếm trên web) và Harness vận chuyển mọi thứ khác, dưới dạng một gói riêng biệt để các khả năng có thể lặp lại theo tốc độ di chuyển của trường trong khi bản thân Pydantic AI vẫn gọn gàng.

Cài đặt

uv add pydantic-ai-harness

Cài đặt này pydantic-ai-slim với nó, nên nó tự hoạt động; bạn không cần phải cài đặt riêng Pydantic AI. Các nhà cung cấp mô hình và CLI đến từ các tính năng bổ sung chuyển sang Pydantic AI: pydantic-ai-harness[anthropic], [cli]. Một số khả năng cần có phần bổ sung riêng cho các phần phụ thuộc tùy chọn; trang của mỗi khả năng cung cấp dòng cài đặt chính xác. Yêu cầu Python 3.10+.

Xây dựng của riêng bạn

Khả năng là điểm mở rộng chính cho Pydantic AI và mọi khả năng trong repo này đều đóng vai trò là một ví dụ hoạt động. Xuất bản một gói độc lập? Sử dụng pydantic-ai-<name> quy ước đặt tên; xem Gói khả năng xuất bản.

Đóng góp

Chúng tôi hoan nghênh những đóng góp về năng lực:

1. Bắt đầu với một vấn đề. Mở một yêu cầu về khả năng để chúng ta có thể thảo luận về cách tiếp cận và mức độ ưu tiên trước khi viết mã.
2. Sau đó mở PR và liên kết vấn đề. Chúng tôi xem xét dựa trên sự quan tâm của cộng đồng; số phiếu ủng hộ cả hai đều được tính.
3. Đừng theo đuổi CI xanh. Hãy áp dụng phương pháp này và cho chúng tôi biết; chúng tôi có thể liên hệ với chi nhánh của bạn hoặc theo dõi và bạn sẽ được ghi nhận là tác giả gốc. (Xem Hướng dẫn đóng góp Pydantic AI)

Lưu ý: PR sửa đổi pyproject.toml hoặc uv.lock từ các thành viên không thuộc nhóm được CI tự động đóng để ngăn ngừa rủi ro chuỗi cung ứng. Nếu bạn cần một phần phụ thuộc mới, mở một vấn đề.

Phát triển

make install   # install dependencies
make format    # ruff format
make lint      # ruff check
make typecheck # pyright strict
make test      # pytest
make testcov   # pytest with 100% branch coverage

Chính sách phiên bản

Pydantic AI Harness sử dụng phiên bản 0.x và đó là tuyên bố về độ ổn định của API, chứ không phải mức độ trưởng thành: các khả năng này được kiểm tra từ đầu đến cuối và được sử dụng trong sản xuất nhưng API của chúng vẫn có thể di chuyển giữa các bản phát hành nhỏ (0,1 -> 0,2): các tham số được đổi tên, mặc định đã thay đổi, các API được cơ cấu lại, luôn có cảnh báo không dùng nữa nếu thực tế. Các bản phát hành bản vá sẽ không cố ý phá vỡ hành vi hiện có và mọi thay đổi vi phạm đều được ghi lại trong ghi chú phát hành kèm theo hướng dẫn di chuyển mà agent của bạn có thể làm theo. Giữ harness ở một gói riêng biệt với Pydantic AI, có chính sách phiên bản chặt chẽ hơn, là thứ cho phép các khả năng lặp lại với tốc độ mà trường di chuyển.

Một phần của ngăn xếp Pydantic

Mọi thứ bạn cần để vận chuyển các AI agent cấp sản xuất:

• Pydantic AI: khung agent an toàn loại
• Pydantic Logfire: Ưu tiên AI, khả năng quan sát toàn bộ ngăn xếp
• Cổng AI Logfire: proxy LLM thống nhất
• Pydantic Evals: đánh giá bất kỳ hàm Python nào, bao gồm các agent
• genai-prices: dữ liệu giá mô hình, được cập nhật

Giấy phép

MIT; xem GIẤY PHÉP.