하네스는 AI 모델과 실제 컴퓨터 사이에 서서 모델이 뱉은 글자를 실행으로 바꾸는 프로그램이다. 모델은 다음에 올 토큰(한 번에 내놓는 글자 조각)을 이어 붙일 뿐 파일을 열지도 명령을 돌리지도 못한다. 그 글자를 셸에 던지고, 돌아온 로그를 모델이 읽을 크기로 줄여 다시 넣어 준다. 이 일을 맡은 프로그램이 하네스다.

핵심 포인트

• 모델은 글자만 낸다. pytest라고 써 놓아도 그 자체로는 아무 일도 안 벌어진다. 답이 옳은지 그른지와 무관하게, 모델의 출력은 문서 한 조각이다.
• 하네스가 그 글자를 명령으로 집행한다. 미리 약속한 표시(EXEC: 같은 접두어나 도구 호출 JSON)를 찾아내 셸과 파일 시스템에 실제로 던진다. 클로드 코드·커서·오픈 인터프리터가 전부 하네스다.

• 한 번 오가고 끝나지 않는다. 위 그림에서 ③~⑨가 실행 고리다. 테스트가 깨지면 로그가 모델로 돌아가고, 모델이 다음 명령을 내고, 하네스가 또 돌린다. 통과가 나올 때까지 이 고리를 반복하는 것이 에이전트라고 부르는 동작의 전부다.
• 결과를 그대로 넣지 않는다. 컨텍스트 창(모델이 한 번에 볼 수 있는 글자 총량)이 정해져 있어 로그 수천 줄을 통째로 넘기면 앞서 넣어 둔 지시가 밀려 나간다. ⑥에서 하네스가 실패한 줄만 남기고 줄이는 이유다.
• 지금까지의 상태는 하네스가 들고 있다. 모델은 요청과 요청 사이에 기억이 없다. 어느 디렉터리에 있는지, 무엇을 이미 고쳤는지, 쓸 수 있는 도구가 무엇인지를 요청마다 ②에서 다시 붙여 넣는다.
• 권한과 정지도 하네스가 쥔다. 파일을 지우는 명령 앞에서 사용자에게 물어보고, 같은 실패가 되풀이되면 고리를 끊는다. 모델이 같아도 이 판단이 다르면 같은 과제의 완주율이 달라진다.

type Msg = { role: "user" | "assistant" | "tool"; text: string };

async function harness(ask: string) {
  // 상태는 하네스가 들고 있다. 모델은 요청과 요청 사이에 아무것도 기억하지 않는다
①  const state: Msg[] = [{ role: "user", text: RULES + "\n" + ask }];

  while (true) {
②    const reply = await model.complete(state, TOOLS);   // 상태를 통째로 보낸다
    state.push({ role: "assistant", text: reply.text });

    // 모델이 낸 것은 글자뿐이다. 도구 호출도 실행이 아니라 JSON 한 조각이다
⑪⑫    if (reply.toolCalls.length === 0) return reply.text;

③    for (const call of reply.toolCalls) {          // 모델이 적어 보낸 명령
      if (risky(call)) await askUser(call);        // 지우는 명령 앞에서 멈춘다
④⑤      const log = await runInShell(call);          // 셸에 실제로 던진다
⑥      state.push({ role: "tool", text: shrink(log) });  // 실패한 줄만 남긴다
    }
    if (stuckOnSameError(state)) return "같은 실패가 되풀이돼 멈춥니다";
  }
}

• 실무에서 「에이전트」라고 부르는 물건은 모델과 하네스를 합친 것이다. GPT-5나 클로드 같은 모델 이름은 그중 한쪽만 가리킨다. 도구 성능을 견줄 때 모델 점수만 보면 나머지 절반을 빼고 세는 셈이다.