Pydantic AI Harness – Pydantic AI 에이전트를 위한 공식 capabilities 라이브러리

왜 필요한가
설치
주요 capabilities
Tools & Execution
Context Management
Memory & Persistence
사용 예시
CodeMode 상세
커뮤니티 패키지 추적
라이선스
관련 문서

Pydantic AI Harness는 Pydantic AI 프레임워크의 공식 capabilities 라이브러리로, Pydantic AI 팀이 직접 유지 관리한다. Pydantic AI의 capabilities와 hooks API를 통해 에이전트에 도구·라이프사이클 훅·지시사항·모델 설정을 추가하는 표준화된 방법을 제공한다. pip install pydantic-ai-harness 한 줄로 프로덕션 에이전트에 필요한 핵심 기능을 즉시 사용할 수 있다.

왜 필요한가

Pydantic AI 코어는 프레임워크 변경이 필요한 저수준 기능을 담당한다. Harness는 그 위에서 실제 에이전트를 구축할 때 반복적으로 필요한 기능들을 미리 구현해 제공한다. Claude Code, Codex 등 주요 코딩 에이전트를 연구해 실제 프로덕션 에이전트에 필요한 기능 지도를 작성하고 추적한다.

설치

uv add pydantic-ai-harness

# CodeMode (Monty 샌드박스 포함)
uv add "pydantic-ai-harness[codemode]"

# Logfire 기반 관리형 프롬프트
uv add "pydantic-ai-harness[logfire]"

Python 3.10+ 및 pydantic-ai-slim>=1.95.1 필요.

주요 capabilities

Tools & Execution

Capability	설명	상태
CodeMode	Monty 샌드박스의 `run_code`로 Python 실행. 여러 도구 호출을 단일 코드 실행으로 대체	완료
Tool Search	대형 도구 세트의 점진적 발견	완료
File System	경로 탐색 방지 기능 포함 파일 읽기·쓰기·편집·검색	완료
Shell	허용·거부 목록과 타임아웃을 적용한 셸 명령 실행	완료
Repo Context Injection	CLAUDE.md/AGENTS.md 및 저장소 구조 자동 로드	개발 중
Verification Loop	편집 후 테스트 실행 및 실패 자동 수정	개발 중

Context Management

Capability	설명	상태
Sliding Window	토큰 한도 유지를 위한 대화 기록 트리밍	개발 중
Context Compaction	LLM 기반 오래된 메시지 요약	개발 중
Tool Output Management	대형 도구 출력 잘라내기·요약·스필	개발 중
System Reminders	지시 드리프트 방지를 위한 주기적 리마인더 주입	개발 중

Memory & Persistence

Capability	설명	상태
Memory	세션 간 지속되는 키-값 메모리	개발 중
Session Persistence	전체 대화 상태 저장·복원	개발 중

사용 예시

from pydantic_ai import Agent
from pydantic_ai.capabilities import MCP, Thinking, ToolSearch, WebSearch
from pydantic_ai_harness import CodeMode

agent = Agent(
    model="claude-sonnet-4-6",
    capabilities=[
        CodeMode(),        # 샌드박스 Python 실행
        ToolSearch(),      # 점진적 도구 발견
        WebSearch(),       # 웹 검색
        MCP(...),          # MCP 서버 통합
    ]
)

CodeMode 상세

CodeMode는 Pydantic AI Harness의 핵심 capability다. Monty 샌드박스에서 Python 코드를 실행하는 run_code 도구를 에이전트에 추가한다. 여러 도구를 순차 호출하는 대신 코드를 작성해 단일 실행으로 처리하므로 토큰과 레이턴시를 절약한다.

uv add "pydantic-ai-harness[codemode]"

from pydantic_ai_harness import CodeMode

agent = Agent(
    model="claude-sonnet-4-6",
    capabilities=[CodeMode()]
)

커뮤니티 패키지 추적

Pydantic AI Harness는 커뮤니티 대안 패키지도 함께 추적한다. pydantic-ai-backend, pydantic-deep, summarization-pydantic-ai 등이 각 기능 영역의 대안으로 제시된다.

라이선스

MIT

AI Sparkup