Shepherd는 에이전트의 실행을 되돌릴 수 있는 Git-like trace로 남기는 Python 런타임이다. 에이전트가 파일을 고치거나 프로그램을 만들 때 결과를 바로 작업 디렉터리에 반영하지 않고, 검토 가능한 제안(changeset)으로 보관한다. 메타 에이전트가 실행을 관찰하고, 포크하고, 재생하고, 필요하면 폐기할 수 있게 하는 것이 핵심이다.
핵심 아이디어
에이전트 실행은 단순한 로그가 아니라 재사용 가능한 실행 자산이다. Shepherd는 실행 중 만들어진 파일 변경, 도구 호출, 권한 범위, 산출물을 retained output으로 보관한다. 사용자는 결과를 읽거나 실행해본 뒤 select로 채택하거나 discard로 버릴 수 있다.
이 구조는 다음 상황에 특히 유용하다.
- 코딩 에이전트가 생성한 변경을 바로 적용하지 않고 리뷰하려는 경우
- 여러 에이전트 실행을 포크해 다른 방향으로 실험하려는 경우
- self-improving-agent-loops처럼 실행 trace를 학습·평가·하네스 개선 신호로 쓰려는 경우
- 읽기 전용·쓰기 가능 저장소를 작업별로 분리해 권한을 강제하려는 경우
사용 흐름
pip install shepherd-ai
mkdir /tmp/agent-task && cd /tmp/agent-task
shepherd init
shepherd doctor claude작업은 Python 함수의 시그니처와 docstring으로 계약을 정의한다. 예를 들어 특정 저장소에는 읽기 권한만, 다른 저장소에는 쓰기 권한을 부여할 수 있다. Shepherd는 이 권한을 macOS Seatbelt나 Linux Landlock 같은 OS 수준 jail로 컴파일해 실행 중 파일 접근을 제한한다.
왜 중요한가
많은 에이전트 하네스는 “에이전트가 잘할 것”을 전제로 한다. Shepherd는 반대로 에이전트가 틀릴 수 있다는 전제에서 실행을 보관하고, 검토하고, 되돌릴 수 있게 만든다. 이는 agent-harness와 agentic-loops에서 말하는 검증 루프를 파일시스템과 런타임 레벨로 끌어내린 설계다.
| 관점 | 일반 에이전트 실행 | Shepherd 방식 |
|---|---|---|
| 결과 반영 | 작업 디렉터리에 즉시 쓰기 | retained output으로 보관 후 선택 |
| 실패 처리 | 로그 확인 후 재실행 | trace를 기준으로 재생·포크·폐기 |
| 권한 | 프로세스 권한에 의존 | 함수 시그니처의 권한 계약을 jail로 강제 |
| 메타 에이전트 | 외부 관찰 위주 | 실행 trace를 직접 관찰·개선 대상으로 사용 |
한계와 주의점
Shepherd는 2026년 7월 기준 early alpha 상태다. API가 바뀔 수 있으므로 핵심 프로덕션 워크플로에 넣기 전에는 별도 실험 환경에서 검증해야 한다. 또한 Claude CLI나 모델 API를 사용하는 실제 에이전트 실행은 인증·조직 정책·샌드박스 제약에 영향을 받는다.
라이선스
MIT 라이선스로 공개되어 있다.
관련 문서
- agent-harness — AI 에이전트 성능을 결정하는 하네스 설계
- self-improving-agent-loops — 결과를 기억하고 다음 실행을 고치는 에이전트 구조
- agent-sandboxing-tips-brain-hands — 에이전트 본체와 코드 실행 샌드박스를 분리하는 방법
참고 자료
- shepherd-agents/shepherd — GitHub 공식 저장소