작동 중인 에이전트에서 GPT-5를 Claude로 교체해도 대부분의 경우 동작은 거의 바뀌지 않습니다. 재시도 처리 방식, 컨텍스트 윈도우에 무엇을 넣는지, 또는 언제 멈출지를 바꾸면 에이전트 전체가 다르게 동작합니다. 그 차이가 핵심입니다. 모델은 작동하는 에이전트에서 가장 작고 가장 교체하기 쉬운 부분입니다. 흥미로운 엔지니어링은 모델을 감싸는 모든 것 안에 있습니다.
이제 그 wrapper에는 이름이 생겼습니다. 실무자들은 고정된 스크립트를 실행하는 것이 아니라 시간이 지남에 따라 행동을 취하는 무언가로 텍스트 생성기를 변환하는 레이어를 "harness"라고 부르기로 했습니다. 이 용어는 2026년 초 Twitter와 엔지니어링 블로그에서 빠르게 퍼졌는데, 이는 읽는 글마다 같은 단어가 조금씩 다른 의미로 느슨하게 사용되었다는 뜻이기도 합니다. 이 글은 그 의미를 정확히 짚어줍니다. harness가 무엇인지, 무엇으로 구성되어 있는지, "framework"와 "scaffold"와 어떻게 다른지, 그리고 에이전트 품질의 대부분이 왜 모델이 아닌 harness에 숨어 있는지를 설명합니다.
요약
- agent harness는 LLM을 둘러싼 소프트웨어로, 실행 루프, 도구, 메모리, 컨텍스트, 상태, 오류 처리 및 가드레일을 관리합니다. 모델은 텍스트를 생성하고, harness는 모델이 무엇을 볼지, 무엇을 할 수 있는지, 언제 멈출지, 그리고 무언가 잘못되었을 때 어떻게 할지를 결정합니다.
- 프로덕션 환경에서 모델 호출은 종종 시스템 표면적의 가장 작은 가시적 부분입니다. 잘 구축된 harness의 약한 모델이 엉성한 harness의 강한 모델을 이길 수 있습니다. 특히 장시간 실행되는 도구 집약적 작업에서 그렇습니다.
- harness는 대략 아홉 개에서 열한 개의 반복적인 구성 요소를 가지고 있습니다. 그 대부분은 모델이 직접 접촉하지 않는 것들입니다.
- "Harness"는 "framework"와 같지 않습니다. framework(LangGraph, agents SDK)는 여러분이 그것을 사용해 구축하는 라이브러리입니다. harness는 그 라이브러리가 조립을 도와주는 실행 레이어입니다.
Agent Harness란 무엇인가?
agent harness는 언어 모델을 둘러싼 소프트웨어 인프라로, 실행 루프, 도구 접근, 메모리, 컨텍스트, 상태 지속성, 오류 처리 및 가드레일을 관리합니다. 모델은 텍스트를 생성합니다. harness는 각 턴에서 모델이 무엇을 보는지, 어떤 행동을 취할 수 있는지, 언제 멈출지, 그리고 단계가 실패했을 때 어떻게 할지를 결정합니다.
가장 명확한 표현은 LangChain에서 나왔으며, 이를 하나의 방정식으로 압축합니다: Agent = Model + Harness. 모델은 지능을 제공합니다. 하네스는 그 지능이 실제 세계에서 무언가를 하도록 만드는 것입니다.
"하네스는 모델 자체가 아닌 모든 코드, 구성, 실행 로직입니다."
— LangChain, 에이전트 하네스의 구조
저는 그 경계를 가장 쉽게 느낄 수 있는 방법이 하나의 질문이라고 생각합니다. 에이전트가 잘못된 행동을 했을 때, 모델 자체의 추론이 잘못된 것인지, 아니면 주변 시스템이 모델에게 잘못된 컨텍스트, 잘못된 도구, 또는 복구 방법을 제공하지 않은 것인지입니다. 실제 시스템에서 대부분의 경우 두 번째입니다. 모델은 잘못된 입력에 대해 올바르게 추론했습니다. 하네스가 입력을 제어하는 것입니다.
핵심 요점: 모델은 생성하고, 하네스는 통제합니다. 그 구분이 전체 개념입니다.
에이전트 하네스의 구성 요소는 무엇인가?
모든 프로덕션 하네스는 동일한 반복 구성 요소를 조합합니다. 모델을 턴 바이 턴으로 구동하는 실행 루프, 행동할 수 있게 하는 도구 접근, 턴 간의 메모리, 현재 보는 것에 대한 컨텍스트 관리, 세션 간에 작업이 유지되도록 하는 상태 지속성, 실패한 단계에 대한 오류 처리, 그리고 할 수 있는 것을 제한하는 가드레일입니다. 프로덕션 시스템에는 검증 루프와 서브에이전트 오케스트레이션이 추가됩니다.
실무자들이 실제 시스템을 설명하는 방식에서 도출한 유용한 목록:
- 실행 / 제어 루프: 에이전트를 턴마다 구동하는 것. 모델을 호출하고, 출력을 읽고, 요청된 도구를 실행하고, 결과를 다시 전달하고, 종료 조건까지 반복한다.
- Tool 접근: 모델이 접근할 수 있는 함수, API, 코드 실행 환경, 파일 시스템.
- 메모리: 에이전트가 턴과 세션을 넘어 유지하는 정보.
- 컨텍스트 관리: 매 턴마다 모델의 컨텍스트 창에 채워지는 내용과 오버플로 시 압축되는 내용.
- 상태 지속성 / 체크포인팅: 에이전트의 상태를 저장하여 충돌하거나 일시 중지된 실행을 재개할 수 있도록 함.
- 오류 처리: tool 호출 또는 모델 호출 실패 시 재시도, 폴백, 복구 처리.
- 가드레일: 에이전트가 수행할 수 있는 작업에 대한 제한 사항(허용된 도구, 단계 제한, 출력 검증 등).
- 검증 루프: 에이전트(또는 하네스)가 작업을 완료로 선언하기 전에 자체 작업을 검사하는 것.
- 서브에이전트 오케스트레이션: 더 큰 작업에서 서브에이전트를 생성하고, 위임하고, 결과를 수집하는 것.
이 모든 것이 보편적인 것은 아닙니다. 실행 루프, 도구, 컨텍스트 처리, 오류 처리는 주말 프로토타입에서도 등장합니다. 상태 지속성, 검증, 서브에이전트 오케스트레이션은 프로토타입과 프로덕션 시스템이 갈라지는 지점입니다. 프로토타입은 이를 생략할 수 있지만, 장기 실행 프로덕션 에이전트는 그럴 수 없습니다. Anthropic의 다음 글: 장기 실행 에이전트 는 프로덕션 전용 부분에 대한 안내입니다. 컨텍스트 창이 초기화된 후 에이전트가 진행 파일에서 이해를 재구성하는 방법과 테스트가 루프에 연결되는 방법을 다룹니다.
학문적 연결을 원하는 분들을 위한 최근 에이전트 아키텍처 설문조사 동일한 메커니즘을 더 작은 핵심 구성 요소의 형식적 튜플로 압축합니다. 실무자 목록과 설문의 프레이밍은 동일한 구조에 대한 두 가지 줌 레벨입니다. 설문은 압축하고, 위의 목록은 확장합니다. 9개에서 11개 수를 대부분의 프로덕션 하네스가 공유하는 구성 요소로 취급하세요. 비준된 표준이 아니라, 이 분야는 아직 아무것도 비준하지 않았습니다.
핵심 요점: 에이전트의 동작 부품 대부분은 모델이 아닌 하네스에 존재합니다. 모델은 많은 구성 요소 중 하나일 뿐입니다.
왜 하네스가 모델보다 더 중요한가?
잘 설계된 harness 안의 약한 모델이 잘못 설계된 harness 안의 강한 모델을 자주 능가합니다. 이유는 기계적이며 마법이 아닙니다. 에이전트의 end-to-end 신뢰성은 각 단계 신뢰성의 곱이며, 그 단계들의 대부분(도구 선택, 컨텍스트 조립, 오류 복구)은 모델이 아닌 harness의 역할입니다. 이를 개선하면 어떤 모델이 안에 있든 전체 체인이 더 신뢰할 수 있게 됩니다.
산술적으로 구체화해 보겠습니다. 10단계 작업에서 각 단계가 99% 성공한다고 가정해 봅시다. End-to-end 성공률은 99%가 아닙니다. 0.99의 10제곱, 즉 약 90%입니다. 각 단계를 99.9%로 높이면 end-to-end는 약 99%로 올라갑니다. 단계별 신뢰성은 복리로 쌓이며, 단계별 신뢰성은 압도적으로 harness의 속성입니다. 그래서 오류 처리와 컨텍스트 관리를 최적화하는 것이 어떤 벤치마크에서 0.5점 더 좋은 모델로 교체하는 것보다 더 큰 효과를 냅니다.
같은 방향을 가리키는 프로덕션 신호가 있습니다. MongoDB, Vercel의 사례 연구를 인용하며, Vercel이 에이전트 도구의 대부분을 줄이고 더 작고 깔끔한 harness로 동일한 모델에서 성공률이 급격히 상승하는 것을 목격했다고 보고합니다. 이것을 증거가 아닌 수렴하는 근거로 읽으십시오. 이것은 통제된 실험이 아닌 하나의 프로덕션 사례이지만, 위의 복리 산술과 설문 연구와 같은 방향을 가리킵니다.
플랫폼 엔지니어로서 제가 계속 돌아오는 휴리스틱이 있습니다. 병목은 원시 모델 능력이 아닌 컨텍스트이며, 오늘날의 모델 격차를 메우기 위해 만든 스캐폴딩은 모델이 발전함에 따라 흡수되는 경향이 있습니다. harness의 내구성 있는 부분(루프, 상태, 복구)을 구축하고 그 아래 모델은 자체 일정에 따라 발전하도록 두십시오.
핵심 요점: 에이전트가 실패할 때, 모델보다 harness를 먼저 의심하십시오. 확률이 그 편입니다.
Harness, Scaffold, Framework의 차이점은 무엇인가?
이 세 가지는 혼용되어 사용되지만, 그래서는 안 됩니다. A 프레임워크 LangGraph 또는 agents SDK 같이 빌드에 사용하는 라이브러리 또는 SDK입니다. A harness 모델 주변의 실행 및 거버넌스 레이어로, 프레임워크가 이를 조립하는 데 도움을 줍니다. A scaffold 셋 중 가장 느슨한 개념으로, 때로는 harness의 유사어, 때로는 프로토타입 수준의 버전, 때로는 특별히 prompt 및 도구 설명 레이어를 가리킵니다.
용어는 아직 확립되지 않았으며, 가장 명확한 접근법은 하나를 규정하기보다 용법을 정리하는 것입니다. HuggingFace의 에이전트 용어집 이를 직접적으로 말합니다:
"이 용어들 중 많은 것들은 아직 보편적으로 받아들여진 정의가 없으며, 서로 다른 framework들이 같은 단어를 다르게 사용합니다."
— HuggingFace, 에이전트 용어집
| 용어 | 무엇을 가리키는지 | 관계 |
|---|---|---|
| Framework | 빌드에 사용하는 라이브러리 또는 SDK (LangGraph, 에이전트 SDK) | harness를 조립하는 도구 |
| Harness | 모델 주변의 실행 레이어: 루프, 도구, 컨텍스트, 상태, 가드레일 | 배포하고 실행하는 것 |
| Scaffold | 넓게 사용됨: harness의 유사 동의어, 또는 프로토타입 수준 / 프롬프트 레이어 버전 | harness와 겹침; 덜 정확함 |
| 루프 | harness 내부의 실행 사이클 | 하네스의 구성 요소 |
자신의 시스템에 대해 추론할 때의 실질적인 결론: 누군가 "framework"라고 말할 때, 라이브러리를 의미하는지 아니면 실행 중인 것을 의미하는지 물어보세요. 누군가 "scaffold"라고 말할 때, 전체 하네스를 의미하는지 아니면 prompt-and-tool 레이어만을 의미하는지 물어보세요. 여기서 가치는 모호성 해소이지, 최종 답을 주장하는 것이 아닙니다.
LangGraph는 하네스 패턴을 어떻게 구현하는가?
LangGraph는 harness 패턴의 인기 있는 오픈 소스 Python 구현입니다. 에이전트 실행을 노드와 엣지의 방향 그래프로 모델링하며, 노드 사이에 타입이 지정된 상태가 흐르고 모든 전환이 체크포인트 가능합니다. 위의 추상적인 구성 요소들이 모호하게 느껴진다면, LangGraph는 실제 도구에서 구체적인 형태를 취하는 것을 볼 수 있는 곳입니다.
매핑은 거의 일대일입니다. 노드와 엣지는 실행 루프입니다: 각 노드는 작업을 수행하고, 각 엣지는 제어가 다음에 어디로 가는지 결정합니다. 노드 사이에 전달되는 타입이 지정된 상태 객체는 명시적으로 만들어진 context-and-state 구성 요소입니다. 체크포인팅(LangGraph savers를 통해 상태를 유지합니다 Postgres 기반 구현과 같이)은 state-persistence 구성 요소입니다. 구성 가능한 단계 제한은 오작동하는 에이전트가 영원히 반복하는 것을 방지하는 중지 조건 가드레일입니다. 동일한 구성 요소로, 특정 라이브러리에 의해 명명되고 연결됩니다.
자신의 서버에서 LangGraph 에이전트를 24시간 실행하고 싶다면, 이는 개념적인 질문이 아니라 배포 질문입니다. 참조하세요 Linux VPS 가이드 그 경로를 위해. 여기서 LangGraph는 단지 작업된 예시입니다: "실행 루프", "상태 지속성", "가드레일"이 추상화가 아니라 실제 코드에서 가리킬 수 있는 것들이라는 증거입니다.
자주 묻는 질문
Agent Harness란 무엇인가?
agent harness는 언어 모델을 에이전트로 변환하는 모델 주변의 소프트웨어입니다. 실행 루프, 도구 접근, 메모리, 컨텍스트, 상태 지속성, 오류 처리 및 가드레일을 관리합니다. 모델은 텍스트를 생성하고; harness는 모델이 무엇을 보는지, 무엇을 할 수 있는지, 언제 멈출지, 무언가 실패할 때 무슨 일이 일어나는지를 결정합니다.
에이전트 하네스는 에이전트 프레임워크와 같은 것인가요?
아닙니다. 프레임워크는 LangGraph나 에이전트 SDK처럼 구축에 사용하는 라이브러리 또는 SDK입니다. 하네스는 모델을 둘러싼 실행 및 거버넌스 계층(루프, 툴, 컨텍스트, 상태, 가드레일)으로, 프레임워크가 조립하는 데 도움을 줍니다. 프레임워크를 사용해 하네스를 구축하는 것입니다.
모든 에이전트 하네스는 어떤 구성 요소를 가지고 있나요?
대부분의 하네스는 공통 핵심 구조를 공유합니다: 실행 루프, 툴 접근, 메모리, 컨텍스트 관리, 상태 지속성, 오류 처리, 그리고 가드레일. 프로덕션 하네스는 검증 루프와 서브에이전트 오케스트레이션을 추가합니다. 프로토타입은 프로덕션 전용 부분을 생략할 수 있지만, 루프, 툴, 컨텍스트 처리, 오류 처리는 거의 어디에나 등장합니다.
"LLM은 에이전트 시스템에서 가장 작은 부분이다"는 무슨 의미인가요?
이는 에이전트의 동작과 신뢰성 대부분이 모델이 아닌 하네스에서 비롯된다는 뜻입니다. 종단 간 신뢰성은 모든 단계의 성공률의 곱이며, 대부분의 단계는 하네스 작업입니다. MongoDB는 Vercel의 사례 연구를 인용하며, 동일한 모델에서 하네스 변경만으로 성공률이 크게 향상되었다고 보고합니다. 이는 하네스를 수정하는 것이 모델을 수정하는 것보다 효과적이라는 증거입니다.
에이전트 품질이 존재하는 곳
하네스는 에이전트 품질 대부분이 존재하는 곳이며, 이제 당신은 자신의 시스템에서 문제를 찾아낼 어휘를 갖게 되었습니다. 하네스를 정의하고, 구성 요소를 명명하고, 프레임워크와 스캐폴드와 구별하며, 특정 실패가 모델 문제인지 하네스 문제인지 추론할 수 있습니다.
그래서 다음에 에이전트가 오작동하면, 먼저 하네스 레이어를 감사하세요: 제공하는 컨텍스트, 노출한 툴, 설정한 중단 조건, 실패한 단계에서 회복하는 방식. 그 레이어를 확인한 후에만 더 큰 모델을 고려하세요. 대부분의 경우 그럴 필요가 없을 것입니다.
