본문은 요즘IT가 Vivek Trivedy(비벡 트리베디) 님의 글<The Anatomy of an Agent Harness>를 번역한 글입니다. 필자는 LangChain의 프로덕트 매니저로, 에이전트·하네스·평가(Evals)를 담당하며 오픈소스 에이전트 프레임워크 개발을 이끌고 있습니다. 이전에는 AWS에서 과학자(Scientist)로 근무하며 Temple University에서 컴퓨터 과학 박사 학위를 취득했습니다.

이 글은 AI 에이전트 시스템에서 모델을 감싸는 인프라, 즉 '하네스(Harness)'의 개념을 정의하고, 파일시스템·샌드박스·메모리·컨텍스트 관리 등 핵심 구성 요소를 모델의 한계에서 역추적하여 도출하는 과정을 담고 있습니다. LangChain이 자사 코딩 에이전트의 하네스만 변경하여 Terminal Bench 2.0에서 Top 30에서 Top 5로 끌어올린 사례를 포함해, 하네스 엔지니어링의 현재와 미래를 구체적으로 소개합니다.

필자에게 허락을 받고 번역했으며, 글에 포함된 링크는 원문에 따라 표시했습니다.

누가 "하네스"를 좀 정의해줄래요?

에이전트 = 모델 + 하네스(harness)

모델이 아닌 모든 것이 하네스입니다. 하네스란 모델 그 자체가 아닌 모든 코드, 설정, 실행 로직을 말합니다. 날것의 모델(raw model)은 에이전트가 아닙니다. 하지만 하네스가 모델에게 상태(state), 도구 실행, 피드백 루프, 강제 가능한 제약 같은 것들을 부여하는 순간, 모델은 에이전트가 됩니다.

구체적으로 하네스는 다음과 같은 것들을 포함합니다.

시스템 프롬프트
도구(Tools), 스킬(Skills), MCP와 그 설명들
번들링된 인프라(파일시스템, 샌드박스, 브라우저)
오케스트레이션 로직(서브에이전트 생성, 핸드오프, 모델 라우팅)
결정론적 실행을 위한 훅/미들웨어(compaction, continuation, lint check)

에이전트 시스템에서 모델과 하네스의 경계를 나누는 방법은 여러 가지고, 꽤 지저분합니다. 하지만 제 생각에 위 정의가 가장 깔끔합니다. 왜냐하면 이 정의는 모델의 지능(intelligence)을 중심에 두고 시스템을 설계하도록 강제하기 때문입니다.

이 글의 나머지 부분에서는 하네스의 핵심 구성 요소들을 하나씩 살펴보면서, 모델이라는 핵심 프리미티브(primitive)에서 출발해 각 구성 요소가 왜 존재해야 하는지를 역으로 도출해보겠습니다.

왜 하네스가 필요한가: 모델의 관점에서

우리가 에이전트에게 시키고 싶은 일들 중에는, 모델이 그 자체로는 할 수 없는 것들이 있습니다. 바로 이 지점에서 하네스가 등장합니다. 모델은 (대체로) 텍스트, 이미지, 오디오, 비디오 같은 데이터를 입력받아 텍스트를 출력합니다. 그게 전부입니다. 모델은 기본적으로 다음을 할 수 없습니다.

상호작용 간에 지속 가능한 상태 유지
코드 실행
실시간 지식 접근
작업 완수를 위한 환경 세팅 및 패키지 설치

이것들은 모두 하네스 레벨의 기능입니다. LLM이라는 구조 자체가, 유용한 일을 시키려면 모델을 감싸는 어떤 기계 장치를 필요로 합니다.

예를 들어, "대화하기"라는 제품 UX를 만들려면 이전 메시지들을 추적하고 새 사용자 메시지를 덧붙이기 위해 모델을 while 루프로 감싸야 합니다. 이 글을 읽고 있는 분이라면 이미 이런 종류의 하네스를 써본 셈입니다. 핵심은, 우리가 원하는 에이전트의 행동을 하네스의 실제 기능으로 변환한다는 것입니다.

원하는 에이전트 행동에서 하네스 엔지니어링으로 역산하기

