Harness²: 에이전트가 프롬프트와 도구 구성을 고치는 방법

에이전트가 같은 실수를 반복할 때, 개발자는 프롬프트에 규칙을 추가하거나 도구 설명을 고친다. Harness²는 이 수정 과정을 실행 결과와 비교하면서 자동화하는 연구 프레임워크다. 모델 가중치는 그대로 두고, 모델 주변의 지침과 도구 구성을 바꾼다.

코딩 에이전트나 업무 자동화를 만드는 개발자라면 “어떤 설정을 바꿨고, 실제 행동이 어떻게 달라졌는가”를 기록하는 방식에 주목할 만하다. 이 글은 2026년 10월 18일 확인한 공식 저장소와 논문을 정리한 것으로, 직접 실행한 사용기는 아니다.

하네스는 모델 주변의 작업 환경이다

하네스(harness)는 모델이 에이전트로 일하도록 연결한 실행 환경을 뜻한다. 어떤 지시를 읽는지, 어떤 도구를 쓰는지, 과거 기록을 어떻게 참고하는지가 여기에 들어간다.

공식 저장소는 수정할 수 있는 요소를 여덟 가지로 나눈다.

구성 요소	역할
시스템 프롬프트	기본 역할과 작업 방식
가드레일	행동을 제한하는 지침
메모리	다시 참고할 기록
도구 사용 지침	도구를 고르고 호출하는 방법
서브에이전트	작업을 나누어 맡기는 구성
스킬	특정 작업에 필요한 절차
스크립트	반복 실행할 코드
플러그인	실행 과정에 연결하는 확장 기능

예를 들어 보고서를 만드는 에이전트가 출처를 자꾸 빠뜨린다고 하자. “출처를 잘 써라”라는 문장만 더할 수도 있지만, 자료를 수집할 때 URL을 함께 저장하는 절차를 추가할 수도 있다. 어느 쪽이 도움이 됐는지는 실행을 비교해야 알 수 있다. 이 보고서 사례는 구조를 설명하기 위한 예시다.

제안하고, 실행하고, 근거가 있는 변경을 합친다

Harness²의 작업별 개선과 경험 축적 흐름

출처: Ruiyao Xu 외, Harness² 논문 Figure 3. 원문, CC BY 4.0. 그림은 수정하지 않았다.

논문의 작업별 개선 과정은 세 단계다.

Propose — 변경 제안: 기존 실행을 살펴보고, 일반적인 작업 방식과 현재 분야에 맞는 수정안을 각각 만든다.
Probe — 실행 비교: 같은 작업을 수정된 환경에서 실행하고 행동과 결과물의 차이를 살핀다.
Compose — 변경 조합: 관찰된 근거를 바탕으로 수정안을 합치거나 고친다. 기존 설정을 유지할 수도 있다.

정답을 제공받지 않고 개선한다는 점이 연구의 출발점이다. 다만 실행이 달라졌다는 사실만으로 결과가 옳다는 보장은 없다. 모델이 같은 편향을 공유하거나 실행마다 결과가 흔들릴 수 있기 때문이다.

작업을 마친 뒤에는 채택한 하네스와 개선 경험을 저장한다. 다음 작업은 공통 기본 하네스에서 시작하고, 이전 경험을 참고해 필요한 부분을 선택적으로 재사용한다. 이전 작업의 설정 전체를 그대로 물려받는 구조는 아니다.

병렬은 후보를 넓히고, 순차는 수정을 이어 간다

실험 가이드에서 --k는 작업별 개선 예산이다.

실행 방식	동작
`--k 1`	제안·실행 비교·조합을 한 단계 수행
`--k 3 --mode parallel`	일반 후보 3개와 분야별 후보 3개를 탐색하고 조합 3개 생성
`--k 3 --mode sequential`	앞선 수정과 실행 근거를 이어받아 3단계 개선

따라서 k=3을 “모델을 세 번만 호출한다”는 뜻으로 읽으면 안 된다. 실행 모델뿐 아니라 수정안을 만드는 단계에도 비용이 든다.

경험은 분야별로 저장된다. 같은 분야의 작업은 순서대로 진행하며 이전 기록을 참고한다. 서로 다른 분야는 병렬로 실행할 수 있다.

성능 수치는 어디까지 확인됐나

연구진은 GLM-5와 Gemini 3.5 Flash를 OpenCode·Codex 실행 환경에 연결한 네 가지 구성으로 평가했다. 한 단계 개선에서 보고한 최대 상승 폭은 다음과 같다.

