LLM Wiki

Agent Harness

21 min read

Agent Harness

한 줄 정의

Agent Harness는 stateless LLM을 multi-step task를 수행하는 agent로 바꾸기 위해 모델 바깥에서 상태, 도구, 검증, 복구, 안전을 관리하는 실행 인프라다.

핵심 요지

  • 실행 환경의 주권: 좋은 에이전트와 데모형 챗봇의 차이는 모델 자체보다 에이전트의 제어 루프를 통제하고 보호하는 외부 하네스 설계에서 결정된다.
  • 제어 문제 해결: RAG(지식 접근 문제)나 결정론적 워크플로(프로세스 문제)와 달리, 에이전트는 목표와 도구를 쥐고 최적의 경로를 탐색하는 제어 문제를 풀며, 하네스는 이 탐색 루프(Thought -> Action -> Observation -> State Update)를 중재한다.
  • 하네스의 모델 내재화 (Harness Absorption): 빅테크 모델(Anthropic Opus 4.8 등)이 사후 학습 및 테스트 시점 추론(CoT) 레이어를 통해 예외 처리, 자가 교정, 툴 호출 제어 등의 상당 부분을 모델 내부로 흡수(Absorb)하고 있다.
  • 외부 하네스의 역할 재정립: 모델이 똑똑해질수록 복잡한 프롬프트 가드라인이나 파이프라인 코드는 모델에 통합되며, 개발자는 금융 예산 통제(Budget Governor), 물리적 샌드박싱, 인간 최종 승인 게이트(HITL) 등 모델 내부로 우회할 수 없는 ‘물리적 통제선’ 구축에 집중해야 한다.
  • 하네스 엔지니어링의 기원: Terraform의 창시자인 Mitchell Hashimoto가 2026년 초 제창한 개념으로, 에이전트가 실수할 때마다 채팅 창에서 일회성으로 프롬프트를 고쳐주는 대신, 동일한 실수가 다신 발생하지 않도록 모델 바깥의 실행 환경/설정(Harness)을 영구적으로 수정해주는 규율을 의미한다.

상세

1. 에이전트 하네스의 11대 아키텍처 구성 요소 (11 Components)

프로덕션 환경의 에이전트는 다음 11가지의 유기적으로 연결된 모듈을 통해 상태와 제어권을 통제받는다.

  1. 오케스트레이션 루프 (Orchestration Loop): Thought ➡️ Action ➡️ Observation으로 순환하는 ReAct 루프를 구동하고, 루프가 탈선하지 않도록 종료 조건을 모델이 아닌 하네스 엔진 수준에서 하드 가이드한다.
  2. 도구 레이어 (Tool Layer): 도구 등록, 스키마 유효성 검증, 샌드박스 실행 및 결과 포맷팅을 처리한다. 호출 전후에 승인과 감사를 실행할 수 있는 Pre/Post-tool hooks를 장착한다.
  3. 메모리 시스템 (Memory Systems): 컨텍스트 윈도우 내 단기 기억(Short-term), Vector DB나 지식 그래프 기반 장기 기억(Long-term), 성공/실패했던 문제 접근법을 기록하는 에피소드 기억(Episodic)을 계층화하여 서빙한다.
  4. 컨텍스트 관리 (Context Management): 입력 길이에 따른 지능 저하를 막기 위해 대화 압축(Compaction), 오래된 결과 마스킹(Observation Masking), JIT 검색(JIT Retrieval), 서브 에이전트 위임(Sub-agent Delegation) 등의 요약 룰을 작동한다.
  5. 프롬프트 구성 (Prompt Construction): 캐시 효율을 위해 정적 프리픽스(Static Prefix)를 맨 앞에 두고 동적 컨텍스트(Dynamic Context)를 뒤에 두어 조립하며, 충돌 시 우선순위 계층(Priority Hierarchy)을 강제한다.
  6. 출력 파싱 (Output Parsing): 단순 문자열 파싱 대신 정형 API(Tool call) 또는 최종 답변(Final Answer), 타 에이전트 이관(Handoff)의 3가지 분기를 Pydantic과 같은 스키마로 검증하고 에러 피드백을 전달하는 Error-aware retry 루틴을 둔다.
  7. 상태 관리 (State Management): 장기 가동 중 런타임이 붕괴해도 재개할 수 있도록 각 단계 완료 시점마다 직렬화 상태를 저장하는 Durable Checkpoints를 보존한다.
  8. 오류 처리 (Error Handling): 실패율을 차단하기 위해 도구 오용 시 Validation 피드백, API 오류 시 지수 백오프(Exponential Backoff), 통제 불가 시 서킷 브레이커(Circuit Breaker)를 탑재한다.
  9. 가드레일 & 보안 (Guardrails & Safety): 민감 데이터, 시스템 파일, 외부 통신망의 3대 치명 권한이 겹쳐 터지지 않게 분리 통제하며, 파괴적인 액션 직전에는 HITL(Human-In-The-Loop) 게이트를 거치게 설계한다.
  10. 검증 루프 (Verification Loops): 작성된 코드를 테스트 팩(pytest, jest 등) 및 정적 분석기(Ruff, ESLint)로 기계적 검증하여 자가 교정을 시도하는 루프를 중재한다.
  11. 서브 에이전트 조율 (Subagent Orchestration): 대규모 프로젝트 시 특정 역할(기획, 코딩, 리뷰)을 쪼개어 독립된 에이전트 런타임에 이관하고 결과 요약만 공유해 메인 컨텍스트를 보호한다.