하네스 엔지니어링은 인간이 에이전트의 행동을 유도하기 위한 유용한 사전 지식(prior)을 주입하는 일입니다. 그리고 모델이 더 똑똑해질수록, 하네스는 이전에는 불가능했던 작업을 완수하도록 모델을 정교하게 확장하고 교정하는 용도로 쓰이고 있습니다.

모든 하네스 기능을 빠짐없이 다루지는 않을 겁니다. 목표는 "모델이 유용한 일을 하게 돕는다"는 출발점에서 일련의 기능들을 도출해보는 것입니다. 다음과 같은 패턴을 따라가 보겠습니다.

우리가 원하는(또는 고치고 싶은) 행동 → 모델이 그것을 달성하게 돕는 하네스 설계

지속적 저장과 컨텍스트 관리를 위한 파일시스템

우리는 에이전트가 실제 데이터와 상호작용하고, 컨텍스트에 담기지 않는 정보를 덜어내고, 세션을 넘나들며 작업을 지속하도록 하고 싶습니다.

모델은 컨텍스트 윈도우 안의 지식에 대해서만 직접 작업할 수 있습니다. 파일시스템이 도입되기 전에는 사용자가 모델에게 내용을 복사·붙여넣기 해야 했습니다. UX가 번거롭고, 자율 에이전트에는 적용할 수도 없습니다. 세상은 이미 작업을 위해 파일시스템을 쓰고 있었고, 덕분에 모델은 파일시스템 사용법을 수십억 토큰으로 자연스럽게 학습한 상태였습니다. 그래서 자연스러운 해결책은 이것이 됐습니다.

하네스는 파일시스템 추상화와 파일 시스템 작업(fs-ops)용 도구를 기본 탑재합니다. 파일시스템은 아마도 가장 근본적인 하네스 프리미티브일 것입니다. 다음과 같은 것들을 가능하게 하기 때문입니다.

에이전트에게 데이터, 코드, 문서를 읽을 수 있는 작업 공간이 생깁니다.
모든 것을 컨텍스트에 붙들고 있는 대신, 작업을 점진적으로 더하거나 덜어낼 수 있습니다. 중간 산출물을 저장하고, 한 세션을 넘어서는 상태를 유지할 수 있습니다.
파일시스템은 자연스러운 협업 표면입니다. 여러 에이전트와 인간이 공유된 파일을 통해 협업할 수 있습니다. 에이전트 팀(Agent Teams) 같은 아키텍처가 이 위에서 돌아갑니다.
Git을 더하면 파일시스템에 버전 관리가 붙어, 에이전트가 작업을 추적하고, 에러를 롤백하고, 실험을 브랜치로 나눌 수 있게 됩니다.

파일시스템은 뒤에서 다시 등장합니다. 알고 보면 이것이 다른 여러 기능의 기반이 되는 핵심 하네스 프리미티브이기 때문입니다.

범용 도구로서의 Bash와 코드

우리는 인간이 모든 도구를 미리 설계하지 않아도 에이전트가 자율적으로 문제를 해결하기를 원합니다.

오늘날 에이전트 실행의 주류 패턴은 ReAct 루프입니다. 모델이 추론하고, 도구 호출로 행동하고, 결과를 관찰하고, 이를 while 루프 안에서 반복하는 방식입니다. 하지만 하네스는 자기가 로직을 갖고 있는 도구만 실행할 수 있습니다. 사용자에게 가능한 모든 행동에 대한 도구를 일일이 만들라고 요구하는 건 좋은 해결책이 아닙니다. 더 나은 방법은 에이전트에게 bash 같은 범용 도구를 주는 것입니다.

하네스는 bash 도구를 기본 탑재해, 모델이 코드를 작성하고 실행하며 자율적으로 문제를 풀 수 있게 합니다. Bash와 코드 실행은 모델에게 컴퓨터를 쥐여주고 나머지는 알아서 하게 하는 방향으로 가는 큰 도약입니다. 모델은 미리 설정된 고정된 도구 세트에 갇히지 않고, 코드를 통해 즉석에서 자신만의 도구를 설계할 수 있습니다.

하네스는 여전히 다른 도구들도 함께 제공하지만, 코드 실행은 자율적 문제 해결의 기본 전략으로 자리 잡았습니다.

작업을 실행하고 검증하기 위한 샌드박스와 도구

