에이전트 하네스(Agent Harness)의 구조

핵심 요약 (Key Takeaways)

복잡한 목표 분해: 계획 도구(Planning tools)를 통해 에이전트는 작업을 분해하고, 진행 상황을 추적하며, 학습함에 따라 적응할 수 있습니다.
병렬 작업 위임: 독립적인 하위 작업(Subtasks)을 위해 서브에이전트(Subagents)를 생성하며, 각 서브에이전트는 격리된 컨텍스트(Context)를 가집니다.

작성자: Vivek Trivedy

요약(TLDR): 에이전트 = 모델(Model) + 하네스(Harness). 하네스 엔지니어링(Harness engineering)은 모델을 작업 엔진으로 전환하기 위해 모델 주변에 시스템을 구축하는 방법입니다. 모델은 지능을 포함하고 있으며, 하네스는 그 지능을 유용하게 만듭니다.
**우리는 오늘 하네스가 무엇인지 정의하고, 현재와 미래의 에이전트가 필요로 하는 핵심 구성 요소를 도출합니다.

누군가 "하네스(Harness)"를 정의해 줄 수 있나요?

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

당신이 모델이 아니라면, 당신은 하네스입니다.

하네스는 모델 자체를 제외한 모든 코드, 설정, 실행 로직을 의미합니다. 가공되지 않은 모델(Raw model)은 에이전트가 아닙니다. 하지만 하네스가 상태(State), 도구 실행(Tool execution), 피드백 루프(Feedback loops), 그리고 강제 가능한 제약 조건(Enforceable constraints)과 같은 것들을 제공할 때 비로소 에이전트가 됩니다.

구체적으로 하네스에는 다음과 같은 것들이 포함됩니다:

• 시스템 프롬프트 (System Prompts)
• 도구(Tools), 기술(Skills), MCP 및 그 설명들
• 번들링된 인프라 (Bundled Infrastructure) (파일 시스템, 샌드박스, 브라우저)
• 오케스트레이션 로직 (Orchestration Logic) (서브에이전트 생성, 핸드오프, 모델 라우팅)
• 결정론적 실행을 위한 훅/미들웨어 (Hooks/Middleware) (압축, 지속, 린트 체크)

에이전트 시스템의 경계를 모델과 하네스 사이에서 나누는 복잡하고 다양한 방법들이 존재합니다. 하지만 제 생각에 이 정의가 가장 깔끔한 이유는, 이것이 우리가 모델의 지능을 중심으로 시스템을 설계하도록 강제하기 때문입니다.

이 포스트의 나머지 부분에서는 핵심 하네스 구성 요소를 살펴보고, 모델이라는 핵심 원시 요소(Core primitive)로부터 역순으로 추적하며 각 요소가 왜 존재하는지를 도출합니다.

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

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

• 상호작용 전반에 걸친 지속적인 상태 유지 (Maintain durable state)
• 코드 실행 (Execute code)
• 실시간 지식 접근 (Access realtime knowledge)
• 작업을 완료하기 위한 환경 설정 및 패키지 설치 (Setup environments and install packages)

이것들은 모두 **하네스 레벨 기능 (harness level features)**입니다. LLM의 구조는 유용한 작업을 수행하기 위해 모델을 감싸는 일종의 기계 장치를 필요로 합니다. 예를 들어, "채팅"과 같은 제품 UX를 구현하기 위해, 우리는 이전 메시지를 추적하고 새로운 사용자 메시지를 추가할 수 있도록 모델을 while 루프 안에 감쌉니다. 이 글을 읽는 모든 사람은 이미 이런 종류의 하네스를 사용해 본 적이 있을 것입니다. 핵심 아이디어는 우리가 원하는 에이전트의 행동을 하네스의 실제 기능으로 변환하는 것입니다.

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

