Pydantic AI Harness: Pydantic AI 에이전트를 위한 공식 기능 라이브러리

9bow · 6월 4, 2026, 12:30오전

Pydantic AI Harness 소개

LLM 에이전트를 실제 제품에 투입하려면 모델 호출 그 자체보다, 그 주위를 감싸는 장치들이 더 많은 일을 합니다. 도구 묶음, 실행 수명주기 훅(hook), 지시문, 모델 설정처럼 에이전트가 할 수 있는 일을 늘려 주는 구성 요소들이 필요하고, Pydantic AI는 이런 것들을 프레임워크 변경 없이 붙일 수 있도록 기능(capability)과 훅 API를 제공합니다. 문제는 이런 기능들을 매번 직접 구현하다 보면 같은 코드를 반복해서 만들게 된다는 점입니다.

Pydantic AI Harness 는 Pydantic AI 팀이 직접 관리하는 공식 기능 라이브러리로, 에이전트에 골라 끼울 수 있는 독립적인 빌딩 블록들을 모아 둔 저장소입니다. Pydantic AI 코어에는 모델이나 프레임워크 차원의 지원이 필요한 기능과 모든 에이전트에 공통으로 필요한 기능(웹 검색, 도구 검색, 추론)만 들어가고, 그 밖의 기능은 이 Harness에 담깁니다. 새로운 기능은 보통 이곳에서 시작해, 충분히 안정화되고 널리 쓰이는 것으로 검증되면 코어로 승격됩니다.

이 라이브러리는 기능 목록을 기능 매트릭스(capability matrix) 로 공개하고, 각 항목을 저장소의 이슈와 PR로 추적하면서 어떤 것을 먼저 만들지 커뮤니티 투표로 정합니다. 본 게시물에서는 현재 제공되는 핵심 기능인 CodeMode, 라이브러리가 다루려는 기능 영역, 그리고 설치·사용법을 정리합니다.

Pydantic AI Harness의 CodeMode

현재 Harness에서 바로 사용할 수 있는 대표 기능은 CodeMode 입니다. 일반적인 도구 호출 방식에서는 모델이 도구를 하나 부르고, 결과를 받고, 다시 다음 도구를 부르는 식으로 도구마다 모델 왕복이 발생합니다. CodeMode는 모든 도구를 하나의 run_code 도구로 감싸고, 모델이 그 안에서 실행할 파이썬 코드를 직접 작성하게 합니다. 모델은 반복문, 조건문, asyncio.gather 를 이용한 병렬 호출, 결과의 로컬 필터링까지 코드로 표현할 수 있고, 그 결과 N개의 도구 호출이 단 한 번의 모델 왕복으로 처리됩니다.

이 코드는 Pydantic AI 팀의 샌드박스인 Monty 안에서 실행되며, [code-mode] extra를 설치하면 함께 딸려 옵니다. 아래는 공식 문서의 빠른 시작 예시로, CodeMode와 함께 MCP 서버 연결, 웹 검색을 하나의 에이전트에 묶은 모습입니다.

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

agent = Agent(
    'anthropic:claude-opus-4-7',
    capabilities=[
        # 모든 도구를 하나의 run_code 도구로 감싸고 Monty 샌드박스에서 실행
        CodeMode(),
        # 오픈소스 Hacker News MCP 서버에 연결 (native=False로 로컬 툴셋 강제)
        MCP('https://hn.caseyjhand.com/mcp', native=False),
        # 제공자 적응형 웹 검색 (native=False로 로컬 DuckDuckGo 폴백 경유)
        WebSearch(native=False),
    ],
)

result = agent.run_sync(
    "여러 Hacker News 피드에서 100점 이상이면서 가장 많이 논의된 글을 찾아, "
    "댓글 스레드와 작성자 프로필, 관련 웹 보도를 모아 한 문단으로 요약해줘."
)
print(result.output)

native=False 옵션은 MCP와 웹 검색을 로컬 툴셋으로 강제해, 제공자가 서버 쪽에서 직접 실행하는 대신 CodeMode가 도구를 감쌀 수 있도록 합니다. 실행 과정은 Logfire 트레이스로 확인할 수 있는데, 각 run_code 스팬이 모델이 샌드박스 안에서 호출한 도구들로 펼쳐지므로 코드 모드가 실제로 무슨 일을 했는지 추적하기 쉽습니다.

Pydantic AI Harness의 기능 영역

기능 매트릭스는 프로덕션 에이전트에 필요한 영역을 일곱 갈래로 정리합니다. 도구 실행(코드 모드, 도구 검색, 파일 시스템, 셸, 검증 루프), 컨텍스트 관리(슬라이딩 윈도우, 컨텍스트 압축, 한도 경고), 메모리와 영속성(영속 메모리, 세션 저장, 체크포인트), 에이전트 오케스트레이션(서브 에이전트, 스킬, 계획 수립, 작업 추적, 팀), 안전장치(입출력 가드레일, 비용·토큰 예산, 도구 접근 제어, 비밀 정보 마스킹, 승인 워크플로), 신뢰성(무한 루프 감지, 도구 오류 복구), 추론(적응형 추론, 현재 시각 주입)이 그것입니다.

다만 이 가운데 현재 사용할 수 있도록 출시된 것은 코드 모드와 도구 검색이고, 나머지 항목 대부분은 PR 또는 이슈로 진행 중인 로드맵 상태입니다. Pydantic AI 팀은 vstorm-co 가 만든 커뮤니티 패키지들을 매트릭스에서 함께 소개하며, 일부 구현을 이 저장소로 흡수(upstream)하는 작업을 진행하고 있습니다. 따라서 지금 시점에서는 코드 모드를 중심으로 사용하면서, 필요한 기능이 어디까지 와 있는지 매트릭스에서 직접 확인하는 방식이 현실적입니다.

Pydantic AI Harness 설치 및 사용법

설치는 uv 로 패키지를 추가하면 됩니다. Python 3.10 이상과 pydantic-ai-slim>=1.95.1 이 필요합니다.

uv add pydantic-ai-harness

특정 기능에 필요한 extra는 따로 지정합니다. 예를 들어 CodeMode는 Monty 샌드박스를 함께 설치하는 [codemode](또는 별칭 [code-mode]) extra가 필요합니다.

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

위 빠른 시작 예시처럼 동작시키려면 Pydantic AI 본체와 관련 extra도 함께 설치합니다.

uv add "pydantic-ai-slim[anthropic,mcp,duckduckgo,logfire]" "pydantic-ai-harness[code-mode]"

각 기능은 Agent(...) 의 capabilities 리스트에 인스턴스를 넣는 방식으로 활성화되므로, 필요한 것만 골라 조합할 수 있습니다.

Pydantic AI Harness의 라이선스

Pydantic AI Harness는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

Pydantic AI 공식 문서

Pydantic AI Harness 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~