Akshay Pachaar가 Anthropic, OpenAI, Perplexity, LangChain이 실제로 구축하고 있는 에이전트 하네스를 심층 분석합니다. 오케스트레이션 루프, 도구, 메모리, 컨텍스트 관리 등 stateless LLM을 capable agent로 변환하는 모든 것을 다룹니다.
원문: The Anatomy of an Agent Harness
핵심 주장
챗봇을 만들어 ReAct 루프에 도구 몇 개를 연결하면 데모에서는 작동한다. 프로덕션을 시도하면 무너진다 — 모델이 3단계 전에 한 일을 잊고, 도구 호출이 조용히 실패하고, 컨텍스트 윈도우가 쓰레기로 채워진다.
문제는 모델이 아니다. 모델을 둘러싼 모든 것이다.
LangChain이 동일 모델(같은 가중치)로 인프라만 변경하여 TerminalBench 2.0에서 30위권 밖에서 5위로 점프한 사례가 증명한다. 별도 연구 프로젝트에서는 LLM이 인프라 자체를 최적화하게 하여 76.4% 통과율로 수작업 시스템을 넘어섰다.
Vivek Trivedy(LangChain)의 정준 공식: “모델이 아니면, 하네스다(If you’re not the model, you’re the harness)”
에이전트 하네스란 무엇인가
2026년 초 공식화된 용어. LLM을 감싸는 완전한 소프트웨어 인프라: 오케스트레이션 루프, 도구, 메모리, 컨텍스트 관리, 상태 지속성, 오류 처리, 가드레일.
Beren Millidge의 비유(2023, “Scaffolded LLMs as Natural Language Computers”): 원시 LLM은 RAM·디스크·I/O 없는 CPU다. 컨텍스트 윈도우 = RAM(빠르지만 제한적), 외부 DB = 디스크(크지만 느림), 도구 통합 = 디바이스 드라이버, 하네스 = 운영체제. “우리는 폰 노이만 아키텍처를 재발명했다”
3가지 엔지니어링 수준
| 수준 | 범위 |
|---|---|
| 프롬프트 엔지니어링 | 모델이 받는 지시사항 제작 |
| 컨텍스트 엔지니어링 | 모델이 무엇을 언제 보는지 관리 |
| 하네스 엔지니어링 | 위 둘 + 전체 애플리케이션 인프라 (도구 오케스트레이션, 상태 지속성, 오류 복구, 검증 루프, 안전 시행, 라이프사이클 관리) |
프로덕션 하네스의 12가지 구성요소
1. 오케스트레이션 루프
심장박동. Thought-Action-Observation(TAO) 사이클(ReAct 루프) 구현. 프롬프트 조립 → LLM 호출 → 출력 파싱 → 도구 실행 → 결과 피드백 → 반복. Anthropic은 런타임을 “dumb loop"로 설명 — 모든 지능은 모델에 있고, 하네스는 턴만 관리.
2. 도구
에이전트의 손. 스키마(이름, 설명, 매개변수 타입)로 정의되어 LLM 컨텍스트에 주입. 도구 계층이 등록, 스키마 검증, 인수 추출, 샌드박스 실행, 결과 캡처, 포맷팅을 처리. Claude Code는 6개 카테고리(파일 작업, 검색, 실행, 웹 접근, 코드 인텔리전스, 서브에이전트 생성) 제공.
3. 메모리
다중 시간 척도로 작동:
- 단기 메모리 : 단일 세션 내 대화 기록
- 장기 메모리 : 세션 간 지속. Anthropic은 CLAUDE.md + 자동 생성 MEMORY.md, LangGraph는 네임스페이스 JSON Stores, OpenAI는 SQLite/Redis 세션 지원
Claude Code의 3계층 구조: 경량 인덱스(항목당 ~150자, 항상 로드) → 상세 토픽 파일(온디맨드) → 원시 트랜스크립트(검색으로만 접근). 핵심 원칙: 에이전트는 자신의 메모리를 “힌트"로 취급하고 행동 전 실제 상태와 대조 검증 한다.
4. 컨텍스트 관리
많은 에이전트가 조용히 실패하는 지점. 핵심 문제는 컨텍스트 부패(context rot) : 중요 콘텐츠가 윈도우 중간에 위치하면 모델 성능이 30%+ 저하(Stanford “Lost in the Middle” 발견).
프로덕션 전략:
- 압축(Compaction) : 한계 접근 시 대화 기록 정리 (아키텍처 결정과 미해결 버그는 보존, 중복 도구 출력은 폐기)
- 관찰 마스킹 : JetBrains Junie가 오래된 도구 출력을 숨기되 도구 호출은 가시적으로 유지
- 적시 검색(JIT) : 경량 식별자 유지 후 동적 로드 (grep, glob, head, tail 사용)
- 서브에이전트 위임 : 각 서브에이전트가 광범위 탐색 후 1,000~2,000 토큰 만 반환
Anthropic의 목표: “원하는 결과의 가능성을 최대화하는 최소한의 고신호 토큰 집합 찾기”
5. 프롬프트 구성
모델이 각 단계에서 실제로 보는 것을 조립. 계층적: 시스템 프롬프트 → 도구 정의 → 메모리 파일 → 대화 기록 → 현재 사용자 메시지. OpenAI Codex는 엄격한 우선순위 스택 사용(서버 제어 시스템 메시지가 최고 우선순위).
6. 출력 파싱
현대 하네스는 네이티브 도구 호출에 의존 — 모델이 자유 텍스트 대신 구조화된 tool_calls 객체 반환. 도구 호출 있으면 실행 후 루프, 없으면 최종 답변.
7. 상태 관리
- LangGraph : 타입 딕셔너리가 그래프 노드를 흐르며 리듀서가 업데이트 병합. 슈퍼스텝 경계에서 체크포인팅 → 중단 후 재개, 타임트래블 디버깅 가능
- Claude Code : git 커밋을 체크포인트로, progress 파일을 구조화된 스크래치패드로 사용
8. 오류 처리
10단계 프로세스에서 단계당 99% 성공률이면 전체 성공률은 ~90.4% . 오류는 빠르게 복합된다.
LangGraph의 4가지 오류 유형: 일시적(백오프 재시도), LLM 복구 가능(오류를 ToolMessage로 반환), 사용자 수정 가능(인간 입력 인터럽트), 예상 외(디버깅용 버블업). Stripe는 프로덕션에서 재시도를 2회로 제한.
9. 가드레일과 안전
OpenAI SDK의 3단계: 입력 가드레일(첫 에이전트에서 실행), 출력 가드레일(최종 출력에서 실행), 도구 가드레일(모든 도구 호출에서 실행). “트립와이어” 메커니즘이 트리거 시 에이전트 즉시 중단.
Anthropic은 권한 시행을 모델 추론에서 아키텍처적으로 분리 . 모델은 시도할 것을 결정하고, 도구 시스템은 허용 여부를 결정. Claude Code는 ~40개 개별 도구 기능을 독립적으로 게이팅.
10. 검증 루프
장난감 데모와 프로덕션 에이전트를 구분하는 것. Anthropic의 3가지 접근: 규칙 기반 피드백(테스트, 린터, 타입 체커), 시각적 피드백(Playwright 스크린샷), LLM-as-judge(별도 서브에이전트가 출력 평가).
Claude Code 창시자 Boris Cherny의 발견: 모델에게 작업을 검증할 방법을 주면 품질이 2~3배 향상 된다.
11. 서브에이전트 오케스트레이션
Claude Code의 3가지 실행 모델:
- Fork : 부모 컨텍스트의 바이트 동일 복사본
- Teammate : 별도 터미널 페인, 파일 기반 메일박스 통신
- Worktree : 자체 git worktree, 에이전트별 격리 브랜치
OpenAI SDK: agents-as-tools(제한된 하위 작업) + handoffs(전체 제어 이전). LangGraph: 중첩 상태 그래프로 구현.
12. (루프의 실제 작동)
Step 1: 프롬프트 조립 → Step 2: LLM 추론 → Step 3: 출력 분류 → Step 4: 도구 실행(읽기 전용은 병렬, 변경은 직렬) → Step 5: 결과 패키징 → Step 6: 컨텍스트 업데이트(한계 시 압축 트리거) → Step 7: 루프
종료 조건: 도구 호출 없는 응답, 최대 턴 제한 초과, 토큰 예산 소진, 가드레일 트립와이어, 사용자 인터럽트, 안전 거부.
장기 실행 작업: Ralph Loop 패턴
여러 컨텍스트 윈도우에 걸치는 작업을 위해 Anthropic이 개발한 2단계 패턴:
- Initializer Agent : 환경 설정 (init 스크립트, progress 파일, 기능 목록, 초기 git 커밋)
- Coding Agent : 이후 매 세션에서 git 로그와 progress 파일을 읽어 자기 위치 파악 → 최우선 미완료 기능 선택 → 작업 → 커밋 → 정리 작성
파일시스템이 컨텍스트 윈도우 간 연속성을 제공 한다.
하네스를 정의하는 7가지 설계 결정
1. 단일 에이전트 vs 다중 에이전트
Anthropic과 OpenAI 모두: 단일 에이전트를 먼저 최대화 . 다중 에이전트는 추가 LLM 호출(라우팅)과 핸드오프 시 컨텍스트 손실의 오버헤드. 도구 과부하가 ~10개 겹치는 도구를 초과하거나 명확히 분리된 작업 도메인이 있을 때만 분할.
2. ReAct vs Plan-and-Execute
ReAct: 매 단계에서 추론과 행동을 교차(유연하지만 단계당 비용 높음). Plan-and-Execute: 계획과 실행 분리. LLMCompiler는 순차 ReAct 대비 3.6배 속도 향상 보고.
3. 컨텍스트 윈도우 관리 전략
5가지 프로덕션 접근: 시간 기반 클리어링, 대화 , 관찰 마스킹, 구조화된 노트 작성, 서브에이전트 위임. ACON 연구: 추론 트레이스 우선으로 95%+ 정확도 유지하며 26~54% 토큰 감소 .
4. 검증 루프 설계
계산적 검증(테스트, 린터) = 결정론적 진실. 추론적 검증(LLM-as-judge) = 의미적 이슈 포착하지만 지연 추가. Martin Fowler의 Thoughtworks 팀: guides(피드포워드, 행동 전 조향) vs sensors(피드백, 행동 후 관찰).
5. 권한 및 안전 아키텍처
관대(빠르지만 위험) vs 제한적(안전하지만 느림). 배포 맥락에 따라 결정.
6. 도구 범위 전략
도구가 많으면 성능이 나빠지는 경우가 많다. Vercel은 v0에서 80% 도구를 제거하고 더 나은 결과 를 얻었다. Claude Code는 지연 로딩으로 95% 컨텍스트 감소. 원칙: 현재 단계에 필요한 최소 도구 세트만 노출.
7. 하네스 두께
하네스에 얼마나 많은 로직을 넣을 것인가 vs 모델에 맡길 것인가. Anthropic은 얇은 하네스 + 모델 개선에 베팅. 그래프 기반 프레임워크는 명시적 제어에 베팅. Anthropic은 새 모델 버전이 해당 능력을 내재화하면 정기적으로 Claude Code 하네스에서 계획 단계를 삭제 한다.
스캐폴딩 메타포
건축 비계(scaffolding)는 작업자가 닿지 못하는 구조물을 지을 수 있게 하는 임시 인프라다. 건설을 하지는 않지만, 없으면 상층에 도달할 수 없다. 핵심: 건물이 완성되면 비계는 제거된다.
모델이 개선되면 하네스 복잡성은 감소해야 한다. Manus는 6개월 동안 5번 재구축하며 매번 복잡성을 제거했다. 복잡한 도구 정의 → 일반 셸 실행, “관리 에이전트” → 단순 구조화된 핸드오프.
미래 대비 테스트 : 더 강력한 모델에서 하네스 복잡성 추가 없이 성능이 확장되면, 설계가 건전한 것이다.
결론
동일 모델을 사용하는 두 제품이 하네스 설계만으로 완전히 다른 성능을 보일 수 있다. TerminalBench 증거: 하네스만 변경하여 에이전트가 20+ 랭킹 이동 .
하네스는 해결된 문제도, 상품화된 계층도 아니다. 어려운 엔지니어링이 사는 곳이다: 컨텍스트를 희소 자원으로 관리하고, 실패가 복합되기 전에 잡는 검증 루프를 설계하고, 환각 없이 연속성을 제공하는 메모리 시스템을 구축하고, 얼마나 많은 비계를 세울 것인지 vs 모델에 맡길 것인지에 대한 아키텍처적 베팅을 하는 것.
“다음에 에이전트가 실패하면, 모델을 탓하지 마라. 하네스를 봐라.”