Banya Agent Harness — 개요
문서 최종 수정: 2026년 6월 23일
개요
이 문서는 Banya Agent Harness를 도입·사용하려는 엔지니어 를 위한 개념 안내서입니다. 내부 구현 규칙은 다루지 않되, 무엇을 보장하고 어떤 설계 가이드를 따르는지를 기술적으로 설명합니다.
1. 정의: Agent = Model + Harness
Agent = Model + Harness
Model — 확률적(stochastic) 구성 요소. 샘플링으로 토큰을 생성하므로 같은 입력에도 출력이 흔들리는 비결정적 요소입니다.
Harness — 모델을 둘러싼 결정론적 실행 셸(deterministic execution shell) . 모델이 아닌 모든 코드·설정·실행 로직이며, 모델 출력을 받아 검사·교정·라우팅합니다.
Banya Agent Harness는 이 셸을 온프레미스 122B 모델 전제 위에서 구현합니다. 이 규모의 모델은 재현 가능한 실패 모드(reproducible failure modes) 를 가지므로 — 매번 같은 자리에서 미끄러지므로 — 하네스의 역할은 그 실패 분포를 결정론적 코드로 흡수 하는 것입니다. 이때 능력을 끌어내는 스캐폴딩(scaffolding)과 출력을 제약하는 가드레일(guardrails)을 둘 다 얇게 구현합니다.
마구가 말의 힘을 줄이지 않고 방향만 구속하듯, 하네스도 모델의 능력은 두고 이탈 경계만 고정합니다.
2. 무엇을 보장하는가
하네스가 제공하는 보장은 모델이 줄 수 없는 비기능적 속성(non-functional properties) 입니다.
결정론(determinism) — 모델 출력은 분포를 따르지만, 하네스의 검사·방어 경로는 입력이 같으면 결과가 같습니다. 검증 계층 자체는 흔들리지 않습니다.
멱등성·재현성(idempotency & reproducibility) — 누가 언제 어느 환경에서 실행하든 동일 절차·동일 판정. 사람·리뷰어·실행 시점에 따른 편차가 제거됩니다.
실패 모드 커버리지(failure-mode coverage) — 모델이 반복하는 오류 유형을 명시적 검사 집합 으로 고정합니다. 사람의 육안 리뷰가 갖는 누락·비일관·확장 한계를 코드로 대체합니다.
관측 가능성(observability) — 조용한 실패(silent failure) 대신 fail-loud . 어디서 어떤 가정이 깨졌는지 원인을 짚는 진단을 냅니다.
게이트화(gating) — 종료 코드(exit code) 같은 기계 판독 가능한 신호를 내보내 CI 파이프라인에 그대로 연결됩니다. 모델 산출물이 머지되기 전에 결정론적 게이트에서 걸립니다.
요점은 명확합니다. 모델은 확률적으로 옳고, 하네스는 결정론적으로 안전합니다. 시스템의 신뢰도는 모델의 정확도가 아니라, 이 결정론적 셸의 커버리지에서 나옵니다.
3. 설계 가이드: Framework vs SDK vs Harness
LLM 위에 무언가를 덧대는 방식은 결국 추상화를 얼마나 두껍게 쌓느냐 의 스펙트럼입니다. Banya Agent Harness가 그 스펙트럼의 어디에 서 있는지를 보면 성격이 드러납니다.
한쪽 끝에는 무거운 오케스트레이션 프레임워크 가 있습니다. 체인·그래프·멀티에이전트를 한 보따리로 묶어 많은 것을 대신 해줍니다. 다만 그 편의에는 추상화 세금(abstraction tax) 이 붙습니다. 비유하자면 만능 공구가 가득한 트럭과 같아서, 못 하나를 박으려 해도 트럭부터 끌고 와야 합니다. 그래서 현장의 불만도 늘 비슷합니다 — 조금이라도 평범하지 않은 일을 하려면 여러 겹의 추상을 헤집고 들어가야 하고, 오류 하나를 추적하려면 프레임워크 내부 스택을 읽어야 한다는 것. 새는 추상(leaky abstraction), 비대한 의존성 표면, 잦은 API 변경, 그리고 그 생태계에의 벤더 락인 이 따라옵니다.
반대쪽 끝에는 최소한의 원시 요소만 주는 경량 에이전트 SDK 가 있습니다. Banya Agent Harness는 그보다도 한 발 더 나아간 자리 — 작업 하나당 의존성 0·빌드 0의 자족적 실행 단위 입니다. 트럭이 아니라 손에 딱 맞는 연장 한 자루 에 가깝습니다. 한 가지 일밖에 못 하지만, 그 한 가지는 꺼내자마자 바로 됩니다.
이 차이를 떠받치는 원칙은 하나입니다.
하네스의 모든 구성 요소는 "모델이 혼자서는 못 한다"는 가정 하나 를 인코딩한다.
그러니 하네스에 무언가가 더해졌다면 그건 장식이 아니라, 관측된 실패 모드 의 결정론적 대응물입니다. 목표는 기능을 늘리는 것이 아니라, 더 덜어낼 수 없는 최소집합(irreducible minimum) 에 도달하는 것입니다.
도입하는 입장에서 체감하는 차이를 한 표로 모으면 이렇습니다.
축
무거운 프레임워크
Banya Agent Harness
첫인상
배워야 쓸 수 있다
받으면 바로 돌아간다
추상화 두께
다층 추상
모델 위 얇은 한 겹
의존성 표면
광범위·전이 의존성
0 (표준 라이브러리만)
결정론
내부 상태로 추론 어려움
입력→출력 결정론 보장
관측성
블랙박스, 깊은 스택트레이스
한눈에 읽히는 단일 책임
버전 안정성
API 변경에 취약
변동원이 없음
결합도
생태계 락인
무결합·이식 가능
범위
무엇이든 다
한 가지를, 확실하게
결국 가르는 변수는 기능의 수 가 아니라 신뢰 표면(trust surface) 입니다. 검증을 맡은 한 겹이 얇고 투명할수록, 그것이 무엇을 보장하는지 끝까지 들여다보고 믿을 수 있습니다. 반대로 두꺼운 보호 계층은, 정작 그 자신이 또 하나의 미덥지 않은 변수가 되어 버립니다.
4. 방법론과 구조
위의 설계 가이드는 추상이 아니라 저장소의 물리적 구조 그 자체 로 강제됩니다. Banya Agent Harness 모음은 다음 규칙으로 조직됩니다.
언어별 디렉터리 — python/ , nodejs/ 처럼 런타임으로 1차 분류합니다.
단위 = 자족적 실행체 — 하나의 하네스는 의존성 0·빌드 0의 단일 파일 이 기본이고, 복잡해지면 디렉터리 하나 로 승격됩니다.
코드 ↔ 동명(同名) 스킬 문서 1:1 — 모든 하네스 코드 옆에는 같은 이름의 얇은 .md 가 짝으로 붙습니다. 문서는 로직을 산문으로 복제하지 않고 진입점만 가리킵니다(thin docs, behavior in code). 디렉터리 하네스는 그 .md 를 디렉터리 안에 두어, 복사·반입 시 문서가 코드와 함께 이동합니다.
python/
fastapi_guard.py ← 코드 (단일 파일 하네스)
fastapi_guard.md ← 동명 스킬 문서 (얇음)
nodejs/
e2e-llm-harness/ ← 디렉터리 하네스
e2e-harness ← 코드
e2e-llm-harness.md ← 동명 문서 (디렉터리 안)
이 구조가 곧 방법론입니다. 코드와 문서 이름이 1:1로 맞고 의존성이 없으므로, 사람이든 LLM 에이전트든 스킬 문서 한 장만 읽고 곧바로 해당 코드를 실행 할 수 있습니다. 새 하네스를 추가하는 비용도 "코드 한 파일 + 같은 이름의 얇은 .md " 한 쌍으로 고정됩니다.
5. 운영 관점에서의 특성
도입하는 입장에서 체감하는 속성:
무설치(zero install) — pip/npm install 이나 빌드 단계가 없습니다. 가리키고(point) 실행합니다. 환경 차이로 인한 설치 실패 변수가 없습니다.
자기 문서화(self-documenting) — 각 하네스는 동봉된 얇은 사용 안내(스킬 문서)와 1:1로 짝지어집니다. 숨은 동작이 없어 호출 표면이 그대로 노출됩니다.
재현 가능(reproducible) — 동일 입력 → 동일 결과. 어제 통과한 것이 오늘 비결정적으로 깨지지 않습니다.
명시적 실패(explicit failure) — 예외/진단에 실패 지점과 원인 힌트를 담아, 디버깅이 추측이 아닌 추적이 되게 합니다.
단일 책임(single responsibility) — 한 하네스는 한 작업만 수행합니다. 직교하는 작업은 별도 하네스를 조합(compose)합니다 — 모놀리식 확장이 아니라 작은 단위의 합성.
이식성(portability) — 외부 결합이 없어, 단위를 그대로 복사·반입하면 다른 환경에서도 동일하게 동작합니다.
이 속성들은 하나의 운영 목표로 수렴합니다 — 감사 가능하고(auditable), 신뢰하고 잊을 수 있는(trust-and-forget) 검증 단위.
6. 요약
Banya Agent Harness는 모델을 더 똑똑하게 만들지 않는다. 모델을 신뢰 가능한 시스템 구성 요소로 만든다.
능력(capability)은 확률적 모델에 위임하고, 그 능력이 반복적으로 이탈하는 실패 모드만 얇고 결정론적인 셸 로 흡수합니다. 신뢰도는 모델 정확도가 아니라 이 셸의 커버리지·투명성에서 나오며, 그 셸을 의도적으로 얇게 유지하는 것 자체가 설계의 핵심입니다.
이 문서는 개념·설계 가이드입니다. 각 하네스의 정확한 동작·요구사항·종료 코드 규약은 해당 하네스에 동봉된 스킬 문서를 참고하세요. 배경 개념은 공개 자료 — Anthropic Building Effective Agents 및 harness 설계 글, METR의 agent scaffolding 논의, ReAct·Reflexion·Voyager 등 스캐폴딩 선례, NeMo/Guardrails AI 류의 guardrail 접근 — 을 함께 보면 맥락이 분명해집니다.