LLM Wiki

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

14 min read

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

모델이 문제가 아니다. 모델을 감싸는 모든 것이 문제다.

에이전트 하네스란?

에이전트 하네스(Agent Harness) = LLM을 감싸는 완전한 소프트웨어 인프라

  • 오케스트레이션 루프, 도구, 메모리, 컨텍스트 관리, 상태 지속성, 에러 처리, 가드레일을 포함
  • Anthropic: “SDK는 Claude Code를 구동하는 에이전트 하네스”
  • OpenAI Codex 팀: “agent”와 “harness” = 모델 외부 인프라를 가리키는 동의어

핵심 구분:

  • 에이전트(Agent) = 사용자가 상호작용하는 목표 지향적, 도구 사용, 자기 수정 동작 (= 결과)
  • 하네스(Harness) = 그 동작을 만드는 기계 장치 (= 수단)

“모델이 아닌 모든 것이 하네스다.” — LangChain Vivek Trivedy

Von Neumann 아날로지 (Beren Millidge, 2023):

컴퓨터 구성 요소에이전트 대응
CPULLM
RAM컨텍스트 윈도우
디스크외부 데이터베이스
디바이스 드라이버도구 통합
운영체제하네스

엔지니어링 3계층

  1. 프롬프트 엔지니어링 — 모델이 받는 지시사항 작성
  2. 컨텍스트 엔지니어링 — 모델이 보는 것과 타이밍 관리
  3. 하네스 엔지니어링 — 1·2를 포함한 전체 인프라: 도구 오케스트레이션, 상태 지속성, 에러 복구, 검증 루프, 안전 집행, 생명주기 관리

프로덕션 하네스의 12가지 구성 요소

1. 오케스트레이션 루프

  • Thought-Action-Observation(TAO) 사이클 = ReAct 루프
  • 동작: 프롬프트 조립 → LLM 호출 → 출력 파싱 → 도구 실행 → 결과 피드백 → 반복
  • Anthropic: “멍청한 루프(dumb loop)” — 모든 지능은 모델 안에, 하네스는 턴만 관리

2. 도구(Tools)

  • 스키마(이름, 설명, 파라미터 타입)로 정의해 LLM 컨텍스트에 주입
  • Claude Code 6대 카테고리: 파일 조작, 검색, 실행, 웹 접근, 코드 인텔리전스, 서브에이전트 스폰
  • OpenAI Agents SDK: 함수 도구, 호스팅 도구(WebSearch·CodeInterpreter·FileSearch), MCP 서버 도구

3. 메모리(Memory)

종류설명
단기 메모리단일 세션 내 대화 이력
장기 메모리세션 간 지속 (CLAUDE.md, MEMORY.md, JSON Store, SQLite/Redis)

Claude Code 3계층:

  1. 경량 인덱스 (~150자/항목, 항상 로드)
  2. 주제별 상세 파일 (온디맨드 로드)
  3. 원시 트랜스크립트 (검색으로만 접근)

원칙: 에이전트는 자신의 메모리를 “힌트”로 취급하고, 행동 전 실제 상태를 검증한다.

4. 컨텍스트 관리

컨텍스트 부패(Context Rot): 핵심 내용이 윈도우 중간에 위치하면 성능 30%+ 저하 (Chroma 연구, Stanford “Lost in the Middle” 동일 결과)

프로덕션 전략:

전략설명
컴팩션(Compaction)한도 근접 시 대화 이력 요약
관찰 마스킹과거 도구 출력 숨기고 호출만 유지 (JetBrains Junie)
JIT 검색가벼운 식별자 유지 후 동적 로드 (grep, glob 활용)
서브에이전트 위임광범위 탐색 후 1,000~2,000 토큰 요약만 반환

목표: 원하는 결과의 가능성을 최대화하는 가장 작은 고신호 토큰 집합

5. 프롬프트 구성

계층 구조: 시스템 프롬프트 → 도구 정의 → 메모리 파일 → 대화 이력 → 현재 사용자 메시지

