Coder
Coder
Coder는 Pydantic AI 에이전트에게 로컬 코드베이스를 조사·편집·테스트하기 위한 도구와 안내를 줘요. FileSystem, Shell, RepoContext, 그리고 컨텍스트 관리 capability들로 만든 평범한 결합 capability라, 통째로 쓰거나 분해할 수 있어요.
출처: 문서
Pydantic AI Harness가 0.x 릴리스인 동안 API는 마이너 릴리스 사이에 바뀔 수 있어요. 그럴 때는 deprecation 경고와 릴리스 노트의 마이그레이션 안내가 정확히 어떻게 업그레이드할지 알려줘요. 버전 정책을 참고하세요.
본문
사용법 (Usage)
list_files와 grep 도구를 뒷받침하는 ripgrep(rg)을 포함하려면 Coder extra를 설치하세요.
pip install "pydantic-ai-harness[coder]"
uv add "pydantic-ai-harness[coder]"
extra는 Android를 제외하고 ripgrep==14.1.0을 설치해요. Android에서는 rg를 PATH에 별도 제공해야 해요. 필요하면 [coder,anthropic] 같은 프로바이더 extra를 추가하세요. 명령은 허용 목록 없이 호스트에서 실행돼요. 신뢰할 수 없는 작업에는 OS 수준 샌드박스나 컨테이너를 쓰세요. 파일 도구의 경로 제한은 셸 샌드박스가 아니에요.
from pydantic_ai import Agent
from pydantic_ai_harness.coder import Coder
agent = Agent(
'anthropic:claude-fable-5',
name='coder',
capabilities=[Coder('.')],
)
result = agent.run_sync('Investigate the failing parser test, fix the cause, and run focused checks.')
print(result.output)
내보내진 pydantic_ai_harness.coder:coder_agent는 같은 구성이고, 모델 없이 이름 coder예요. Pydantic AI CLI와 함께 쓰세요.
uvx --with "pydantic-ai-harness[coder]" clai -a pydantic_ai_harness.coder:coder_agent -m anthropic:claude-fable-5
구성 (Composition)
Coder(workspace)는 이 순서의 capability들이에요.
- 기본 지시문과 넘긴
instructions=를 지니는Capability하나. FileSystem(root_dir=workspace, content_hashes=False, max_read_chars=60000, tools=FILE_TOOL_NAMES).FILE_TOOL_NAMES은read_file,write_file,edit_file,list_files,grep이에요.Shell(cwd=workspace, denied_commands=[], allow_interactive=True, default_timeout=270, denied_env_patterns=LLM_API_KEY_ENV_PATTERNS, tools=['shell']).RepoContext(workspace_dir=workspace, expose_inventory_tool=False)로 저장소 지시문과 구조. 에이전트가 이미 자체RepoContext를 바인딩하면repo_context=False를 넘겨 빼서 지시문 파일이 두 번 로드되지 않게 해요.
그다음 에이전트가 직접 부르지 않는 배관:
ClearToolResults(max_fraction=0.7)과WarnNearLimits(max_context_fraction=0.9).- 스필 검색 도구를 추가하지 않고 64,000자 넘는 도구 결과를 자르는 사설
ToolOutputLimits전문화. 안정 IDcoder_tool_output_limits로, 별도 구성된ToolOutputLimits와 충돌하지 않고 durability capability가 상속된 작업을 바인딩하게 해요. RepairToolArguments가 정상 검증 전에 잘못된 JSON 도구 인수를 수리해요(아래 참고).
모든 도구는 FileSystem이나 Shell에서 와요. 그 페이지들이 각각을 온전히 문서화해요. 어떤 설정을 바꾸려면 같은 에이전트를 조각으로 만들어요. 콘텐츠 해시 유지, list_directory 추가, 명령 허용 목록 같은 것요.
여섯 도구 (Six tools)
| 도구 | 동작 |
|---|---|
read_file(path, offset=0, limit=None) |
0 기반 줄 오프셋, 1 기반 표시 줄 번호, 완전한 줄로 최대 2,000줄 또는 60,000자. 이어지는 힌트가 정확한 다음 오프셋을 이름붙이고, 창에 너무 긴 줄도 이름붙여 건너뛸 수 있어요. 해시 헤더 없음. |
write_file(path, content) |
기존 디렉터리에 파일 생성 또는 교체. expected_hash 없음. |
edit_file(path, old_text, new_text) 또는 edit_file(path, replacements=[...]) |
정확한 치환, 각각 한 번씩 일치. 배치는 메모리에서 검사되고 모든 치환이 일치할 때만 써져요. |
list_files(path='.', glob=None) |
rg --files, 경로순 정렬, ignore 파일 존중, 숨김 파일 건너뜀. |
grep(pattern, ...) |
path, glob, file_type, ignore_case, literal, context(0~20)로 ripgrep 검색. |
shell(command, mode='foreground', timeout=270) |
실행보다 오래 사는 워크스페이스에 뿌리를 둔 무제한 명령. |
결과는 FileSystem의 상한(2,000줄 또는 read_file당 60,000자, 검색·나열당 1,000줄·파일)과 Coder의 64,000자 도구 출력 한도로 경계져요. 잘림 표시는 더 많은 출력이 빠졌다는 뜻이므로 완료라 가정하지 말고 검색을 좁혀요. read_file 창은 출력 한도 아래 있어 offset으로 페이지해도 줄을 건너뛰지 않아요. mkdir, find, 프로세스 검사, kill에는 shell을 쓰세요. 파일 쓰기는 독립형 파일시스템의 보호 경로 규칙(.git, .env, 키, 비밀)을 유지하고, shell은 그 규칙을 우회할 수 있어요. Coder는 계획, 위임, 실행 범위 run_command 계열을 포함하지 않아요.
파일시스템 범위 (Filesystem scope)
파일 도구는 기본적으로 워크스페이스 범위예요. 신뢰된 로컬 사용을 위해 Coder(unrestricted_filesystem=True)가 FileSystem(root_dir=<workspace drive root>, cwd=workspace, protected_patterns=[])를 설정해요. 상대 경로는 여전히 워크스페이스에서 해석되고, 드라이브 어디든 절대 경로는 받아들여져요. POSIX에서는 /tmp/example.py 같은 경로를 허용하고, Windows에서는 다른 드라이브가 아니라 워크스페이스 드라이브를 다뤄요. OS 권한과 파일 변경 이벤트 리스너는 여전히 적용돼요. 이것은 비밀과 저장소 메타데이터 수정을 허용해요. 에이전트와 그 입력을 신뢰할 때만 쓰세요. Shell 명령은 이미 무제한이었어요.
오래 실행되는 명령 (Long-running commands)
shell은 Shell capability의 지속 도구예요. 포그라운드는 최대 270초(또는 더 작은 양수 timeout)를 기다린 뒤 같은 실행 중 프로세스에 대한 핸들을 반환하고, 백그라운드는 즉시 반환해요. 둘 다 PID, 절대 출력 로그 경로, 절대 JSON 상태 경로로 끝나는데, 명령 실행 중 exit_code가 null이에요. 포그라운드는 그 앞에 마지막 16,000바이트 출력을 둬요. 명령은 에이전트 실행보다 오래 살아 서버가 계속 실행돼요. 완료 알림이나 최종 응답 후 자동 깨움이 없어요. Shell 페이지가 슈퍼바이저, 정리, UI가 구독할 CommandStartedEvent, CommandOutputEvent, CommandFinishedEvent 진행 이벤트를 다뤄요.
기본 지시문은 에이전트에게 최종 응답을 주기 전에 필요한 작업을 끝내라고 말해요. 다른 유용한 작업을 한 다음 완료 또는 진짜 장애물까지 상태와 출력을 폴링하라고요. 서버는 시작·준비가 검증된 뒤 계속 실행될 수 있어요. 흔한 LLM API 키 환경 변수는 명령 환경에서 필터링돼요. 다른 호스트 자격 증명과 파일은 여전히 접근 가능해요.
지시문 (Instructions)
기본 지시문은 엔지니어링 안내를 간결히 유지해요. 자율 조사·완료, 집중된 변경·검증, 실용적 DRY, YAGNI, SOLID, Zen of Python. 도구 설명이 도구 사용을 제공하고, RepoContext가 저장소 지시문·구조를 제공해요. Coder(instructions='...')는 기본을 교체하지 않고 프로젝트 특정 안내를 덧붙여요. 파일 크기 한도나 선호하는 검증 워크플로우 같은 추가 정책에 쓰세요.
도구 인수 수리 (Tool argument repair)
Coder는 RepairToolArguments를 조합하는데, Pydantic AI가 도구 스키마를 검증하기 전에 잘못된 JSON에 json-repair를 써요. 유효한 JSON과 이미 파싱된 인수는 그대로 통과해요. 빠진 필드와 잘못된 타입은 정상 검증·재시도 동작을 여전히 따르고, 수리는 Coder 옆에 추가된 도구에도 적용돼요. 수리 파서가 값이나 재귀 오류를 일으키면 원본 인수가 정상 검증으로 가요.
수리는 휴리스틱이에요. 잘못된 입력은 모호할 수 있고, 추론된 문자열이 모델 의도와 다를 수 있어요. 수리 라이브러리에 스키마를 공급하거나 정확한 편집 일치를 우회하지 않아요. 각 시도는 인수나 파일 콘텐츠 없이 ctx.tracer를 통해 repair_tool_arguments 스팬을 내보내요. 다른 Coder 작업은 core 도구 스팬과 그 FileSystem·Shell capability가 내는 이벤트에 의존해요.
벤치마킹 (Benchmarking)
Harbor 안에서 Coder를 실행하고, 어댑터와 하네스를 고정하고, 시험 결과를 검사하려면 Terminal-Bench 2.1 playbook을 보세요.
소스를 보세요.
API 참조 (API reference)
Coder
Bases: CombinedCapability[AgentDepsT]
여섯 도구와 컨텍스트 관리로 자율 로컬 코딩.
명령은 무제한이고 실행보다 오래 살 수 있어요. 신뢰할 수 없는 작업에는 OS 샌드박스를 쓰세요. 추가 지시문이 기본 안내를 보충해요. repo_context=False는 자기 것을 바인딩하고 그렇지 않으면 지시문 파일을 두 번 로드할 호스트용으로 동봉된 RepoContext를 빼요.