pydantic/pydantic-ai-harness

TL;DR

Pydantic AI Harness는 Pydantic AI 에이전트를 완전한 기능을 갖춘 자율 워커로 변환하는 플러그인 스타일의 capabilities 라이브러리입니다. 파일 시스템 액세스, 셸 명령, 웹 검색, 메모리, 계획, 하위 에이전트, 안전 가드, 지속 실행, 그리고 많은 SaaS 통합을 위한 도구가 번들로 제공됩니다. 필요한 조각(예: 기성 Coder 하네스)을 구성하여 Agent의 capabilities 목록에 추가하면, 코드 편집, 웹 탐색, 서비스 상호 작용, 과거 작업 기억, 비용 한도 유지, 재시작 후에도 지속되는 자율 에이전트를 만들 수 있습니다.

기능

50개 이상의 capabilities 카탈로그 제공 – 각각은 자체 포함된 단위(도구, 메모리 저장소, 가드 등)로, 모든 pydantic_ai.Agent에 추가할 수 있습니다.
기성 하네스에는 다음이 포함됩니다:
- Coder – 파일 편집, 지속 셸, 위임, 자율 코딩 워크플로우.
- Researcher – 웹 검색, 페이지 가져오기, 하위 연구자 위임.
실행 환경 헬퍼 – 안전한 파일 시스템 액세스, 샌드박스 셸, 선택적 Modal 클라우드 샌드박스.
도구 통합 – GitHub, Linear, Notion, Google Workspace, Slack 및 기타 많은 SaaS 서비스에 대한 MCP 또는 호스팅 API를 통한 통합.
웹 및 연구 유틸리티 – DuckDuckGo 폴백 검색, Exa, You.com, Playwright 브라우저 제어 등.
계획 및 오케스트레이션 – 모델 소유 작업 계획, 하위 에이전트, 동적 워크플로우, 백그라운드 동시 도구.
컨텍스트 관리 – 압축, 도구 출력 제한, 코드 모드 실행, 슬라이딩 윈도우 트리밍.
메모리 및 지식 – 영구 노트북, 대화 검색, 주문형 스킬 로딩, 리포지토리 컨텍스트 힌트.
안전 및 제어 – 가드레일, 프롬프트 인젝션 방어, 비용 한도, 인간 개입 도구 승인, 궤적 판단.
자체 확장 – 에이전트가 실행 중에 새로운 capabilities를 생성하고 영구 저장할 수 있습니다.
지속 실행 – Temporal, DBOS, Prefect, Airflow 등을 통한 재시작 후에도 실행 지속; AWS Lambda 체크포인트; 단계 영구 저장 백엔드.
관찰 가능성 – OpenTelemetry 스팬, Logfire 통합, 관리형 프롬프트.

대상 사용자

장기간 실행해야 하는 자율 에이전트를 구축하는 개발자(예: 코드베이스 수정, 주제 연구)로, 강력한 도구, 메모리, 안전이 필요한 경우.
저수준 배관을 작성하지 않고 맞춤형 AI 에이전트 스택을 구성하려는 팀 – 필요한 capabilities를 가져오기만 하면 됩니다.
지속성, 관찰 가능성, 비용 제어가 필요한 운영/프로덕션 팀.

시작하기

# uv 사용 (권장)
uv add "pydantic-ai-harness[anthropic]"
# 또는 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)

전체 CLI 경험을 위해:

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

필요에 따라 메모리나 웹 검색과 같은 더 많은 capabilities를 추가하세요:

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'))],
)

내부 구성 (선별된 하이라이트)

카테고리	예시 capability	핵심 아이디어
하네스	`Coder`, `Researcher`	드롭인할 수 있는 사전 구축 스택.
파일 시스템	`FileSystem`	루트 아래 안전한 읽기/쓰기/목록, 선택적 ripgrep.
셸	`Shell`	허용/거부 목록, 타임아웃, 지속 상태를 가진 명령 실행.
SaaS 통합	`GitHub`, `Slack`, `Notion`, `Linear` …	MCP 또는 호스팅 서버를 통한 직접 API 수준 액세스.
웹	`WebSearch`, `Exa`, `Playwright`	웹 검색, 페이지 가져오기, 실제 브라우저 제어.
계획	`Planning`	실시간 리마인더가 있는 모델 소유 작업 계획.
메모리	`Memory` (FileStore, Postgres 등)	실행 간 영구적이고 검색 가능한 노트북.
안전	`Guardrails`, `PromptInjectionDefender`, `Spend`	입력/출력 검증, 비용 한도 강제, 위험한 도구 결과 차단.
지속성	`Durable execution`, `Step Persistence`, `AWS Lambda durability`	실행 체크포인트, 재시작 생존, 워크플로우 엔진 통합.
관찰 가능성	`Instrumentation`, `Logfire MCP`	OpenTelemetry 스팬, Logfire 추적.

중요성

Pydantic AI는 이미 타입이 지정된 에이전트 루프와 도구 호출 지원을 제공합니다. Pydantic AI Harness는 그것을 프로덕션 준비가 된 플랫폼으로 전환합니다: 코드를 편집하고, 웹을 탐색하고, SaaS 도구와 상호 작용하고, 과거 작업을 기억하고, 예산 내에서 유지하고, 프로세스가 중단되어도 계속 실행되는 에이전트를 구축할 수 있습니다. 모든 조각은 모듈식이고 타입이 지정되며 문서화되어 있어, 기성 하네스로 시작한 다음 개별 capabilities를 분리하거나 교체하여 정확한 사용 사례에 맞출 수 있습니다.

링크 및 리소스

문서: https://pydantic.dev/docs/ai/harness
GitHub 저장소(아카이브됨): https://github.com/pydantic/pydantic-ai-harness
메인 Pydantic AI 저장소: https://github.com/pydantic/pydantic-ai
PyPI 패키지: https://pypi.org/project/pydantic-ai-harness/
Slack 커뮤니티: https://logfire.pydantic.dev/docs/join-slack/

위의 모든 정보는 저장소의 README에서 직접 가져온 것이며, 추가 기능은 추론되지 않았습니다.