OpenAI Codex 우선순위 스택 (높은 순):

  1. 서버 제어 시스템 메시지
  2. 도구 정의
  3. 개발자 지시사항
  4. 사용자 지시사항 (AGENTS.md, 32KiB 한도)
  5. 대화 이력

6. 출력 파싱

  • 네이티브 도구 호출: 모델이 tool_calls 구조체 반환 → 텍스트 파싱 불필요
  • 도구 호출이 있으면 실행 후 루프, 없으면 최종 응답
  • 구조화 출력: Pydantic 스키마 제약 (OpenAI·LangChain 지원)

7. 상태 관리

프레임워크방식
LangGraph타입 딕셔너리 + 리듀서, 슈퍼스텝 체크포인트
OpenAI앱 메모리 / SDK 세션 / Conversations API / previous_response_id
Claude Codegit 커밋 = 체크포인트, 진행 파일 = 구조화 스크래치패드

8. 에러 처리

10단계 프로세스에서 단계당 99% 성공률 → 전체 성공률 ~90.4%. 에러는 빠르게 복합된다.

LangGraph 에러 분류:

  • 일시적 → 백오프 재시도
  • LLM 복구 가능 → ToolMessage로 반환해 모델이 조정
  • 사용자 수정 필요 → 인간 입력 대기
  • 예상 외 → 디버깅을 위해 버블업

Stripe 프로덕션 하네스: 재시도 최대 2회 제한

9. 가드레일 및 안전

OpenAI SDK 3단계:

  1. 입력 가드레일 (첫 에이전트 실행 시)
  2. 출력 가드레일 (최종 출력 시)
  3. 도구 가드레일 (모든 도구 호출 시) → “트립와이어(tripwire)” 발동 시 즉시 중단

Claude Code:

  • 모델이 시도할 것을 결정, 도구 시스템이 허용 여부 결정 (아키텍처적 분리)
  • ~40개 도구 권한을 독립적으로 관리
  • 3단계: 프로젝트 로드 시 신뢰 설정 → 도구 호출 전 권한 체크 → 고위험 작업 사용자 확인

10. 검증 루프

방식설명
규칙 기반테스트, 린터, 타입 체커 (결정론적)
시각적Playwright 스크린샷 (UI 작업)
LLM-as-judge별도 서브에이전트가 출력 평가

Boris Cherny(Claude Code 창시자): “모델에게 작업 검증 방법을 주면 품질이 2~3배 향상된다.”

11. 서브에이전트 오케스트레이션

Claude Code 3가지 실행 모델:

  • Fork — 부모 컨텍스트의 바이트 동일 복사본
  • Teammate — 별도 터미널 창, 파일 기반 메일박스 통신
  • Worktree — 에이전트당 독립 git worktree·브랜치

OpenAI Agents SDK:

  • agents-as-tools — 전문 에이전트가 제한된 서브태스크 처리
  • handoffs — 전문 에이전트가 완전한 제어권 인수

12. (생략된 구성 요소)

원문에서 목차 상 12개를 언급하지만 11개 항목만 열거됨. 실제로는 서브에이전트 오케스트레이션까지가 공식 목록.

루프의 동작: 단계별 추적

  1. 프롬프트 조립 — 시스템 프롬프트 + 도구 스키마 + 메모리 파일 + 대화 이력 + 현재 메시지 (중요 컨텍스트는 앞·뒤에 배치)
  2. LLM 추론 — 텍스트, 도구 호출 요청, 또는 둘 다 생성
  3. 출력 분류 — 텍스트만: 루프 종료 / 도구 호출: 실행으로 / 핸드오프: 에이전트 전환 후 재시작
  4. 도구 실행 — 인수 검증 → 권한 확인 → 샌드박스 실행 → 결과 캡처 (읽기 전용: 병렬, 변경: 직렬)
  5. 결과 패키징 — LLM 읽기 가능한 메시지로 포맷, 에러도 결과로 반환
  6. 컨텍스트 업데이트 — 대화 이력에 추가, 한도 근접 시 컴팩션
  7. 루프 — 1번으로 돌아가 반복

