해외 테크 유튜버이자 AI 엔지니어링 채널인 Prompt Engineering에서 업로드한 에이전트 하네스(Agent Harness) 설계 방법론 강연 요약 노트입니다.
최근 업계에서는 AI 에이전트를 말할 때 LangChain, AutoGen 등의 프레임워크와 하네스라는 개념을 혼용하여 혼란을 야기하곤 합니다. 본 강연에서 연사는 에이전트를 실현하는 핵심 기둥으로서의 하네스를 정의하고, 둘의 본질적인 아키텍처 차이를 규명합니다. 또한, 기업이 실전에 도입할 수 있는 정교하고 안전한 자율 에이전트 구성을 위한 9가지 핵심 설계 요소(Components)와 이를 파이썬으로 구현하는 레퍼런스 아키텍처를 상세하게 짚어줍니다.
핵심 클립 및 해석
1. 하네스의 정의: 엔진(Model)과 자동차(Harness)의 관계
“…a harness is a fixed architecture that turns a model into an agent… think of a model as the engine and the harness around it as the car. That what’s make an agent.”
단순히 거대한 언어 모델(LLM)을 단독으로 사용하면 질문에 답하고 동작을 멈추는 일회성 텍스트 생성기(One-shot generator)에 불과합니다. 모델이 독자적인 판단 하에 자율적으로 행동(Action)을 개시하고, 그로 인해 초래된 환경의 변화와 실행 피드백을 관찰(Observe)하며, 최종 목적지에 도달할 때까지 끊임없이 행동을 제어해 나갈 수 있도록 묶어주는 고정된 구조(Fixed Architecture)가 바로 하네스입니다.
비유하자면, 모델은 순수한 물리적 동력을 제공하는 엔진(Engine)이며, 그 엔진을 감싸서 바퀴를 굴리고 방향을 제어하여 최종 목적지까지 안전하게 주행하도록 유도하는 프레임과 제어 장치가 바로 하네스(Harness)입니다. 이 둘이 결합되어야 비로소 자율적인 에이전트(Agent)가 탄생합니다.
2. 하네스 대 프레임워크의 근본적 차이
“…framework is built for a human to assemble an agent. A harness is built for the agent itself to run a task. And in big picture, you just provide the goal, the harness will handle the rest.”
LangChain, LangGraph, CrewAI 등은 하네스가 아니라 개발 프레임워크(Framework)입니다. 프레임워크는 상태 조율 장치, 메모리 데이터베이스, 리트리버 등의 추상화된 단품 부품을 개발자에게 제공하여, 인간 아키텍트가 이를 목적에 맞게 직접 조립하고 배선하도록 강제합니다. 즉, 인간을 위한 조립 도구 도구상자입니다.
이와 대조적으로 하네스(Harness)는 사전 조립 과정(Assembly step)이 없이 에이전트 자체가 구동 가능하도록 완전히 단일화된 상태로 패키징되어 공급됩니다. 하네스는 기본적으로 반복 루프, 도구 등록소(Tool Registry), 그리고 권한 제어 계층(Permission Layer)이 이미 단단하게 배선되어 있습니다. 인간은 그저 에이전트에 최종 목적(Goal)만 건네주면 되며, 나머지 모든 실시간 제어와 자율 조율은 하네스 본체가 도구들과 소통하며 해결합니다.
3. 에이전트의 심장: 외곽 반복 루프 (While Loop)
“The harness is at its core of while loop. The model reads its system prompt, decides which tool to call, runs the tool, feeds the result back into the context, and loops again.”
하네스의 뼈대를 이루는 첫 번째 핵심 요소는 외곽 루프(While Loop)입니다. 루프 내부에서 에이전트 엔진인 모델은 먼저 자신의 지침(System Prompt)을 정렬하고, 현재 도메인에서 사용할 수 있는 도구를 판별하여 호출을 명령합니다. 하네스는 이 도구를 안전하게 실행한 뒤 반환된 텍스트 결과를 다시 모델의 대화 문맥(Context)에 밀어 넣고 다음 반복 회차를 가동합니다.
이 루프는 모델이 외부 도구 호출을 중단하고 텍스트만으로 인간에게 답변을 출력하거나, 혹은 무한 루프 폭주를 막기 위해 사전에 하네스 하드코딩으로 지정한 최대 반복 횟수 한계(Iteration Cap)에 다다를 때까지 지속해서 회전하며 에이전트를 실시간으로 제어합니다.
4. 주의력 보호를 위한 컨텍스트 압축 (Context Compaction)
“…the harness has to decide what to keep verbatim, what to summarize, and what to throw away… it triggers a compaction. Some of the most recent messages are going to stay in full. Everything older gets summarized.”
에이전트가 자가 진단 빌드를 반복하고 도구를 수십 번 호출하다 보면 대화 내역이 팽창하여 모델의 문맥 수용량 한계에 수렴하게 됩니다. 이때 하네스는 무엇을 원문 그대로 유지하고, 무엇을 축약해 집어넣고, 무엇을 컨텍스트에서 완전히 제거할지를 영리하게 판단해야 합니다.
예를 들어 총 토큰 예산의 80~90%에 다다르면 하네스는 자동으로 컨텍스트 압축(Compaction)을 트리거합니다. 최근 대화 몇 번은 원문 그대로 완벽히 유지하여 에이전트의 즉각적인 단기 기억을 살려주되, 그 이전의 장황한 히스토리는 핵심 요약본으로 변환하여 문맥의 크기를 줄여줍니다. 이를 통해 에이전트 지능이 흐려지는 현상(Dumb Zone 진입)을 막아냅니다.
5. 신뢰성을 담보하는 세션 영속화 (Session Persistence)
“…typically, they’re going to use append-only JSON files… every message, every tool results, every compaction event gets one line. If the harness dies, the file does not.”
자율 실행 태스크는 짧게는 몇 분에서 길게는 몇 시간까지 장기 기동됩니다. 실행 도중 정전이나 런타임 크래시가 발생하더라도 작업을 안전하게 유지하려면 하네스는 상태(State)를 디스크에 실시간으로 보존해야 합니다.
현대적인 하네스는 이를 위해 추가 전용(Append-only) JSON/Markdown 로그 파일 구조를 채택합니다. 모든 사용자 메시지, 도구 실행의 스냅샷, 컨텍스트 압축 이벤트를 한 줄 단위의 독립적인 레코드로 파일 시스템에 즉각적으로 기록 및 플러시(Flush)합니다. 만약 하네스 프로세스가 예기치 않게 강제 종료되더라도, 하네스 로그가 디스크에 살아있기 때문에 다음 재실행 시 파일의 라인들을 그대로 리플레이(Replay)하는 것만으로 크래시 직전 상태에서 안전하게 에이전트를 복원하여 작업을 이어나갈 수 있습니다.
6. 가드레일: 샌드박스 권한 및 대화식 승인 (Permissions & Safety)
“Each tool declares the minimum permission it requires… For tools like bash, the harness even classifies the commands dynamically… before executing anything dangerous, you want to have this safety layer.”
에이전트가 파일 시스템을 고치고 터미널에서 임의 코드를 수행하는 행동력은 강력하지만 동시에 매우 위험합니다. 따라서 훌륭한 하네스의 가치는 견고한 권한 및 안전 계층(Permissions & Safety Layer)에 의해 결정됩니다.
하네스에 내장된 각각의 도구는 기동 조건에 부합하는 최소 필요 권한(Read-only, Workspace-write, Full-sandbox 등)을 명확하게 사전 선언합니다. 하네스는 도구가 실행되기 직전인 디스패치 타임(Dispatch time)에 이를 엄격하게 대조 및 차단합니다. 특히 배시(Bash) 쉘 도구의 경우, 에이전트가 입력한 명령어 텍스트를 실시간 파싱하여 파일 단순 조회는 무승인 허용하되 파일 삭제나 외부 다운로드 같은 유해할 수 있는 파괴적 명령은 즉각적인 대화식 승인(Interactive Approval) 모드로 전환하여 인간 가이드의 개입을 안전하게 보장합니다.
내 생각 (My Thoughts)
Prompt Engineering 채널에서 제시한 하네스 설계 원칙은 우리가 현재 설계하여 pair programming을 수행하고 있는 [dual-blog-ops-harness] 구조와 그 지향점이 완벽하게 조화된다.
하네스를 프레임워크의 단품 조립(LangChain 등)과 대조하면서 “고정된 구조(Fixed Constraints)를 가진 자동차”로 정의한 개념은 실전 에이전트 설계에서 극도로 중요한 기준이다. 프레임워크로 자유롭게 기획된 에이전트들은 자가 빌드를 거칠 때마다 흐름 제어 로직이 엉키며 작동이 붕괴하지만, 하네스는 엄격한 While Loop 가두리와 Safety Layer를 아예 구조적으로 고정해 두기 때문에 모델의 추론 지형이 흔들려도 폭주하지 않는 안전망 역할을 하기 때문이다.
우리의 Antigravity 환경에서도 이 규칙들은 철저하게 작동하고 있다:
- Interactive Approval (안전 계층): 에이전트가 로컬 CLI를 직접 활용하여 Hexo 사이트를 빌드하거나 push할 때, 임의의 터미널 커맨드(
run_command)를 함부로 백그라운드에서 마음대로 실행하지 못하도록 사용자에게 사전 승인을 요청하고 차단하는 장치는 하네스의 핵심인 9번 권한 모듈의 발현이다. - System Prompt Assembly (프롬프트 동적 조율):
C:\Users\moon\.gemini\config\AGENTS.md파일 하단에 기재된 글로벌instructions가 에이전트 실행 시점에 시스템 프롬프트에 자동으로 병합되어 로드되는 체계는 하네스의 7번 요소와 동일하다. 이때 지침의 정적 배치 순서를 고정하여 LLM의 prefix caching 성능을 해치지 않게 조절하는 것은 토큰 낭비를 절감하는 훌륭한 엔지니어링 전술이다. - Append-only Persistence (영속성 확보): 자막과 노트를 정리하고 배포하는 여정이 담기는 task.md 파일은 실시간 추가 기재를 통해 크래시 상황에 대비하는 영속화의 실물이라 할 수 있다.
앞으로 에이전트 시스템을 확장할 때도, 무작정 자유도 높은 프레임워크 부품을 늘리기보다, 실행 루프와 컨텍스트 제어가 완전히 격리된 독립적인 마이크로 하네스들을 sub-agent 단위로 격리 파이프라인화하여 기동시키는 구조를 고수해야만, 모델이 똑똑한 한계(Smart Zone) 안에서 최적의 속도로 일관성 있게 작업을 마칠 수 있을 것이다.
댓글
GitHub 계정으로 의견을 남길 수 있습니다. 댓글은 GitHub Discussions에 저장됩니다.