Harness Router
Protocol Lattice · 코딩 · 생산성
Harness Router는 이미 돌리고 있는 AI 에이전트 하네스 안에서 다음 도구를 고른다. 캐시된 결정, Jev 라우팅, 선택형 MCTS를 조합하고 실제 실행은 원래 루프에 남긴다.
Harness Router 소개
What Is Harness Router
Harness Router는 에이전트 루프 안에서 한 가지 결정만 내리는 오픈소스 Python 패키지다. 지금 어떤 도구를 실행할지 정한다. 목표, 현재 관측, 직전 행동, 사용 가능한 도구 목록을 받아 도구 이름과 신뢰도, 그리고 판단을 플래너에게 돌려줄지 알려주는 플래그를 반환한다.
역할 분담이 핵심이다. 하네스는 인자 구성, 권한 확인, 승인, 재시도, 실제 호출을 이미 맡는다. Harness Router는 그 부분을 건드리지 않는다. 프롬프트 훅이나 도구 결과 콜백처럼 호스트가 열어 둔 수명 주기 지점에 앉아, 다음 수를 정하는 순간에 힌트를 건넨다. Protocol Lattice가 MIT 라이선스로 공개했고 현재 버전은 alpha로 표시돼 있다.
범위는 좁다. 도구 목록이 커질수록 같은 관측에 여러 도구가 그럴듯하게 걸린다. 신뢰도와 함께 도구 하나를 지목하면 하네스는 받아들일지 버릴지 판단할 수 있다. 코드를 쓰거나 테스트를 돌리거나 완료의 정의를 정하지는 않는다.
설치 전에 프로젝트 자체 벤치마크를 읽어 볼 만하다. 테스트한 Codex 연동에서는 토큰 사용량과 실행 시간이 늘었고, 결정 대부분이 플래너로 돌아갔다. 라우팅이 자동으로 빨라지는 것은 아니며 개발자도 그렇게 밝힌다.
Getting Started
- Python 3.11 이상에서 uv로 CLI를 설치한다.
uv tool install --force --with 'mcp>=2,<3' 'git+https://github.com/Protocol-Lattice/harness-router.git@main'을 실행하면har,harness-router,harness-router-mcp가 준비된다. - 하네스 프로세스가 읽는 환경에
OPENROUTER_API_KEY를 설정한다. 기본 모델은typesafe/jev-1.13이고, 키가 없으면 플래너 폴백이 반환된다. - 쓰는 공급자에 맞는 hook 설치 스크립트를 실행하고 빠진 어댑터 두 개를 직접 복사한다. Codex와 Claude Code는 hooks 폴더에
pre_decision.py와stop.py가 필요하고, 설치 스크립트는 설정을 합치기 전에 백업을 만든다. - 새 세션을 연다. 시작 훅이 도구 목록을 훑고, 프롬프트와 결과 콜백이 선택을 미리 계산하며, 검증 훅은 저장된 결정을 모델에 다시 묻지 않고 대조한다.
제품 정보
Harness Router의 요금, 지원 플랫폼, 성능을 한눈에 확인해 보세요.
추천 대상
이 도구가 가장 잘 맞는 사용자, 작업, 상황입니다.
사용자
- Codex나 Claude Code로 긴 작업을 돌리는 개발자. 모델 요청 전에 선택을 미리 계산하므로 에이전트가 목록을 다시 훑지 않고 이름이 정해진 도구로 한 걸음을 시작한다.
- MCP 도구 등록이 스무 개를 넘은 팀. 도구가 24개를 넘으면 기본 설정이 범주를 먼저 고르고 그 안에서 도구를 고를 수 있어 프롬프트가 짧아진다.
- 직접 에이전트 루프를 만드는 사람. Python API, CLI, MCP 서버가 같은 결정 경로를 쓰므로 하네스에 연결하기 전에 라우팅을 시험할 수 있다.
작업
- 비슷한 읽기 도구 중 하나를 고르기. `read_file`, `search_code`, grep 계열이 모두 관측에 맞는 상황에서도 신뢰도가 붙은 후보 하나를 돌려주고 모델에 추측을 맡기지 않는다.
- 테스트 실패 뒤 흐름 되돌리기. 결과 콜백이 실패를 새 관측으로 바꾸고 다음 결정에 반영한다.
- 라우팅과 일반 플래너 비교하기. 같은 작업을 훅을 켜고 끈 채로 각각 돌려 토큰, 도구 호출, 통과율을 나란히 본다.
활용 상황
- 같은 상태가 반복되는 디버깅 세션. 훅 캐시는 목표, 관측, 직전 행동, 도구 목록을 키로 쓰므로 상태가 그대로면 최근 결정을 재사용한다.
- 도구 목록이 계속 커지는 프로젝트. 범주 우선 라우팅이 Jev에 넘기기 전에 후보를 줄인다. 기본값이 노리는 상황이 바로 이쪽이다.
- AI 도구 라우팅 첫 실험. 먼저 MCP 서버나 CLI 한 번 호출로 시작하고 숫자를 확인한 뒤 실제 프로젝트에 훅을 설치한다.
주요 기능
신뢰도가 붙은 다음 도구 결정
호출마다 도구 이름, 범주, 신뢰도, 폴백 플래그가 돌아온다. 호스트는 이 값을 두 기준선과 비교한다. 0.85 이상이면 그대로 채택하고 0.60 아래면 플래너로 되돌린다. 라우터를 믿을 때와 무시할 때가 명확히 갈린다.
신뢰 수준에 맞춘 세 가지 모드
hybrid는 확신 있는 선택을 받아들이고 불확실하거나 처리된 공급자 오류에서는 플래너로 돌아간다. jev_only는 폴백 기준선을 넘는 선택을 모두 받아들이고 오류를 그대로 드러낸다. planner_only는 모델 호출 자체를 건너뛴다. 하네스 코드를 건드리지 않고 요청마다 모드를 바꿀 수 있다.
모델 호출 전에 걸리는 결정 캐시
훅 브리지는 목표, 관측, 직전 행동, 압축한 도구 목록으로 상태 키를 만든다. 같은 상태면 저장된 선택을 재사용하고, 기본 캐시는 세션당 512건을 300초 동안 유지한다. 라이브러리에는 목표와 도구 집합이 그대로일 때 확신이 높은 선택만 담는 작은 캐시도 있으며 obvious_cache_size=0으로 끌 수 있다.
OpenRouter를 거치는 Jev 라우팅
Jev는 대화 모델이 아니라 결정 모델이다. 상태와 닫힌 선택지 목록을 받아 문장 대신 확률을 돌려준다. 도구 고르기 같은 분류 작업에 맞는다. 기본 모델은 typesafe/jev-1.13이고 자기 키로 OpenRouter를 통해 호출한다. 도구가 24개를 넘으면 범주를 먼저 정하고 그 안에서 도구를 고를 수 있다.
선택형 MCTS 도구 탐색
첫 수가 이후 결과에 달려 있을 때 몬테카를로 트리 탐색이 쓸모 있다. 예측한 상태와 전이 그래프를 넘기고 시뮬레이션 횟수를 1에서 4,096까지, 깊이를 최대 8까지 정한다. 탐색은 시뮬레이션 위에서만 돌고 실제 도구는 건드리지 않는다. 돌아오는 것은 첫 행동과 주요 변화 계열이다. 시뮬레이터가 없으면 선택은 플래너로 간다.
다섯 가지 하네스 어댑터
Codex, Claude Code, ohmypi, Antigravity, DeepSeek Harness에는 각 호스트가 여는 콜백에 맞춘 어댑터가 있다. Codex와 Claude Code는 세션 시작, 프롬프트, 도구 결과, 실행 전 검증 훅을 쓴다. ohmypi는 살아 있는 등록 정보를 읽고 활성 도구 집합을 바꾼다. Antigravity는 호출과 결과 콜백을 쓴다. 공용 Stop 훅은 최신의 확신 있는 결정이 남아 있으면 한 걸음 더 요청할 수 있다.
장단점
장점
- MIT 라이선스에 계정도 구독도 루프 안의 호스팅 서비스도 없다. 소스 전체를 감사하고 고칠 수 있다.
- 폴백이 기본 결말이다. 신뢰도 부족, 키 누락, 공급자 오류는 플래너에 제어를 돌려주고 잘못된 도구 호출을 밀어붙이지 않는다.
- 결정 계층 하나로 다섯 하네스에 Python API, CLI, MCP 서버까지 덮는다. 호스트마다 선택 로직을 다시 쓸 필요가 없다.
- 공개 벤치마크가 한 연동의 부정적 결과를 그대로 적었다. 드문 태도이고 나머지 문서의 신뢰도를 끌어올린다.
- 캐시와 범주 우선 라우팅은 라우터가 값을 하는 두 상황을 겨냥한다. 상태 반복과 지나치게 큰 도구 목록이다.
단점
- 테스트한 Codex 구성에서 라우팅은 메인 모델 토큰을 105.9% 늘리고 평균 시간을 115.8초에서 228.9초로 밀어 올렸다. 58건 중 54건이 플래너로 돌아갔다. 돌아가는 프로젝트에 켜기 전에 직접 재 봐야 한다.
- 라우팅마다 목표, 관측, 도구 설명이 OpenRouter로 전송되고 세션 파일에도 그 문장이 `.harness-router/` 아래에 남는다. 자격 증명과 비밀은 이 입력에 넣지 말아야 한다.
- 프로젝트가 alpha이고 태그된 릴리스가 아직 없다. Codex와 Claude Code 어댑터는 설치 후에도 수동 복사가 필요하다.
- MCTS는 부작용 없는 시뮬레이터를 제공할 때만 성립한다. 대부분 팀은 캐시와 Jev 경로만 쓰고 탐색 계층까지는 가지 않는다.
자주 묻는 질문
에이전트 루프에서 다음 도구를 고른다. 목표, 현재 관측, 사용 가능한 도구를 넘기면 도구 이름과 신뢰도, 또는 플래너 폴백이 돌아온다. 인자 구성과 실행은 여전히 하네스 몫이다.
관련 콘텐츠
Harness Router와 관련된 도구, 스킬, 아티클을 살펴보세요.
Harness Router 대안
Base Code
Base44 (Wix) · 코딩 · 생산성Base Code는 Base44가 만든 공유 클라우드 개발 환경이다. 팀은 기존 GitHub 저장소에 대한 변경을 채팅으로 설명하고, 미리보기로 확인한 뒤 풀 리퀘스트로 돌려보낸다.
Google EmbeddingGemma 2
Google DeepMind · 글쓰기 · 이미지 · 코딩Google EmbeddingGemma 2는 7억 4000만 파라미터의 오픈 모델로, 텍스트와 코드, 이미지, 오디오, 영상 프레임을 하나의 768차원 공간에 벡터로 바꿔 스마트폰과 노트북에서 실행한다.
GitGlow
GitGlow · 코딩 · 생산성GitGlow는 내 코드와 AI 에이전트의 변경을 한 리뷰에 모으는 데스크톱 Git 클라이언트다. 배포 전에 내 기계에서 무엇이 나가는지 확인할 수 있다.