하네스 엔지니어링 (Harness Engineering)은 인간이 에이전트의 행동을 안내할 수 있도록 유용한 사전 지식 (priors)을 주입하는 것을 돕습니다. 그리고 모델의 능력이 향상됨에 따라, 하네스는 이전에는 불가능했던 작업을 완료하기 위해 모델을 정교하게 확장하고 교정하는 데 사용되어 왔습니다.

모든 하네스 기능의 포괄적인 목록을 다루지는 않을 것입니다. 목표는 모델이 유용한 작업을 수행하도록 돕는다는 시작점에서 일련의 기능들을 도출하는 것입니다. 우리는 다음과 같은 패턴을 따를 것입니다:

우리가 원하는 (또는 수정하고 싶은) 행동 → 모델이 이를 달성하도록 돕는 하네스 설계.

지속적인 저장 및 컨텍스트 관리를 위한 파일 시스템 (Filesystems)

우리는 에이전트가 실제 데이터와 인터페이스하고, 컨텍스트 (context)에 담기지 않는 정보를 오프로드(offload)하며, 세션 전반에 걸쳐 작업을 유지할 수 있는 지속적인 저장 공간을 갖기를 원합니다.

모델은 오직 자신의 컨텍스트 윈도우 (context window) 내에 있는 지식에 대해서만 직접적으로 작동할 수 있습니다. 파일 시스템이 있기 전에는 사용자가 콘텐츠를 모델에 직접 복사/붙여넣기 해야 했으며, 이는 투박한 UX이며 자율 에이전트에게는 적합하지 않습니다. 세상은 이미 작업을 수행하기 위해 파일 시스템을 사용하고 있었고, 따라서 모델은 파일 시스템을 사용하는 방법에 대한 수십억 개의 토큰을 통해 자연스럽게 학습되었습니다. 이에 따른 자연스러운 해결책은 다음과 같습니다:

하네스는 파일 시스템 추상화 (filesystem abstractions) 및 파일 시스템 작업 (fs-ops)을 위한 도구들을 함께 제공합니다.

파일 시스템은 그것이 가능하게 하는 기능들 때문에 단연코 가장 기초적인 하네스 기본 요소 (harness primitive)라고 할 수 있습니다:

• 에이전트(Agents)는 데이터, 코드, 문서를 읽을 수 있는 작업 공간(workspace)을 할당받습니다.
• 모든 것을 컨텍스트(context)에 유지하는 대신, 작업을 점진적으로 추가하거나 오프로드(offload)할 수 있습니다. 에이전트는 중간 출력물(intermediate outputs)을 저장하고 단일 세션보다 오래 지속되는 상태(state)를 유지할 수 있습니다.
  파일 시스템(filesystem)은 자연스러운 협업 표면(collaboration surface)입니다. 여러 에이전트와 인간이 공유 파일을 통해 협업할 수 있습니다. 에이전트 팀(Agent Teams)과 같은 아키텍처는 이에 의존합니다.

Git은 파일 시스템에 버전 관리(versioning) 기능을 추가하여 에이전트가 작업 내용을 추적하고, 오류를 롤백(rollback)하며, 실험을 브랜치(branch)할 수 있게 합니다. 파일 시스템은 우리가 필요로 하는 다른 기능들을 위한 핵심적인 하네스 기본 요소(harness primitive)임이 밝혀졌기에, 아래에서 더 자세히 살펴보겠습니다.

범용 도구로서의 Bash + 코드

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

오늘날 주요 에이전트 실행 패턴은 모델이 추론하고, 도구 호출(tool call)을 통해 행동을 취하며, 결과를 관찰하고, 이를 while 루프 내에서 반복하는 ReAct 루프입니다. 하지만 하네스는 로직이 구현된 도구만을 실행할 수 있습니다. 사용자에게 가능한 모든 행동에 대한 도구를 구축하도록 강요하는 대신, 더 나은 해결책은 에이전트에게 bash와 같은 범용 도구를 제공하는 것입니다.