종료 조건: 도구 호출 없는 응답 / 최대 턴 초과 / 토큰 예산 소진 / 트립와이어 발동 / 사용자 중단 / 안전 거부

Ralph Loop 패턴 (Anthropic, 장기 실행 작업)

다수 컨텍스트 윈도우에 걸친 작업을 위한 2단계 패턴:

  • Initializer Agent — 환경 설정 (init 스크립트, 진행 파일, 기능 목록, 초기 git 커밋)
  • Coding Agent — 매 세션마다 git 로그·진행 파일로 컨텍스트 복원 → 최우선 미완성 기능 선택 → 작업·커밋·요약 작성

파일시스템이 컨텍스트 윈도우 간 연속성을 제공한다.

주요 프레임워크 구현 비교

프레임워크핵심 추상화특징
Anthropic Claude Agent SDKquery() 함수 + 비동기 이터레이터”멍청한 루프”, Gather-Act-Verify 사이클
OpenAI Agents SDKRunner 클래스 (async·sync·streamed)코드 퍼스트, 네이티브 Python
LangGraph상태 그래프 (llm_call ↔ tool_node)명시적 상태 그래프, 체크포인트·시간여행 디버깅
CrewAIAgent + Task + Crew역할 기반 멀티에이전트, Flows 계층
AutoGenCore + AgentChat + Extensions대화 주도 오케스트레이션, 5가지 패턴

하네스 설계 7가지 핵심 결정

  1. 단일 에이전트 vs. 멀티 에이전트 — 먼저 단일 에이전트를 최대화할 것. 도구 수 ~10개 초과 또는 명확히 분리된 도메인이 있을 때만 분리.

  2. ReAct vs. 계획-실행 분리 — LLMCompiler: 순차 ReAct 대비 3.6배 속도 향상

  3. 컨텍스트 윈도우 관리 전략 — 5가지: 시간 기반 초기화 / 요약 / 관찰 마스킹 / 구조화 노트 / 서브에이전트 위임. ACON 연구: 토큰 26~54% 절감, 정확도 95%+ 유지 (원시 도구 출력 대신 추론 트레이스 우선)

  4. 검증 루프 설계 — 계산 검증 (결정론적) vs. 추론 검증 (LLM-as-judge). guides(사전 조종) vs. sensors(사후 관찰)

  5. 권한·안전 아키텍처 — 허용적(빠르고 위험) vs. 제한적(안전하고 느림). 배포 컨텍스트에 따라 결정.

  6. 도구 범위 전략 — 도구가 많을수록 성능이 나빠지는 경향. Vercel v0: 도구 80% 제거 후 성능 향상. Claude Code: 지연 로딩으로 컨텍스트 95% 절감. 원칙: 현재 단계에 필요한 최소 도구 세트만 노출.

  7. 하네스 두께(Thickness) — 얇은 하네스 + 모델 개선에 베팅(Anthropic) vs. 명시적 제어 그래프(LangGraph). Anthropic은 새 모델이 기능을 내재화할 때마다 Claude Code 하네스에서 계획 단계를 삭제한다.

미래 검증 테스트: 더 강력한 모델로 스케일업해도 하네스 복잡도를 추가하지 않고 성능이 향상된다면 설계가 건전한 것이다.

핵심 인사이트

  • 에이전트가 실패하면 모델이 아니라 하네스를 먼저 살펴봐야 한다.
  • LangChain: 동일 모델, 인프라만 변경 → TerminalBench 2.0에서 30위권 밖에서 5위로 도약
  • 별도 연구: LLM이 인프라 자체를 최적화 → 76.4% pass rate (수작업 시스템 초과)
  • 하네스는 빌딩이 완성되면 제거되는 건축 비계(scaffolding)와 같다. 모델이 강력해질수록 하네스는 얇아진다.

그래프 뷰

백링크