2. 에이전트의 5대 실패(Crash) 모드와 하네스 방어선

  • 무한 루프(Infinite loops): 동일 상태에서 무의미한 도구 호출을 반복하는 모드. max_steps 하드 가이드로 해결한다.
  • 도구 오용(Tool misuse): 모델이 헛소리로 도구 인자값을 입력하는 모드. Pydantic이나 JSON Schema를 통한 강제 스키마 검증(Validation Loop)을 두고, 오류 발생 시 모델에 피드백을 전달해 스스로 교정하도록 설계한다.
  • 비용 폭주(Runaway costs): 유료 API의 재시도가 제어되지 않고 소모되는 모드. Exponential backoff 및 retry limit을 지정하고, 임계치가 넘을 시 도구를 정지하는 서킷 브레이커(Circuit Breaker)를 도입한다.
  • 비영속성 실행(Non-durable execution): 런타임 크래시 시 모든 진행 상황이 유실되는 모드. 각 도구 호출 완료 단계마다 상태를 직렬화해 Checkpoint DB에 백업한다.
  • 프롬프트 주입(Prompt injection): 악성 외부 입력을 실행해 시스템을 파괴하는 모드. 도구 허용 목록(Allowlist), 실행 전 입력 검사 필터링, 그리고 파괴적 명령어 실행 시 사람의 직접 승인을 강제하는 human-in-the-loop gate를 둔다.

3. 하네스 엔지니어링의 핵심 지표 및 실무 검증 사례

  • Terminal Bench 2.0 성능 격차: LangChain 연구팀이 모델 가중치를 전혀 손대지 않고, 오케스트레이션 루프, 컨텍스트 매니지먼트, reasoning budget 등 하네스 인프라만 튜닝했더니 벤치마크 점수가 52.8%에서 66.5%로 (+13.7포인트) 상승하여 리더보드 Top 5에 진입했다. 하네스 구성을 최적화하는 메타 하네스(Meta-Harness) 활용 시 **76.4%**까지 상승했다.
  • Vercel SQL 에이전트 도구 축소 사례: 당초 15개가 넘는 세분화된 도구를 가졌으나, 이를 단 1개의 bash 실행 도구로 통폐합했더니 성공률이 80%에서 100%로 상승하고 속도는 3.5배 빨라졌으며 토큰 소모량은 37% 감소했다. 모델에 좁고 자잘한 도구를 쥐여주는 것은 오히려 추론의 성능을 저해한다.
  • 연쇄 실패의 수학 (Step Reliability): 개별 툴 콜의 신뢰도가 **99%**로 매우 높더라도, 10단계 태스크의 성공률은 **90.4%**로 떨어지며, 프로덕션에서 흔한 50단계가 되면 성공률은 **60.5%**까지 급감한다. 이 때문에 단 한 번의 에러로 전체 흐름이 깨지지 않게 실패를 복원하는 하네스의 내충격성(Fault-tolerance)이 필수다.
  • Lost in the Middle (Stanford 연구): Stanford 대학 연구팀에 따르면 모델의 컨텍스트 윈도우 한계에 닿기 훨씬 전부터, 본문 중간에 배치된 지식을 추론하고 인출하는 정확도가 30% 이상 급감한다 (Context Rot 현상). 따라서 Position-aware 컨텍스트 설계와 요약 압축은 필수적이다.
  • Surrounding Engineering의 부피: 2026년 3월 유출된 Claude Code의 소스코드는 무려 1,906개 파일, 513,000줄에 달하는 TypeScript로 이루어져 있었는데, 여기에는 단 한 줄의 모델 가중치도 포함되어 있지 않았다. 에이전트의 실무 경쟁력은 모델 그 자체보다 51만 줄에 달하는 하네스 코드에서 결정됨을 뜻한다.