하네스는 bash 도구를 함께 제공하므로, 모델은 코드를 작성하고 실행함으로써 자율적으로 문제를 해결할 수 있습니다.

Bash + 코드 실행(code exec)은 모델에게 컴퓨터를 부여하고, 모델이 나머지를 자율적으로 파악하도록 하는 큰 진전입니다. 모델은 미리 구성된 고정된 도구 세트에 국한되는 대신, 코드를 통해 즉석에서 자신만의 도구를 설계할 수 있습니다.

하네스에는 여전히 다른 도구들이 포함되어 있지만, 코드 실행은 자율적인 문제 해결을 위한 기본 범용 전략이 되었습니다.

작업 실행 및 검증을 위한 샌드박스(Sandboxes)와 도구

에이전트가 안전하게 행동하고, 결과를 관찰하며, 진전을 이룰 수 있도록 적절한 기본 설정(defaults)을 갖춘 환경이 필요합니다.

우리는 모델에게 저장 공간과 코드를 실행할 수 있는 능력을 부여했지만, 이 모든 과정은 어딘가에서 이루어져야 합니다. 에이전트가 생성한 코드를 로컬(locally)에서 실행하는 것은 위험하며, 단일 로컬 환경은 대규모 에이전트 워크로드(workloads)를 감당할 만큼 확장성(scale)을 갖추지 못합니다.

샌드박스(Sandboxes)는 에이전트에게 안전한 운영 환경을 제공합니다. 하네스(harness)는 코드를 로컬에서 실행하는 대신 샌드박스에 연결하여 코드를 실행하고, 파일을 검사하며, 의존성(dependencies)을 설치하고, 작업을 완료할 수 있습니다. 이를 통해 코드의 안전하고 격리된 실행(isolated execution)이 가능해집니다. 보안을 더욱 강화하기 위해 하네스는 명령어를 화이트리스트(allow-list)로 관리하거나 네트워크 격리(network isolation)를 강제할 수 있습니다. 또한 샌드박스는 환경을 필요에 따라 생성하고, 여러 작업에 걸쳐 확장(fanned out)하며, 작업이 완료되면 폐기할 수 있기 때문에 확장성(scale)을 확보할 수 있습니다.

좋은 환경에는 좋은 기본 도구(default tooling)가 수반됩니다. 하네스는 에이전트가 유용한 작업을 수행할 수 있도록 도구를 구성할 책임이 있습니다. 여기에는 언어 런타임(language runtimes) 및 패키지의 사전 설치, git 및 테스트를 위한 CLI, 웹 상호작용 및 검증을 위한 브라우저(browsers) 등이 포함됩니다.

브라우저, 로그(logs), 스크린샷, 테스트 러너(test runners)와 같은 도구는 에이전트가 자신의 작업을 관찰하고 분석할 수 있는 방법을 제공합니다. 이는 에이전트가 애플리케이션 코드를 작성하고, 테스트를 실행하며, 로그를 검사하고, 오류를 수정할 수 있는 자기 검증 루프(self-verification loops)를 형성하는 데 도움을 줍니다.

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

지속적 학습을 위한 메모리 및 검색 (Memory & Search for Continual Learning)

에이전트는 자신이 본 것을 기억해야 하며, 학습 당시에는 존재하지 않았던 정보에 접근할 수 있어야 합니다.

모델은 자신의 가중치(weights)와 현재 컨텍스트(context)에 포함된 내용 외에는 추가적인 지식을 가지고 있지 않습니다. 모델의 가중치를 수정할 수 있는 권한이 없다면, "지식을 추가"하는 유일한 방법은 **컨텍스트 주입(context injection)**을 통하는 것입니다.

