Agent Harness의 해부학: 모델을 작동하는 엔진으로 만드는 모든 것
원문: Viv Trivedy (@vtrivedy10), LangChain 엔지니어
서론: 에이전트란 무엇인가
에이전트를 이해하는 가장 간결한 공식이 있다. 에이전트 = 모델 + 하네스(Harness). 이 등식은 단순해 보이지만, 그 안에 에이전트 엔지니어링의 핵심이 모두 담겨 있다. 모델이 아닌 모든 것은 하네스다. 하네스란 모델 그 자체를 제외한 모든 코드, 설정, 실행 로직의 총체를 가리킨다.
날것의 모델(raw model)은 에이전트가 아니다. 모델에게 상태(state), 도구 실행, 피드백 루프, 강제 가능한 제약 조건을 부여하는 순간, 비로소 에이전트가 탄생한다. 구체적으로 하네스는 시스템 프롬프트, 도구·스킬·MCP 서버와 그 설명, 파일시스템이나 샌드박스 같은 번들 인프라, 서브에이전트 스폰·핸드오프·모델 라우팅을 아우르는 오케스트레이션 로직, 그리고 컴팩션·연속 실행·린트 검사 같은 결정론적 실행을 위한 훅(Hook)/미들웨어를 포함한다.
이 경계를 이처럼 명확히 정의하는 이유는 하나다. 시스템을 모델 지능을 중심으로 설계하도록 강제하기 위해서다. 모델과 하네스의 경계를 허물거나 혼용하면, 결국 무엇을 모델에 맡기고 무엇을 시스템으로 구현해야 하는지 판단이 흐려진다.
왜 하네스가 필요한가: 모델의 관점에서
에이전트에게 기대하는 행동 중 상당수는 모델이 기본 상태에서 수행할 수 없는 것들이다. 모델은 본질적으로 텍스트, 이미지, 오디오, 영상 같은 데이터를 입력받아 텍스트를 출력하는 함수다. 그게 전부다. 기본 상태의 모델은 상호작용 간에 지속적인 상태를 유지하거나, 코드를 실행하거나, 실시간 지식에 접근하거나, 작업 완료를 위해 환경을 설정하고 패키지를 설치하는 일을 할 수 없다. 이 모든 것이 하네스 레벨의 기능이다.
예를 들어, 사용자가 “채팅”하는 제품 UX를 구현하려면 이전 메시지를 추적하고 새로운 사용자 메시지를 추가하기 위해 모델을 while 루프로 감싸야 한다. 이 단순한 구조 자체가 이미 하네스다. 핵심 아이디어는 이것이다. 원하는 에이전트 행동을 하네스의 실제 기능으로 변환하는 것, 그것이 하네스 엔지니어링의 본질이다.
원하는 행동에서 하네스 설계로: 역방향 도출의 원칙
하네스 엔지니어링은 인간이 에이전트 행동을 유도하기 위해 유용한 사전 지식(prior)을 주입하는 과정이다. 모델이 더 유능해질수록 하네스는 모델을 정밀하게 확장하고 교정하여 이전에는 불가능했던 작업을 완수하는 데 쓰인다.
이 과정은 항상 같은 패턴을 따른다. “원하는(혹은 고쳐야 할) 행동 → 모델이 이를 달성하도록 돕는 하네스 설계.” 아래에서는 이 패턴을 따라 핵심 하네스 컴포넌트를 하나씩 도출해 나간다.
파일시스템: 지속적 저장소와 컨텍스트 관리의 기반
에이전트가 실제 데이터를 다루고, 컨텍스트에 맞지 않는 정보를 오프로드하며, 세션을 넘어 작업을 지속하려면 지속적인 저장소가 필요하다.
모델은 컨텍스트 윈도우 안에 있는 지식에만 직접 접근할 수 있다. 파일시스템이 없던 시절에는 사용자가 콘텐츠를 모델에게 직접 복사-붙여넣기 해야 했는데, 이는 어색한 UX일 뿐 아니라 자율 에이전트에게는 근본적으로 작동하지 않는 방식이다. 세상은 이미 파일시스템을 이용해 작업해왔고, 모델은 수십억 토큰의 파일시스템 사용 패턴으로 학습되었다. 그 결과 가장 자연스러운 해법이 도출되었다. 하네스에 파일시스템 추상화와 파일 작업 도구를 기본 탑재하는 것.
파일시스템은 하네스에서 가장 근본적인 프리미티브(primitive)다. 파일시스템이 있으면 에이전트는 데이터, 코드, 문서를 읽을 작업 공간을 갖는다. 모든 것을 컨텍스트에 담는 대신 작업을 점진적으로 추가하고 오프로드할 수 있으며, 단일 세션을 넘는 중간 출력과 상태를 저장할 수 있다. 파일시스템은 자연스러운 협업 표면이 되어 여러 에이전트와 인간이 공유 파일을 통해 조율할 수 있다. 여기에 Git을 더하면 에이전트는 작업을 버전 관리하고, 오류를 롤백하며, 실험을 브랜치로 분기할 수 있다.
Bash와 코드 실행: 범용 도구로서의 코드
인간이 매번 도구를 사전에 설계하지 않아도 에이전트가 자율적으로 문제를 해결하게 하려면 무엇이 필요한가.
오늘날 주된 에이전트 실행 패턴은 ReAct 루프다. 모델이 추론하고, 도구 호출을 통해 행동을 취하며, 결과를 관찰하고, 이를 반복한다. 그런데 하네스는 자신이 로직을 보유한 도구만 실행할 수 있다. 모든 가능한 행동에 대해 도구를 만들도록 사용자에게 강요하는 대신, bash 같은 범용 도구를 에이전트에게 주는 것이 훨씬 나은 해법이다.
하네스에 bash 도구를 탑재하면 모델은 코드를 작성하고 실행하여 자율적으로 문제를 해결할 수 있다. bash와 코드 실행은 모델에게 컴퓨터를 주고 나머지를 자율적으로 해결하게 하는 데 있어 큰 도약이다. 모델은 사전 구성된 고정 도구 세트에 갇히는 대신 즉석에서 코드를 통해 자신만의 도구를 설계할 수 있다. 하네스는 여전히 다른 도구들을 탑재하지만, 코드 실행은 자율적 문제 해결의 기본 전략이 되었다.
샌드박스: 안전한 실행 환경과 자기 검증
에이전트에게 저장소와 코드 실행 능력을 부여했다면, 그 모든 것이 실행될 환경이 필요하다. 에이전트가 생성한 코드를 로컬에서 실행하는 것은 위험하고, 단일 로컬 환경은 대규모 에이전트 워크로드로 확장되지 않는다.
샌드박스는 에이전트에게 안전한 운영 환경을 제공한다. 로컬에서 실행하는 대신 하네스가 샌드박스에 연결하여 코드를 실행하고, 파일을 검사하며, 의존성을 설치하고, 작업을 완수한다. 이는 코드의 안전하고 격리된 실행 환경을 만든다. 보안을 더 강화하기 위해 하네스는 명령어를 허용 목록으로 제한하고 네트워크 격리를 강제할 수 있다. 샌드박스는 필요에 따라 온디맨드로 생성하고, 여러 작업에 걸쳐 병렬 확장하며, 작업이 끝나면 삭제할 수 있어 규모 확장성도 확보된다.
좋은 환경에는 좋은 기본 도구가 따라온다. 하네스는 에이전트가 유용한 작업을 수행할 수 있도록 도구를 구성할 책임이 있다. 언어 런타임과 패키지를 사전 설치하고, git과 테스트를 위한 CLI를 구성하며, 웹 상호작용과 검증을 위한 브라우저를 준비하는 것이 여기에 해당한다. 브라우저, 로그, 스크린샷, 테스트 러너 같은 도구는 에이전트가 자신의 작업을 관찰하고 분석하는 수단이 된다. 이를 통해 에이전트는 애플리케이션 코드를 작성하고, 테스트를 실행하며, 로그를 검사하고, 오류를 수정하는 자기 검증 루프를 만들 수 있다.
메모리와 검색: 지속적 학습과 지식 갱신
에이전트는 이전에 본 것을 기억하고, 훈련 이후에 생겨난 정보에도 접근할 수 있어야 한다.
모델은 가중치와 현재 컨텍스트 안에 있는 것 이상의 지식을 가지지 않는다. 모델 가중치를 편집하지 않는 이상, “지식을 추가”하는 유일한 방법은 컨텍스트 주입이다. 메모리를 위해서 파일시스템이 다시 핵심 프리미티브로 등장한다. 하네스는 AGENTS.md 같은 메모리 파일 표준을 지원하며, 에이전트 시작 시 이를 컨텍스트에 주입한다. 에이전트가 이 파일을 추가하고 편집하면 하네스는 업데이트된 파일을 미래 세션의 컨텍스트에 로드한다. 이는 에이전트가 한 세션의 지식을 지속 저장하고 미래 세션에 그 지식을 주입하는 지속적 학습의 한 형태다.
지식 컷오프 문제는 모델이 사용자가 직접 제공하지 않으면 업데이트된 라이브러리 버전 같은 신규 데이터에 직접 접근할 수 없다는 것을 의미한다. 최신 지식을 위해 웹 검색과 Context7 같은 MCP 도구가 에이전트에게 지식 컷오프 이후의 새로운 라이브러리 버전이나 현재 데이터에 접근할 수 있도록 돕는다. 웹 검색과 최신 컨텍스트 조회 도구는 하네스에 기본 탑재할 유용한 프리미티브다.
컨텍스트 부식(Context Rot)과의 싸움
에이전트 성능은 작업 진행에 따라 저하되어서는 안 된다.
컨텍스트 부식(Context Rot)이란 컨텍스트 윈도우가 채워질수록 모델의 추론과 작업 완수 능력이 저하되는 현상을 말한다. 컨텍스트는 희소하고 귀중한 자원이기 때문에 하네스는 이를 관리하기 위한 전략이 필요하다. 오늘날의 하네스는 상당 부분 좋은 컨텍스트 엔지니어링의 전달 메커니즘으로 기능한다.
컴팩션(Compaction) 은 컨텍스트 윈도우가 가득 찰 때 무엇을 할지의 문제를 해결한다. 컴팩션 없이 대화가 컨텍스트 윈도우를 초과하면 API 오류가 발생하는데, 이는 좋지 않다. 컴팩션은 기존 컨텍스트 윈도우를 지능적으로 오프로드하고 요약하여 에이전트가 계속 작업할 수 있도록 한다.
도구 호출 오프로딩(Tool Call Offloading) 은 컨텍스트 윈도우를 잡음으로 어지럽히는 큰 도구 출력의 영향을 줄여준다. 하네스는 임계값 이상의 토큰을 가진 도구 출력의 앞뒤 토큰만 유지하고, 전체 출력을 파일시스템에 오프로드하여 필요시 모델이 접근할 수 있게 한다.
스킬(Skills) 은 에이전트 시작 시 너무 많은 도구나 MCP 서버가 컨텍스트에 로드되어 작업 시작 전부터 성능이 저하되는 문제를 해결한다. 스킬은 점진적 공개(progressive disclosure)를 통해 이 문제를 해결하는 하네스 레벨 프리미티브다. 모델이 스킬 앞부분(front-matter)을 시작 시 컨텍스트에 로드하도록 선택한 것은 아니지만, 하네스가 이를 지원함으로써 모델을 컨텍스트 부식으로부터 보호한다.
장기 자율 실행: Ralph 루프와 자기 검증
에이전트가 복잡한 작업을 자율적으로, 올바르게, 장기간에 걸쳐 완수하게 하는 것은 코딩 에이전트의 성배다. 오늘날의 모델은 조기 종료, 복잡한 문제 분해 실패, 여러 컨텍스트 윈도우에 걸친 비일관성 문제를 안고 있다. 좋은 하네스는 이 모든 것을 설계로 극복해야 한다.
바로 이 지점에서 앞서 살펴본 하네스 프리미티브들이 복합적으로 작동하기 시작한다. 장기 작업을 위해서는 지속적 상태, 계획, 관찰, 검증이 여러 컨텍스트 윈도우에 걸쳐 계속 작동해야 한다.
파일시스템과 Git은 세션을 넘는 작업 추적을 가능하게 한다. 에이전트는 장기 작업에서 수백만 토큰을 생성하기 때문에 파일시스템이 작업을 지속 캡처하여 시간의 흐름에 따른 진행 상황을 추적한다. Git을 추가하면 새로운 에이전트가 프로젝트의 최신 작업과 이력을 빠르게 파악할 수 있고, 여러 에이전트가 함께 작업할 때 파일시스템은 협업을 위한 공유 원장으로 기능한다.
Ralph 루프(Ralph Loop) 는 작업 연속성을 유지하기 위한 하네스 패턴이다. Ralph 루프는 훅을 통해 모델의 종료 시도를 가로채고, 깨끗한 컨텍스트 윈도우에 원래 프롬프트를 재주입하여 완료 목표를 향해 계속 작업하도록 강제한다. 각 반복이 새로운 컨텍스트에서 시작하지만 이전 반복의 상태를 파일시스템에서 읽어오기 때문에 이것이 가능하다.
계획과 자기 검증은 방향을 잃지 않도록 한다. 계획은 모델이 목표를 일련의 단계로 분해하는 것으로, 하네스는 좋은 프롬프팅과 파일시스템의 계획 파일 사용 방법 주입을 통해 이를 지원한다. 각 단계 완료 후 에이전트는 작업의 정확성을 자기 검증을 통해 확인한다. 하네스의 훅은 사전 정의된 테스트 스위트를 실행하여 실패 시 오류 메시지와 함께 모델에게 루프백하거나, 모델이 자신의 코드를 독립적으로 자기 평가하도록 프롬프트할 수 있다. 검증은 솔루션을 테스트에 기반하게 하고 자기 개선을 위한 피드백 신호를 만든다.
모델-하네스 훈련 루프: 공진화의 순환
오늘날의 에이전트 제품, 예를 들어 Claude Code나 Codex는 모델과 하네스를 루프 안에 두고 사후 학습(post-training)된다. 이는 하네스 설계자들이 모델이 기본적으로 잘 해야 한다고 생각하는 행동들—파일시스템 작업, bash 실행, 계획, 서브에이전트를 통한 병렬 작업—에서 모델이 개선되도록 돕는다.
이로부터 피드백 루프가 형성된다. 유용한 프리미티브가 발견되고, 하네스에 추가되며, 다음 세대 모델을 훈련할 때 사용된다. 이 사이클이 반복될수록 모델은 자신이 훈련된 하네스 안에서 더 유능해진다.
그런데 이 공진화는 일반화에 흥미로운 부작용을 낳는다. 도구 로직을 변경하면 모델 성능이 저하되는 방식으로 나타난다. Codex-5.3 프롬프팅 가이드에서 파일 편집을 위한 apply_patch 도구 로직에 대해 설명된 것이 좋은 예다. 진정으로 지능적인 모델이라면 패치 방법 전환에 별 어려움이 없어야 하지만, 하네스를 루프에 두고 훈련하면 이러한 과적합이 발생한다.
하지만 이것이 모델을 위한 최선의 하네스가 그 모델이 사후 학습된 하네스라는 의미는 아니다. Terminal Bench 2.0 리더보드가 좋은 예다. Claude Code 안의 Opus 4.6은 다른 하네스 안의 Opus 4.6보다 훨씬 낮은 점수를 기록한다. LangChain은 하네스만 변경하여 Terminal Bench 2.0에서 Top 30 밖에서 Top 5로 순위를 끌어올렸다. 특정 작업에 맞게 하네스를 최적화하는 것에는 아직 짜낼 수 있는 가치가 많다.
실제로 LangChain의 deepagents-cli는 모델(gpt-5.2-codex)을 고정한 채 하네스만 반복 최적화하여 Terminal Bench 2.0에서 52.8%에서 66.5%로 13.7 퍼센트포인트 개선을 달성했다. 이 개선은 세 가지 핵심 영역에 집중했다. 자기 검증 루프를 강조하는 시스템 프롬프트, 에이전트가 환경을 이해하도록 돕는 향상된 도구와 컨텍스트 주입, 그리고 doom loop 같은 문제 패턴을 감지하는 미들웨어 훅이 그것이다.
하네스 엔지니어링의 미래
모델이 더 유능해질수록 오늘날 하네스에 있는 것들 중 일부가 모델 자체로 흡수될 것이다. 모델은 계획, 자기 검증, 장기 일관성을 기본적으로 더 잘 수행하게 되어 예를 들어 컨텍스트 주입이 덜 필요하게 될 것이다. 이것은 하네스가 시간이 지남에 따라 덜 중요해질 것임을 시사한다.
그러나 프롬프트 엔지니어링이 오늘날에도 여전히 가치 있는 것처럼, 하네스 엔지니어링도 좋은 에이전트를 구축하는 데 계속 유용할 가능성이 높다. 하네스는 오늘날 모델의 결함을 패치할 뿐만 아니라, 모델 지능을 중심으로 시스템을 엔지니어링하여 더 효과적으로 만든다. 잘 구성된 환경, 적절한 도구, 지속적 상태, 검증 루프는 기본 지능에 관계없이 어떤 모델이든 더 효율적으로 만든다.
LangChain의 CEO Harrison Chase는 “에이전트가 실패할 때, 그것은 올바른 컨텍스트를 갖지 못했기 때문이고, 성공할 때는 올바른 컨텍스트를 가졌기 때문”이라고 말했다. 컨텍스트 엔지니어링이란 올바른 정보를 올바른 형식으로 올바른 시간에 LLM에게 전달하는 것을 의미한다. 하네스 엔지니어링은 바로 이 컨텍스트 엔지니어링의 확장이다.
현재 LangChain이 deepagents를 통해 탐구하는 열린 문제들은 하네스 엔지니어링의 최전선을 보여준다. 공유 코드베이스에서 병렬로 작업하는 수백 개의 에이전트 오케스트레이션, 자신의 트레이스를 분석하여 하네스 레벨 실패 모드를 식별하고 수정하는 에이전트, 사전 구성 없이 주어진 작업에 맞는 올바른 도구와 컨텍스트를 적시에 동적으로 조합하는 하네스가 그 예다.
결론
모델은 지능을 담고 있고, 하네스는 그 지능을 유용하게 만드는 시스템이다. 에이전트 엔지니어링의 시대에 경쟁 우위는 더 나은 모델을 보유하는 것보다 더 나은 하네스를 구축하는 데서 비롯될 가능성이 높다. 하네스를 구축하고, 더 나은 시스템을 만들며, 더 나은 에이전트를 향해 나아가는 것. 그것이 2026년 에이전트 엔지니어링의 핵심 과제다.
작성일: 2026-03-11