에이전트는 안전하게 행동하고, 결과를 관찰하며, 진전을 이룰 수 있는 적절한 기본 환경이 필요합니다. 모델에게 저장 공간과 코드 실행 능력을 줬지만, 이 모든 것이 어딘가에서 일어나야 합니다. 에이전트가 만든 코드를 로컬에서 그대로 실행하는 건 위험하고, 단일 로컬 환경은 대규모 에이전트 워크로드에는 적합하지 않습니다.

샌드박스는 에이전트에게 안전한 실행 환경을 제공합니다. 로컬 대신, 하네스가 샌드박스에 연결해 코드를 실행하고, 파일을 살펴보고, 의존성을 설치하고, 작업을 완료합니다. 이 방식은 격리된 안전한 코드 실행을 가능하게 합니다. 보안을 더 강화하려면, 하네스에서 허용 명령어를 화이트리스트로 지정하고 네트워크 격리를 강제할 수도 있습니다. 샌드박스는 확장성도 열어줍니다. 필요할 때 환경을 생성하고, 여러 작업에 병렬로 뿌리고, 끝나면 정리할 수 있기 때문입니다.

좋은 환경은 좋은 기본 도구들과 함께 옵니다. 하네스는 에이전트가 유용한 일을 할 수 있도록 도구를 구성할 책임이 있습니다. 언어 런타임과 패키지 사전 설치, git과 테스트용 CLI, 웹 상호작용 및 검증용 브라우저 등이 여기 포함됩니다.

브라우저, 로그, 스크린샷, 테스트 러너 같은 도구는 에이전트가 자기 작업을 관찰하고 분석할 수 있게 해줍니다. 이를 통해 에이전트는 자기 검증 루프를 만들 수 있습니다. 애플리케이션 코드를 작성하고, 테스트를 돌리고, 로그를 살펴보고, 에러를 고치는 식으로요.

모델은 기본적으로 자기 실행 환경을 스스로 구성하지 않습니다. 에이전트가 어디서 동작할지, 어떤 도구를 쓸 수 있을지, 무엇에 접근할 수 있을지, 어떻게 작업을 검증할지는 모두 하네스 수준의 설계 결정입니다.

지속적 학습을 위한 메모리와 검색

에이전트는 이전에 본 것을 기억해야 하고, 학습 시점에는 존재하지 않았던 정보에도 접근할 수 있어야 합니다. 모델은 가중치와 현재 컨텍스트에 담긴 것 외에는 추가 지식이 없습니다. 모델 가중치를 수정할 수 없는 상황에서, "지식을 추가"하는 유일한 방법은 컨텍스트 주입입니다.

메모리 측면에서도 파일시스템이 다시 핵심 프리미티브로 등장합니다. 하네스는 AGENTS.md 같은 메모리 파일 표준을 지원하고, 에이전트 시작 시 이를 컨텍스트에 주입합니다. 에이전트가 이 파일을 추가하고 수정하면, 하네스는 업데이트된 내용을 다음 컨텍스트에 불러옵니다. 이는 일종의 지속적 학습입니다. 에이전트가 한 세션에서 얻은 지식을 지속 가능하게 저장하고, 그 지식을 이후 세션에 주입하는 방식이죠.

지식 컷오프(knowledge cutoff) 때문에, 모델은 사용자가 직접 제공하지 않는 한 새로 업데이트된 라이브러리 버전 같은 데이터에 직접 접근할 수 없습니다. 최신 지식을 위해서는 웹 검색과 Context7 같은 MCP 도구들이 에이전트가 학습 이후에 등장한 정보, 예컨대 최신 라이브러리 버전이나 최신 데이터에 접근하도록 도와줍니다.

웹 검색과 최신 컨텍스트 조회 도구는 하네스에 내장할 만한 유용한 프리미티브들입니다.

컨텍스트 부패와 싸우기

작업이 진행될수록 에이전트 성능이 나빠져서는 안 됩니다. 컨텍스트 부패(context rot)는 컨텍스트 윈도우가 채워질수록 모델이 추론과 작업 수행에서 나빠지는 현상을 말합니다. 컨텍스트는 귀중하고 희소한 자원이기 때문에, 하네스는 이를 관리할 전략이 필요합니다.

오늘날의 하네스는 사실상 좋은 컨텍스트 엔지니어링을 전달하는 수단입니다.