메모리(memory)의 경우, 파일 시스템(filesystem)이 다시 한번 핵심적인 기본 요소(primitive)로 작용합니다. 하네스(Harnesses)는 에이전트 시작 시 컨텍스트(context)에 주입되는 AGENTS.md와 같은 메모리 파일 표준을 지원합니다. 에이전트가 이 파일을 추가하거나 수정함에 따라, 하네스는 업데이트된 파일을 컨텍스트로 로드합니다. 이는 에이전트가 한 세션에서 얻은 지식을 영구적으로 저장하고 해당 지식을 향후 세션에 주입하는 일종의 지속적 학습(continual learning) 형태입니다.

지식 컷오프(Knowledge cutoffs)는 사용자가 직접 제공하지 않는 한, 모델이 업데이트된 라이브러리 버전과 같은 새로운 데이터에 직접 접근할 수 없음을 의미합니다. 최신 지식을 유지하기 위해, 웹 검색(Web Search) 및 Context7과 같은 MCP 도구들은 에이전트가 학습이 중단되었을 당시에는 존재하지 않았던 새로운 라이브러리 버전이나 현재 데이터와 같이 지식 컷오프를 넘어서는 정보에 접근할 수 있도록 돕습니다.

웹 검색과 최신 컨텍스트를 쿼리하기 위한 도구들은 하네스에 내장하기 유용한 기본 요소(primitives)입니다.

컨텍스트 부패(Context Rot)와의 싸움

에이전트의 성능은 작업 과정 중에 저하되어서는 안 됩니다.

컨텍스트 부패(Context Rot)는 컨텍스트 창(context window)이 채워짐에 따라 모델의 추론 및 작업 완료 능력이 어떻게 저하되는지를 설명합니다. 컨텍스트는 귀중하고 희소한 자원이므로, 하네스는 이를 관리하기 위한 전략이 필요합니다.

오늘날의 하네스는 대체로 훌륭한 컨텍스트 엔지니어링(context engineering)을 위한 전달 메커니즘입니다.

**압축(Compaction)**은 컨텍스트 창이 거의 가득 찼을 때 무엇을 해야 하는지를 다룹니다. 압축이 없다면 대화가 컨텍스트 창을 초과할 때 어떤 일이 발생할까요? 한 가지 옵션은 API 오류가 발생하는 것인데, 이는 좋지 않습니다. 하네스는 이 경우를 위한 어떤 전략을 사용해야 합니다. 따라서 압축은 기존 컨텍스트 창을 지능적으로 오프로드(offload)하고 요약하여 에이전트가 작업을 계속할 수 있도록 합니다.

**도구 호출 오프로딩(Tool call offloading)**은 유용한 정보를 제공하지 않으면서 컨텍스트 창을 소란스럽게 어지럽힐 수 있는 대규모 도구 출력(tool outputs)의 영향을 줄이는 데 도움이 됩니다. 하네스는 도구 출력의 헤드(head)와 테일(tail) 토큰을 일정 임계값 이상의 토큰으로 유지하고, 전체 출력은 파일 시스템으로 오프로드하여 모델이 필요할 경우 접근할 수 있도록 합니다.

Skills는 에이전트 시작 시 컨텍스트(Context)에 너무 많은 도구(Tools)나 MCP 서버가 로드되어 에이전트가 작업을 시작하기도 전에 성능이 저하되는 문제를 해결합니다. Skills는 **점진적 공개 (Progressive Disclosure)**를 통해 이 문제를 해결하는 하네스(Harness) 레벨의 프리미티브(Primitive)입니다. 모델이 시작 시 Skill 프런트매터(Front-matter)를 컨텍스트에 로드하도록 선택한 것은 아니지만, 하네스는 컨텍스트 부패(Context rot)로부터 모델을 보호하기 위해 이를 지원할 수 있습니다.

장기 지평 자율 실행 (Long Horizon Autonomous Execution)

우리는 에이전트가 복잡한 업무를 자율적으로, 정확하게, 그리고 장기적인 지평(Long time horizons)에 걸쳐 완수하기를 원합니다.