3. 모델 수준의 하네스 흡수 (Harness Absorption by Models)

  • 추론 모델의 제어권 내재화: Anthropic의 Opus 4.8이나 OpenAI O1/O3 계열과 같이 강화 학습(RL)과 생각의 사슬(CoT) 연산을 사후 학습에 고밀도로 탑재한 모델들은, 도구 호출 시 인자 포맷팅 결함이나 예외 발생 시 외부 코드가 개입하지 않아도 모델 내부 추론 루프에서 스스로 에러를 인지하고 교정하여 재시도한다.
  • 개발 오버헤드 축소: 예전에는 복잡한 LangChain 루프나 커스텀 Pydantic 검증 파이프라인을 구축해 에러를 수습했으나, 이제는 간단한 도구 명세만 쥐어주면 모델 가중치 수준에서 자율 디버깅을 완수한다.
  • 외부 통제 경계의 중요성: 이와 같은 트랜드로 인해 개발자가 짜야 할 외부 하네스는 단순 프롬프트 가드나 JSON 재시도 루프에서 탈피한다. 대신 모델 내부 가중치가 절대 우회하거나 변조할 수 없는 하드웨어 샌드박스, 금융 크레딧 고정(Ceiling), **실제 사용자 인증 게이트(HITL)**처럼 시스템 외부의 물리 보안 경계를 방어하는 형태로 한정되어야 한다.

4. 멀티 에이전트 분할 (Multi-Agent Decomposition) 설계

(이하 기존과 동일)

  • 역할 분할 및 상태 연동: 실라버스 설계, 본문 작성, 퀴즈 설계 등 단계를 쪼개어 각각 독립된 에이전트가 이를 담당하게 하고, 중앙의 상태 스키마(State Object)를 거쳐 데이터를 연속적으로 이행(LangGraph 등 활용)한다.
  • 최적 모델 및 도구 매칭: 무거운 논리 구조를 짤 때는 Reasoning 모델을, 본문 작성에는 저렴하고 신속한 모델을, 최종 문서/슬라이드 렌더링 단계에는 확정적 규칙 코드를 배치하여 효율성을 극대화한다.
  • 안티 슬롭(Anti-slop) 검토기 및 휴먼 인 더 루프: 각 에이전트의 중간 출력물 전환 시점에 AI Slop(기계적인 반복 어구, 상투적 서사)을 걸러내는 자동 검토 필터를 배치하고, 핵심 기획안 수립 직후 사람의 수정과 승인을 거치는 휴먼 승인 게이트(Human Approval Gate)를 하네스 수준에서 제어한다.

5. 지속성 실행 백본 (Durable Execution Backbone)