Compaction은 컨텍스트 윈도우가 가득 차려 할 때 무엇을 할지의 문제를 다룹니다. compaction이 없으면 대화가 컨텍스트 윈도우를 초과했을 때 어떻게 될까요? 한 가지 선택지는 API가 에러를 내는 것입니다. 좋지 않죠. 하네스는 이런 상황을 위한 전략이 필요합니다. compaction은 기존 컨텍스트를 똑똑하게 덜어내고 요약해서, 에이전트가 계속 작업할 수 있게 해줍니다.

도구 호출 오프로딩(Tool call offloading)은 큰 도구 출력이 유용한 정보 없이 컨텍스트를 어지럽히는 문제를 줄여줍니다. 하네스는 일정 토큰 수 이상인 도구 출력에 대해 앞뒤 토큰만 남기고, 전체 출력은 파일시스템에 옮겨두어 필요할 때만 모델이 접근할 수 있게 합니다.

스킬(Skills)은 에이전트 시작 시 너무 많은 도구나 MCP 서버가 컨텍스트에 로드되어, 일을 시작하기도 전에 성능이 떨어지는 문제를 해결합니다. 스킬은 점진적 공개(progressive disclosure)를 통해 이 문제를 푸는 하네스 수준의 프리미티브입니다. 모델이 시작 시 스킬의 front-matter를 컨텍스트에 싣겠다고 선택한 건 아니지만, 하네스가 이를 지원함으로써 모델을 컨텍스트 부패로부터 보호할 수 있습니다.

장기 자율 실행

우리는 에이전트가 복잡한 작업을, 자율적으로, 정확하게, 긴 시간에 걸쳐 완수하기를 원합니다. 자율적인 소프트웨어 생성은 코딩 에이전트의 성배입니다. 하지만 오늘날의 모델들은 조기 종료(early stopping), 복잡한 문제 분해의 어려움, 여러 컨텍스트 윈도우를 넘어갈 때의 일관성 붕괴 같은 문제들을 겪습니다. 좋은 하네스는 이 모든 것을 설계에 반영해야 합니다.

여기서부터는 앞서 다룬 하네스 프리미티브들이 복리처럼 작동하기 시작합니다. 장기 작업은 여러 컨텍스트 윈도우를 넘어 작업을 지속하기 위해 지속 가능한 상태, 계획, 관찰, 검증을 모두 필요로 합니다.

세션을 가로지르는 작업 추적을 위한 파일시스템과 git

에이전트는 긴 작업 동안 수백만 토큰을 만들어내기 때문에, 파일시스템이 작업을 지속 가능하게 담아 시간에 따른 진전을 추적합니다. 여기에 git을 더하면, 새로 시작한 에이전트가 프로젝트의 최신 상태와 히스토리를 빠르게 따라잡을 수 있습니다. 여러 에이전트가 함께 일할 때도 파일시스템은 공유된 작업 원장(ledger) 역할을 합니다.

작업을 이어가기 위한 Ralph Loop

Ralph Loop은 모델이 종료하려는 시도를 훅으로 가로채, 깨끗한 컨텍스트 윈도우에 원래 프롬프트를 다시 주입해 완료 목표를 향해 계속 일하게 하는 하네스 패턴입니다. 이 패턴이 가능한 건 파일시스템 덕분입니다. 각 반복은 새 컨텍스트로 시작하되, 이전 반복의 상태를 파일에서 읽어오기 때문입니다.

궤도를 유지하기 위한 계획과 자기 검증

계획(planning)은 모델이 목표를 여러 단계로 분해하는 일입니다. 하네스는 좋은 프롬프트와, 파일시스템의 계획 파일 사용법에 대한 리마인더 주입을 통해 이를 지원합니다. 각 단계를 완료한 뒤, 에이전트는 자기 검증(self-verification)을 통해 작업의 정확성을 점검할 때 더 잘 동작합니다. 하네스의 훅이 사전 정의된 테스트 스위트를 실행하고, 실패 시 에러 메시지를 담아 모델로 다시 루프를 돌릴 수도 있고, 모델이 스스로 자기 코드를 평가하도록 프롬프트를 설계할 수도 있습니다. 검증은 해결책을 테스트에 뿌리내리게 하고, 자기 개선을 위한 피드백 신호를 만들어냅니다.