자율적인 소프트웨어 생성은 코딩 에이전트의 성배(Holy grail)입니다. 하지만 오늘날의 모델들은 작업이 여러 컨텍스트 창(Context windows)에 걸쳐 확장됨에 따라 조기 종료(Early stopping), 복잡한 문제 분해 문제, 그리고 일관성 결여(Incoherence) 문제를 겪습니다. 훌륭한 하네스는 이 모든 것을 고려하여 설계되어야 합니다.

이 지점에서 앞서 언급한 하네스 프리미티브들이 결합되기 시작합니다. 장기 지평의 작업은 여러 컨텍스트 창을 가로질러 작업을 지속하기 위해 내구성이 있는 상태(Durable state), 계획(Planning), 관찰(Observation), 그리고 검증(Verification)을 필요로 합니다.

세션 간 작업 추적을 위한 파일 시스템(Filesystems) 및 git. 에이전트는 긴 작업 과정에서 수백만 개의 토큰을 생성하므로, 파일 시스템은 작업 내용을 내구성 있게 캡처하여 시간이 지남에 따라 진행 상황을 추적합니다. 여기에 git을 추가하면 새로운 에이전트가 프로젝트의 최신 작업 내용과 이력을 빠르게 파악할 수 있습니다. 여러 에이전트가 함께 협업하는 경우, 파일 시스템은 에이전트들이 협력할 수 있는 작업의 공유 원장(Shared ledger) 역할도 수행합니다.

작업 지속을 위한 Ralph Loops. Ralph Loop는 훅(Hook)을 통해 모델의 종료 시도를 가로채고, 깨끗한 컨텍스트 창에 원래의 프롬프트(Prompt)를 다시 주입하여 에이전트가 완료 목표를 향해 작업을 계속하도록 강제하는 하네스 패턴입니다. 파일 시스템은 각 반복(Iteration)이 새로운 컨텍스트에서 시작하되 이전 반복의 상태를 읽어올 수 있게 함으로써 이를 가능하게 합니다.

궤도를 유지하기 위한 계획(Planning) 및 자기 검증(Self-verification). 계획(Planning)은 모델이 목표를 일련의 단계로 분해하는 과정입니다. 하네스(Harnesses)는 정교한 프롬프팅(Prompting)과 파일 시스템 내의 계획 파일(Plan file)을 사용하는 방법을 상기시키는 명령을 주입함으로써 이를 지원합니다. 각 단계를 완료한 후, 에이전트는 **자기 검증(Self-verification)**을 통해 자신의 작업이 정확한지 확인함으로써 이점을 얻습니다. 하네스의 훅(Hooks)은 미리 정의된 테스트 스위트(Test suite)를 실행하고, 실패 시 에러 메시지와 함께 모델로 다시 루프(Loop back)를 돌리거나, 모델이 독립적으로 자신의 코드를 스스로 평가하도록 프롬프팅할 수 있습니다. 검증은 테스트를 통해 솔루션을 근거 있게 만들며, 자기 개선(Self-improvement)을 위한 피드백 신호를 생성합니다.

하네스의 미래

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

Claude Code 및 Codex와 같은 오늘날의 에이전트 제품들은 모델과 하네스가 루프(Loop) 안에 포함된 상태로 사후 학습(Post-trained)됩니다. 이는 모델이 파일 시스템 작업, bash 실행, 계획(Planning), 또는 서브 에이전트(Subagents)를 통한 작업 병렬화와 같이 하네스 설계자가 모델이 본래 잘해야 한다고 생각하는 동작들을 개선하는 데 도움을 줍니다.

이는 피드백 루프(Feedback loop)를 생성합니다. 유용한 프리미티브(Primitives)가 발견되어 하네스에 추가되고, 이후 차세대 모델을 학습시킬 때 사용됩니다. 이 사이클이 반복됨에 따라, 모델은 자신이 학습된 하네스 내에서 더욱 강력한 능력을 갖추게 됩니다.