벤치마크	연구진이 보고한 최대 개선
WorkBuddy-Bench	11.5점
JobBench	4.5점
LAB	Partial 통과율 11.8%p

출처는 논문 초록과 실험 본문이다. 모두 연구진의 실험 결과이며, 모든 모델이나 작업에서 이만큼 오른다는 뜻은 아니다. LAB 수치도 전체 작업 성공률과 구분해야 한다.

내 서비스에서 평가한다면 정답률 외에 호출 비용과 완료 시간도 함께 기록할 필요가 있다. 결과가 조금 좋아져도 재실행이 크게 늘면 사용자 요청을 실시간으로 처리하는 용도에는 부담이 될 수 있다.

API 키 없이 데모부터 살펴보기

공식 README는 Linux, Python 3.12, uv를 기준으로 다음 데모를 안내한다. 먼저 저장소를 내려받아 해당 폴더로 이동한다.

git clone https://github.com/google-research/harness2.git
cd harness2

uv venv --python 3.12 .venv
source .venv/bin/activate
uv pip install -e '.[render]'

harness2-demo --output runs/demo --k 2

이 데모는 정해진 규칙으로 동작하는 편집기와 실제 Python 실행을 사용한다. 모델 인증 정보 없이 두 재귀 방식을 살펴보는 용도다. 실제 LLM의 개선 능력을 측정하는 벤치마크와는 구분해야 한다.

위 명령은 공식 설치 안내를 옮겨 정리했으며, 이 글 작성 과정에서 실행하지 않았다.

실제 모델로 실험하려면

설정 문서에 따르면 모델을 연결하는 실험에는 Node.js 20 이상, Google Cloud CLI와 인증 설정 등이 필요하다. LAB은 Pandoc·Poppler, WorkBuddy-Bench는 Docker도 요구한다.

설정은 역할별로 나뉜다.

환경 변수	역할
`HARNESS2_SOLVER_MODEL`	실제 작업을 수행하는 모델
`HARNESS2_IMPROVER_MODEL`	하네스 수정안을 만드는 모델
`HARNESS2_JUDGE_MODEL`	결과를 평가하는 모델
`HARNESS2_RUNS_DIR`	실험 결과 저장 위치

의존성·인증·모델 설정을 마친 뒤에는 작은 작업 선택부터 확인한다.

harness2-setup lab
harness2-check --bench lab

harness2 --bench lab --k 1 --mode parallel \
  --only-domains antitrust-competition --max-tasks 1 \
  --dry-run

--dry-run은 모델 호출 없이 작업 선택을 확인한다. 실제 실험은 이 옵션을 제거해야 실행된다. --max-tasks는 전체 작업 수가 아니라 분야별 작업 수의 상한이므로, 위처럼 분야도 함께 지정하는 편이 명확하다.

기본 실행기는 OpenCode다. Codex는 --substrate cx와 별도 설정으로 선택한다. 제공되는 브리지는 Gemini의 Vertex AI 호출을 Codex가 사용하는 Responses API 인터페이스로 연결한다. 모델 이름만 바꾸면 모든 조합이 자동으로 작동한다고 가정해서는 안 된다.

평가 전에 네트워크 조건부터 고정해야 한다

이 저장소에는 눈여겨볼 실행 조건이 있다. 기본 배포본은 실행기의 네트워크 접근을 제한하지 않으며, Codex는 샌드박스가 비활성화된 상태로 실행된다.

실험 문서의 Web access 항목은 검증 실행 중 Codex가 요청받지 않았는데도 JobBench의 채점 기준을 내려받은 사례를 명시한다. 공개된 정답이나 채점 기준에 접근할 수 있다면 성능 비교를 해석하기 어려워진다.

설치에 필요한 다운로드와 평가 중 허용할 네트워크를 분리하고, 실제 적용한 제한을 결과와 함께 기록해야 한다. 모델이나 작업 구성을 바꿀 때는 결과 폴더도 새로 지정하는 것이 공식 가이드의 권장 방식이다.

Harness²는 Apache 2.0으로 공개되어 있지만 Google이 공식 지원하는 제품은 아니다. 벤치마크와 제삼자 구성 요소에는 각각의 라이선스가 적용된다.

내 에이전트에 이 방식을 응용한다면, 반복되는 실패 하나부터 고르는 편이 낫다. 실패 기록, 수정한 지침, 같은 작업의 재실행 결과를 함께 남겨 보자. 그 기록이 있어야 다음 작업에서 어떤 변경을 재사용할지 판단할 수 있다.