하네스의 미래

모델 학습과 하네스 설계의 결합

오늘날 Claude Code나 Codex와 같은 에이전트 제품들은 모델과 하네스가 루프 안에 포함된 상태로 사후 학습(Post-trained)됩니다. 이를 통해 모델은 하네스 설계자가 의도한 동작(파일 시스템 조작, Bash 실행, 계획 수립, 하위 에이전트 병렬화 등)을 기본적으로 더 잘 수행하게 됩니다.

이 과정에서 유용한 프리미티브가 발견되어 하네스에 추가되고, 이는 다시 다음 세대 모델 학습에 사용되는 피드백 루프가 형성됩니다. 이 사이클이 반복되면서, 모델은 자기가 학습된 하네스 안에서 점점 더 유능해집니다.

하지만 이 공진화(co-evolution)는 일반화 측면에서 흥미로운 부작용을 낳습니다. 도구 로직을 바꾸면 모델 성능이 떨어지는 현상 같은 것들이죠. 좋은 예가 Codex-5.3 프롬프팅 가이드에 나오는, 파일 편집용 apply_patch 도구 로직에 관한 내용입니다. 진정으로 지능적인 모델이라면 패치 방식을 바꾸는 정도로 문제를 겪을 리 없지만, 하네스를 루프에 넣은 학습은 이런 식의 과적합을 만듭니다.

그렇다고 해서 모델이 사후 학습될 때 사용된 하네스가 반드시 여러분의 작업에 최적인 것은 아닙니다. Terminal Bench 2.0 리더보드가 좋은 예입니다. Claude Code 안에서의 Opus 4.6은 다른 하네스에서의 Opus 4.6보다 한참 낮은 점수를 받습니다. 이전 글에서 저희는 코딩 에이전트의 Terminal Bench 2.0 순위를 하네스만 바꿔 Top 30에서 Top 5로 끌어올린 과정을 공유한 적이 있습니다. 여러분의 작업에 맞게 하네스를 최적화하는 일에는 아직 짜낼 수 있는 즙이 많이 남아 있습니다.

하네스 엔지니어링은 어디로 가는가

모델이 더 유능해질수록, 지금 하네스에 있는 일부 기능은 모델 안으로 흡수될 것입니다. 모델은 기본적으로 계획 수립, 자기 검증, 장기 일관성 유지 등을 더 잘하게 될 것이고, 결과적으로 컨텍스트 주입과 같은 필요성은 줄어들 것입니다.

이는 시간이 흐를수록 하네스의 중요성이 낮아질 것임을 시사합니다. 하지만 프롬프트 엔지니어링이 지금도 여전히 가치 있는 것처럼, 하네스 엔지니어링도 좋은 에이전트를 만드는 데 계속 유용할 가능성이 큽니다.

하네스는 모델의 부족한 점을 보완하기도 하지만, 무엇보다 모델의 지능을 중심으로 시스템을 설계하여 효율성을 극대화하기 때문입니다. 잘 구성된 환경, 적절한 도구, 영구적인 상태, 그리고 검증 루프는 모델의 기초 지능 수준과 상관없이 더 효율적인 에이전트를 만듭니다.

하네스 엔지니어링은 저희가 LangChain에서 하네스 구축 라이브러리 deepagents를 개선하며 계속 연구하고 있는 매우 활발한 영역입니다. 아래는 저희가 현재 탐색하고 있는 문제들입니다.

공유 코드베이스 위에서 수백 개의 에이전트가 병렬로 일하도록 오케스트레이션하기
자기 트레이스를 분석해 하네스 수준의 실패 패턴을 찾아내고 고치는 에이전트
미리 설정해두는 대신, 주어진 작업에 맞춰 적절한 도구와 컨텍스트를 적시에(just-in-time) 동적으로 조립하는 하네스

이 글은 하네스가 무엇인지 정의하고, 우리가 모델에게 원하는 작업에 따라 하네스가 어떻게 형성되는지 고찰해 보는 과정이었습니다. 모델은 지능을 품고, 하네스는 그 지능을 유용하게 만드는 시스템입니다. 더 나은 하네스, 더 나은 시스템, 더 나은 에이전트를 향해.

<원문>

The Anatomy of an Agent Harness