Pydantic AI Harness
Pydantic AI Harness
당신의 에이전트가 가장 좋아하는 하네스. Pydantic AI 위에 구축됐어요
Pydantic AI Harness는 Pydantic AI의 공식 capability 및 하네스 라이브러리예요. 모든 Pydantic AI 에이전트에는 이미 가벼운 하네스가 있어요. 타입화된 에이전트 루프, 어떤 모델이든, 자신의 도구, 구조화 출력까지요. 단순한 에이전트에게는 이걸로 충분해요. 하지만 복잡하고 오래 걸리는 작업(코드베이스 고치기, 질문 리서치, 무인으로 몇 시간 실행)에 에이전트를 풀어 놓으면, 모델 주변에 필요한 것이 커져요. 작업할 워크스페이스, 최신 상태로 유지되는 계획, 세션을 가로질러 이어지는 메모리, 일을 넘길 서브 에이전트, 10시간째에도 버티는 컨텍스트 관리, 재시작을 견디는 영속 실행까지. Pydantic AI Harness는 바로 그 하네스를 제공해요.
출처: 문서
본문
여기의 모든 것은 하나의 프리미티브예요. capability, 즉 어떤 에이전트의 capabilities=[...]에 추가하는 자족적인 에이전트 동작 단위이죠. 30개 이상이 있고, Coder와 Researcher 같은 완전한 에이전트도 그 자체가 capability를 조합한 것이에요. 조립된 방식 그대로 분해할 수 있죠. 블록 하나를 끼우거나, 자신의 스택을 조립하거나, 전체 코딩 에이전트에서 시작해 나중에 분해할 수도 있어요.
빠른 시작 (Quick start)
uv로 설치하세요:
pip install "pydantic-ai-harness[anthropic]"
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.
Coder는 read_file, write_file, edit_file, list_files, grep, shell 여섯 도구를 제공하고, 저장소 컨텍스트와 컨텍스트 제어도 제공해요. 셸 명령은 제한이 없고 개별 실행을 넘어 지속될 수 있습니다. 기본 지시문이 자율 조사·편집·검증을 안내하고, instructions=를 넘기면 자신의 안내를 추가할 수 있어요.
uvx --with "pydantic-ai-harness[coder]" clai -a pydantic_ai_harness.coder:coder_agent -m anthropic:claude-fable-5
모든 모델이 동작해요. 문자열을 어느 프로바이더의 것으로 바꾸면 되죠. 더 필요하다면 목록에 capability를 추가하세요. 웹 검색과 세션 간 메모리가 있는, gpt-5.6-sol上의 같은 코더예요:
pip install "pydantic-ai-slim[openai]"
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
],
)
Skills(당신의 SKILL.md 절차. 요청 시 로드. skills/ 디렉터리를 가리키고 skills 엑스트라 추가), Web Fetch, Guardrails, Dynamic Workflow도 같은 방식으로 끼워 넣어요. Coder 페이지에 무엇이 잘 어울리는지 나열돼 있어요.
마법 없음: 끝까지 capability예요 (No magic: it's capabilities all the way down)
Coder는 일반적인 결합 capability예요. 다섯 도구에 콘텐츠 해시를 끈 FileSystem, 영속 shell 도구와 허용 목록이 없는 Shell, RepoContext, ClearToolResults와 WarnNearLimits, 그리고 경계가 있는 ToolOutputLimits에 기본 지시문과 JSON 인자 복구를 더한 것이죠. 통째로 쓰거나, 같은 에이전트를 그 capability들로 만들어 어떤 설정이든 바꿀 수 있어요. Coder 페이지에 정확한 구성이 나열돼 있어요.
from pydantic_ai import Agent
from pydantic_ai_harness.coder import Coder
agent = Agent(
'anthropic:claude-fable-5',
name='coder',
capabilities=[Coder('.')],
)
도구 시그니처, 영속 셸 라이프사이클, 이전 planning/delegation 구성에서의 마이그레이션은 Coder 문서를 참고하세요.
Capabilities
모든 capability는 capabilities=[...]에 넣는 자족적인 단위이며, 모두 서로 및 자신의 것과 조합돼요. 일부는 pydantic-ai 자체에, 나머지는 이 패키지에 포함돼요. Package 열이 어느 쪽인지 알려줘요. 총 50개 이상이며, 에이전트에 주는 것이 무엇인지로 묶었습니다:
하네스 (Harnesses)
완전한 에이전트 스택을 일반적인 결합 capability로 제공해요. 임포트 하나로 동작하는 에이전트를 얻고, 아래 블록들로 분해할 수 있어요.
| 하네스 | 패키지 | 제공 내용 |
|---|---|---|
| Coder | Harness | 코딩 도구 6개, 영속 셸 명령, 자율 안내, 컨텍스트 제어 |
| Researcher | Harness | 완전한 웹 리서치 스택: 검색, 페이지 가져오기, 위임된 서브 리서처, 경계 있는 도구 출력 |
실행 환경 (Execution environments)
에이전트가 작업하는 워크스페이스: 편집하는 파일과 실행하는 명령, 로컬 또는 격리.
| Capability | 패키지 | 동작 |
|---|---|---|
| FileSystem | Harness | 루트 아래 파일 읽기·쓰기·편집·나열·검색, 선택적 ripgrep 도구. 경로 순회·심링크 안전, 시크릿 읽기 전용 |
| Shell | Harness | 허용·차단 목록, 타임아웃, 자격 증명 제거, 실행을 넘어 사는 선택적 명령이 있는 명령 실행 |
| Modal Sandbox | Harness | 격리된 Modal 클라우드 샌드박스에서 명령·파일 |
도구 & 네이티브 능력 (Tools & native abilities)
에이전트 워크스페이스 밖의 시스템 연결, 그리고 프로바이더가 네이티브로 실행하는 능력.
| Capability | 패키지 | 동작 |
|---|---|---|
| MCP | Core | 어떤 MCP 서버의 도구든 연결, 기본 로컬, 프로바이더 네이티브 커넥터는 선택 |
| Image Generation | Core | 이미지 생성·편집, 지원되면 프로바이더 네이티브, 아니면 서브 에이전트 폴백 |
| StackOne | Harness | StackOne을 통해 연결된 SaaS 계정(HRIS, ATS, CRM, ...)에 작용 |
| LocalStack | Harness | AWS CLI 도구가 있는 에뮬레이트된 AWS 환경 |
| Macroscope | Harness | 로컬 Macroscope 코드 리뷰를 실행하고 결과를 에이전트에 전달 |
웹 & 리서치 (Web & research)
공개 웹에서 무언가를 찾고 읽기.
| Capability | 패키지 | 동작 |
|---|---|---|
| Web Search | Core | 가능하면 프로바이더 네이티브 검색, 어디서든 로컬 DuckDuckGo 폴백 |
| Web Fetch | Core | URL 가져오기·읽기, 네이티브 또는 로컬 |
| X Search | Core | X 검색, xAI에서 네이티브, 그 외에는 서브 에이전트 폴백 |
| Exa Search | Harness | Exa를 통한 웹 리서치: 발췌 검색, 전체 페이지 읽기, 선택적 인용 딥 검색 |
| Exa Agent | Harness | 개방형 리서치를 Exa Agent API에 위임 |
| You.com Search | Harness | You.com을 통한 웹 검색·페이지 읽기: 쿼리 관련 발췌 또는 전체 페이지 마크다운 |
| You.com Research | Harness | You.com Answer·Research·Finance Research API를 통한 인용 답변·다단계 리서치 |
| Browser Use | Harness | 실제 브라우저를 조종하는 자율 browser-use 에이전트에 웹 작업 전달 |
| Playwright Browser | Harness | 실제 Chromium 페이지를 직접 구동: 탐색, 클릭, 타이핑, 읽기, 페이지가 한 일 검사 |
추론, 계획 & 위임 (Reasoning, planning & delegation)
에이전트가 생각하고 일을 나누는 방식.
| Capability | 패키지 | 동작 |
|---|---|---|
| Thinking | Core | 구성 가능한 노력의 프로바이더 적응형 확장 사고 |
| Planning | Harness | 캐시 안전한 라이브 리마인더가 있는 모델 소유 작업 계획 |
| Subagents | Harness | 자족적 작업을 이름 붙인 자식 에이전트에 위임 |
| Dynamic Workflow | Harness | 모델이 파이썬 스크립트 하나에서 서브 에이전트를 조율: 단일 도구 호출로 팬아웃·체인·투표, 하드 max_agent_calls 예산 |
| Advisor | Harness | 실행자가 실행 중 더 강한 모델을 상담하도록 허용 |
| Background Tools | Harness | 선택된 도구를 동시에 실행, 결과는 후속 메시지로 도착 |
컨텍스트 관리 (Context management)
에이전트가 컨텍스트 윈도우를 쓰는 방식. 긴 실행 동안 열화되는 에이전트와 그렇지 않은 에이전트의 차이, 토큰을 N번 지불하는 것과 한 번 지불하는 것의 차이예요.
| Capability | 패키지 | 동작 |
|---|---|---|
| Code Mode | Harness | 모델이 Monty 샌드박스 안에서 많은 도구를 호출하는 파이썬 스크립트 하나를 작성: N번이 아니라 왕복 1번, 중간 결과는 컨텍스트 윈도우에 들어오지 않음. 도구 호출 토큰 비만의 해답 |
| Tool Search | Core | 매 프롬프트에 수백 개를 담는 대신 도구 정의를 요청 시 로드 |
| Compaction | Core | OpenAI·Anthropic에서 프로바이더 네이티브 컴팩션. 프로바이더가 서버 측에서 히스토리 요약 |
| Compaction | Harness | 모델에 구애받지 않는 전략: 도구 결과 비우기, 슬라이딩 윈도우 트리밍, LLM 요약, 계층형. 모두 윈도우 기준, 라이브 사용량 보고 |
| Tool Output Limits | Harness | 과도한 도구 반환을 소스에서 절단, 조회 가능한 파일로 유출, 또는 요약 |
| Warn On Cache Busts | Harness | 프로바이더 자체 숫자로 요청 사이의 프롬프트 캐시 프리픽스 붕괴 감지 |
지식 & 메모리 (Knowledge & memory)
에이전트가 알고 기억하는 것. 매 프롬프트에 실어 나르는 대신 관련될 때 로드.
| Capability | 패키지 | 동작 |
|---|---|---|
| Memory | Harness | 영속·네임스페이스 노트북: 경계 있는 프롬프트 주입, 요청 시 검색, 인메모리/파일/Postgres 저장소 |
| Conversation Search | Harness | 저장된 히스토리에 대한 BM25 검색, 컴팩션이 버린 턴 포함 |
| Skills | Harness | Agent Skill(SKILL.md) 지시문을 요청 시 로드 |
| Repo Context | Harness | 실행을 정향(orient)으로 시작: AGENTS.md/CLAUDE.md + 저장소 구조 |
| Pydantic AI Docs | Harness | 요청 시 Pydantic AI 문서 조회 |
제어 & 안전 (Control & safety)
에이전트가 할 수 있는 것을 경계 짓고, 지시문에 붙잡아 두기.
| Capability | 패키지 | 동작 |
|---|---|---|
| Repair Tool Arguments | Harness | 스키마 검증 전에 잘못된 JSON 도구 인자 복구 |
| Guardrails | Harness | 사용자 입력·도구 호출·도구 결과·출력 검증/차단/삭제, 시크릿 마스킹·병렬 비동기 가드 포함 |
| Prompt Injection Defender | Harness | 로컬 도구 결과를 간접 프롬프트 주입으로 분류, 선택적으로 고위험 결과 보류 |
| Spend Limits | Harness | 윈도우 간 USD/토큰 예산과 응답별 비용 추적, 모델별·테넌트별 |
| Ask User | Harness | 모델이 실행 중 다지선다 질문을 사용자에게 허용, 당신이 답변자(터미널·웹·테스트)를 제공 |
| Tool approval | Core | 실행 전 인간 승인이 필요한 도구 호출 플래그 |
| Handle Deferred Tool Calls | Core | 승인 지연 도구 호출을 프로그래밍 방식으로 해결 |
| System Reminders | Harness | 지시문 희미짐에 대응해 실행 중 안내를 캐시 안전하게 재주입 |
| Trajectory Judge | Harness | 두 번째 모델이 슬라이딩 토큰 윈도우 위에서 N 요청마다 라이브 실행을 검토하고 실행 중 조종 |
자기 확장 (Self-extension)
| Capability | 패키지 | 동작 |
|---|---|---|
| Capability Creation | Harness | 에이전트가 실행 중 새 capability를 작성·검증·영속화하고 다음 실행에 로드: 임의 코드 대신 타입화되고 검사 가능한 단위로 자기 확장 |
실행 런타임 (Execution runtime)
루프 바깥: 실행이 어떻게 지속되고, 실패를 견디며, 프로덕션에서 관찰·구성되는지.
| Capability | 패키지 | 동작 |
|---|---|---|
| Durable execution | Core | Temporal, DBOS, Prefect에서 재시작·실패를 견디는 실행, Restate, Kitaru, Airflow 통합 |
| AWS Lambda durability | Harness | 모델 요청·도구 호출을 AWS Lambda 영속 함수 스텝으로 체크포인트 |
| Step Persistence | Harness | 실행 저장·복원·재개(continue_run)·포크(fork_run), 파일/SQLite/Mongo 백엔드 |
| Instrumentation | Core | 모든 모델·도구 호출에 대한 OpenTelemetry GenAI 스팬, Logfire 트레이스의 원자재 |
| Managed Prompt | Harness | 지시문을 Logfire 관리 프롬프트로 뒷받침, 재배포 없이 버전·롤아웃 |
| Thread Executor | Core | 공유 스레드 풀에서 동기 도구 실행 |
Core는 프로덕션 서버용 루프 커스터마이즈 capability도 함께 배포해요: Select Model, Resolve Model ID, Prepare Tools / Prepare Output Tools, Prefix Tools, Set Tool Metadata, Include Tool Return Schemas, Process History, Process Event Stream, Reinject System Prompt, Raise Content Filter Error.
그리고 에이전트는 어떤 인터페이스에도 끼워져요: ACP_(실험적, Harness)_는 Agent Client Protocol로 Zed 같은 편집기에 서빙하고, Core는 웹 채팅 UI, CLI, 프론트엔드 어댑터(AG-UI, Vercel AI), realtime 음성을 제공해요.
커뮤니티 패키지가 같은 capability 시스템을 더 확장해요. 서드파티 capabilities 참고.
Harness가 언제 필요한가요? (When do you need the Harness?)
"하네스(Harness)"는 모델을 에이전트로 바꾸는 모델 주변의 모든 것 — 루프, 도구, 컨텍스트 관리 — 을 가리키는 업계 용어예요. 이 패키지는 에이전트가 코어의 린 하네스가 덮는 것보다 더 하길 원할 때 잡으세요. 파일 다루기, 코드 실행, 브라우징, 기억, 위임, 또는 몇 시간에 걸친 실행 동안 일관성 유지 같은 거죠. 패키지들 사이의 경계는 성숙도 단계가 아니라 기계적인 거예요. Core는 모델이나 프레임워크 지원이 필요한 capability(프로바이더 네이티브 도구인 이미지 생성, 프로바이더 API인 compaction, 깊은 루프 통합인 tool search, 그리고 thinking, MCP, web search 같은 기본 요소)를 배포하고, Harness는 나머지 모두를 별도 패키지로 배포해서, Pydantic AI 자체는 린하게 유지하면서 capability가 업계가 움직이는 속도로 반복할 수 있게 해요.
설치 (Installation)
pip install pydantic-ai-harness
uv add pydantic-ai-harness
이건 pydantic-ai-slim을 함께 설치하므로 단독으로 동작하고, Pydantic AI를 별도로 설치할 필요가 없어요. 모델 프로바이더와 CLI는 Pydantic AI로 통과되는 엑스트라로 옵니다: pydantic-ai-harness[anthropic], [cli]. 일부 capability는 선택 의존성을 위한 자체 엑스트라가 필요해요. 각 capability 페이지에 정확한 설치 줄이 있습니다. Python 3.10+ 필요.
Pydantic AI 자체가 처음이라면 그 문서부터 시작하세요. 이 capability들을 얹을 에이전트가 거기에 정의돼 있어요.
관측 가능성 (Observability)
하네스가 하는 모든 것은 관측 가능해요. Core의 Instrumentation capability(또는 logfire.instrument_pydantic_ai())가 모든 실행의 전체 트레이스를 방출해요. 토큰·비용 추적과 함께 모든 모델 호출·도구 호출을요. 표준 OpenTelemetry라 어떤 OTLP 백엔드든 동작하고, Logfire가 개발 중에 보기 가장 쉬운 방법이에요.
직접 만들기 (Build your own)
Capabilities는 Pydantic AI의 1차 확장 지점이고, 이 라이브러리의 모든 capability는 동시에 실제 작업 예제예요. 독립 패키지를 배포한다면 pydantic-ai-<name> 명명 규칙을 쓰세요. Capability 패키지 배포 참고.
버전 정책 (Version policy)
Pydantic AI Harness는 0.x 버전 관리를 사용하며, 이것은 성숙도가 아니라 API 안정성에 대한 선언이에요. 이 capability들은 end-to-end로 테스트되고 프로덕션용이지만, 그 API는 여전히 마이너 릴리스 사이(0.1 -> 0.2)에 움직일 수 있어요. 파라미터 이름 변경, 기본값 변경, API 재구성, 실용적인 곳에는 항상 폐기 경고와 함께요. 패치 릴리스는 의도적으로 기존 동작을 깨지 않으며, 모든 파괴적 변경은 에이전트가 따를 수 있는 마이그레이션 안내와 함께 릴리스 노트에 문서화돼요. Harness를 더 엄격한 버전 정책을 가진 Pydantic AI와 별도 패키지로 유지하는 것이 capability가 업계가 움직이는 속도로 반복하게 만드는 거예요.
Pydantic AI 참고 (Pydantic AI references)
- Capabilities: capability가 무엇인지, 내장 capability, 직접 만들기
- Hooks: 라이프사이클 훅 레퍼런스, 순서, 오류 처리
- Extensibility: 패키지 배포, 서드파티 생태계
- Toolsets: capability를 위한 도구 구축
- API reference: 전체 API 문서
더 알아보기 (Learn more)
- Pydantic AI Harness 저장소 — 소스와 capability 매트릭스.
- Capabilities — capability 시스템.
- Coder — 완전한 코딩 에이전트.