(이하 기존과 동일) 일주일 단위의 장기 작업을 중단 없이 실행하기 위해, 에이전트 루프는 단순 파이썬 프로세스를 넘어 Temporal과 같은 지속성 실행(Durable Execution) 플랫폼을 백본으로 삼아 구동된다.

  • Workflow와 Activity의 격리: 전체 제어 흐름을 결정론적인 ‘워크플로우(Workflow)‘와 비결정론적인 ‘액티비티(Activity)‘로 이분화한다. 워크플로우 코드는 일체의 외부 API 호출이나 무작위 연산을 배제하고 순수 상태 전이만 처리하여, 시스템 크래시 시 과거 히스토리 저널링(Journaling) 데이터를 바탕으로 리플레이(Replay)해 이전과 100% 동일한 상태로 메모리를 복원한다. 파일 쓰기, 네트워크 통신 등 불확실한 실무는 모두 액티비티로 위임하며, 성공한 액티비티 결과는 캐시에 저장되어 리플레이 시 토큰 낭비나 중복 작업 없이 즉시 복원된다.
  • 지속성 있는 대기 (Durable Sleep): 대기 상태(예: 야간 비기동 또는 수동 승인 대기) 진입 시 클라우드 분산 타이머로 워크플로우를 잠재운다. 서버 리소스를 소모하지 않아 비용이 발생하지 않으며, 서버 재부팅 시에도 정확히 지정된 시간에 기상하여 재개된다.
  • 신규 실행 계속 (Continue-As-New): 장기 가동에 따른 수만 건의 이벤트 로그 누적으로 메모리가 고갈되는 문제를 막기 위해, 주기적으로 중간 진척도를 압축하고 최소한의 상태 스냅샷만 쥔 채 워크플로우를 새로 시작(continue_as_new)한다.
  • 클레임 체크 (Claim-Check) 패턴: LLM 출력 본문이나 대용량 테스트 로그를 그대로 이벤트 저장소에 넣으면 데이터베이스가 붕괴한다. 대형 페이로드는 외부 오브젝트 스토리지에 봉인하고, 워크플로우 내에는 조회용 키값(영수증)만 기록하는 아키텍처를 채택한다.

6. 안전 및 금융 가드레일 (Safety & Financial Guardrails)

에이전트가 통제를 벗어나 무제한 요금을 청구하거나 시스템에 치명적인 파괴 행위를 하는 것을 방지하기 위해, 하네스는 프롬프트가 아닌 코드 레이어에서 강제되는 보안 정책을 적용한다.

  • 비용 가버너 (Budget Governor): 매 사이클 실행 직전 authorize_next 게이트를 통해 요금을 검증한다. 이전의 사이클당 평균 비용 소모를 기준으로 차기 예상 비용을 산정하고, 설정된 예산 한도(Ceiling)를 초과할 가능성이 감지되면 allow를 차단하고 루프를 기동 취소 및 셧다운한다.
  • 무한 루프 탐지기 (Loop Detector): 에이전트가 버그에 막혀 제자리걸음을 하는 현상을 차단한다. 이전 사이클의 코드 수정 내용(action)과 그 시점의 상태(state) 정보의 해시값(지문 시그니처)을 매핑하고, 동일 행위가 임계치(예: 4회)를 넘어 기계적으로 무한 반복되면 즉시 차단기(Trip)를 올린 뒤, 주 에이전트를 대기시키고 리뷰어 에이전트를 긴급 소환하는 구조 요청(Escalation)을 보낸다.
  • 2인 통제 규칙 (The Rule of Two) 기반 보안: 메타(Meta) 보안 엔지니어링 팀의 설계 사상에 입각하여 소프트웨어 보안의 3대 치명 권한을 격리 통제한다:
    1. 검증되지 않은 외부 입력 (Untrusted content)
    2. 기밀 정보 조회 (Private data)
    3. 외부 인터넷망 데이터 송출 (External comms) 위 3대 위험 요소가 한 프로세스에 동시에 겹쳐 폭발하지 않도록 하드웨어/코드 레이어 규제를 적용하고, 기본적으로 아웃바운드 인터넷을 차단(Egress default-deny)하며, 위협적인 행위 수행 시 사람의 승인을 받는 HITL(Human-In-The-Loop) 게이트를 강제한다.

예시

  • coding agent: AGENTS.md를 읽고, 필요한 파일만 찾고, 테스트를 돌리고, 실패 시 다시 수정하는 loop 전체가 harness다.
  • research agent: 검색 결과를 전부 context에 넣지 않고 memory index와 JIT retrieval로 필요한 근거만 불러온다.
  • enterprise agent: pre-tool hook으로 승인 흐름을 넣고 post-tool hook으로 audit log를 남긴다.

충돌

현재 확인된 충돌 없음.

관련 노트

그래프 뷰

백링크