에이전트 하네스를 분리해 모델·도구·환경을 교체하는 설계

프롬프트만으로는 실행 품질을 고칠 수 없다

TrueFoundry가 LLM 에이전트용 오픈소스 하네스 TrueForge를 공개했고, 이 소식은 국내 기술 커뮤니티 큐레이션에도 올랐다. 여기서 주목할 부분은 특정 모델이나 프롬프트 기법보다 모델·도구·실행 환경을 분리해 교체할 수 있는 하네스 계층이다.

도구가 충분하지 않거나 실행 환경이 불안정하다면 프롬프트 문구를 다듬는 것만으로 결과가 좋아지지 않는다. 더구나 성능 변화가 모델, 도구, 환경 중 어디에서 비롯됐는지 구분하지 못하면 개선 결과를 다음 실험에 축적할 수 없다.

모델 릴리스가 3주 주기로 이어지는 상황에서는 모델과 구현이 직접 결합된 구조가 매 릴리스마다 재작업으로 이어진다. 동일한 프롬프트라도 실행 환경이 다르면 결과가 달라지므로, 환경을 고정하지 않은 비교 역시 의미를 갖기 어렵다. 도구 호출 실패와 모델 판단 오류를 하나의 로그로 섞어 보는 방식도 원인 분류를 막는다.

하네스가 분리해야 할 경계

하네스는 호출과 실행을 묶는 중간 계층으로서, 모델·도구·환경의 결합 지점을 통제한다.

모델 호출, 스트리밍, 도구 호출, 토큰 계측은 공통 인터페이스로 정의하고 벤더별 구현은 어댑터 뒤에 둔다. 벤더 고유 파라미터가 상위 계층으로 새어 나오면, 모델 교체는 다시 호출부 전반을 수정하는 작업이 된다.

도구는 이름, 인자 스키마, 반환 형식, 실패 표현을 동일한 규격으로 등록해야 한다. 도구마다 오류를 표현하는 방식이 다르면 실패 계층을 분류할 수 없고, 조합별 비교도 어려워진다.

실행 환경의 제약은 프롬프트가 아니라 하네스가 강제해야 한다. 파일 접근, 네트워크, 프로세스 실행의 허용 범위가 샌드박스 경계다. 프롬프트의 지시는 규칙이 아니라 요청일 뿐이다.

관측 기록도 같은 원칙을 따른다. 요청, 도구 호출, 결과, 판단 근거, 소요 시간을 하나의 스키마로 남겨야 조합 사이의 비교가 가능하다. 여기에 모델 버전, 도구 세트 버전, 샌드박스 버전을 하나의 조합 식별자로 묶어 결과와 함께 기록한다.

실패는 모델 판단 오류, 도구 오류, 환경 오류, 입력 오류로 구분한다. 이 분류는 사후 분석이 아니라 로그를 남기는 단계에서 강제해야 한다. 나중에 나누려 하면 필요한 정보가 이미 유실돼 있을 수 있다. 입력, 도구 응답, 환경 상태를 저장하는 재현 스냅샷도 함께 필요하다. 외부 도구의 응답이 달라지면 같은 실행을 다시 돌려도 재현은 성립하지 않는다.

⤢✕

분리 구조를 도입하는 순서

먼저 애플리케이션 코드에 직접 박혀 있는 모델 문자열, 벤더 SDK 호출, 도구 구현을 찾는다. 결합 지점의 수가 교체 비용이므로 이 지점을 먼저 계량해야 한다.

그다음 모델·도구·환경 가운데 실제로 자주 바뀌는 축부터 분리한다. 세 축을 한꺼번에 분리하기보다 릴리스 주기가 짧은 축을 우선 대상으로 삼는다.

도구 쪽에서는 인자 스키마와 실패 표현을 먼저 확정한 뒤 기존 도구를 그 규격으로 감싼다. 규격을 뒤늦게 변경하면 이미 편입한 도구 전체를 다시 손봐야 한다.

평가 조합은 변경 축이 하나만 남도록 배치한다. 후보가 늘어날수록 조합 수가 급증하므로, 축별 후보는 소수로 제한한다. 조합별로는 성공률, 도구 실패율, 평균 단계 수, 소요 시간, 원가를 함께 본다. 성공률이 같아도 단계 수가 늘면 원가는 오른다.

오픈소스 하네스를 이용한다면 내부 개선을 상류에 반영하는 절차도 필요하다. 포크만 쌓이면 업스트림 변경을 따라가기 어렵다. 도구 규격과 샌드박스 정책의 변경은 승인 대상으로 두고, 조합별 성능과 실패 계층 분포를 정기 보고 항목으로 편성한다.

분리 구조와 결합 구현의 선택

구분	하네스 분리 구조	모델 결합 구현
교체 유연성	높음	낮음
초기 설계 부담	큼	작음
원인 규명력	높음	낮음
고유 기능 활용	제한	최대
재현 가능성	확보	어려움
릴리스 대응	빠름	느림

하네스 분리 구조에서는 모델 교체가 어댑터 하나의 문제로 좁혀진다. 3주 주기의 릴리스를 따라가면서도 도구와 환경을 따로 개선하고, 그 효과를 각각 측정할 수 있다. 실패 원인을 계층별로 기록할 수 있다는 점도 개선의 누적에 유리하다.

대신 공통 인터페이스가 벤더 고유 기능을 모두 흡수하지 못할 수 있고, 추상화 계층 자체가 유지보수 대상이 된다. 초기 구현 규모도 결합 방식보다 커진다.

모델 결합 구현은 벤더가 제공하는 기능을 그대로 사용할 수 있어 품질 상한이 높고, 문서와 예제를 바로 적용할 수 있다. 초기 구현도 빠르다. 그러나 모델이 바뀔 때마다 호출부 전체가 영향을 받고, 성능 변화의 원인이 모델인지 도구인지 구분하기 어려워 개선이 시행착오로 흐를 수 있다. 모델 릴리스 주기가 짧아진 조건에서는 초기 부담을 감수하고 분리하는 편이 총비용에서 유리하다.

도구 통합에서도 표준 규격은 새 도구를 규격에 맞추는 즉시 편입할 수 있고, 통일된 실패 표현을 바탕으로 원인 분류와 조합 테스트를 수행할 수 있다. 반면 특수한 도구는 규격에 억지로 맞추는 과정에서 기능이 깎일 수 있으며, 규격 변경은 모든 도구의 수정으로 이어진다.

개별 어댑터 방식은 도구의 특성을 최대한 살릴 수 있지만, 도구마다 실패 표현이 달라지고 새 도구 추가가 매번 별도 작업이 된다. 다수의 도구는 표준 규격으로 처리하고 특수 도구만 예외 어댑터로 두며 예외 목록을 관리하는 구성이 확장 속도와 표현력 사이의 절충점이 된다.

평가도 목적에 따라 나뉜다. 하네스 단위 평가는 한 축만 바꾸므로 성능 변화의 원인을 특정하고, 어느 계층의 개선인지 기록하며, 회귀가 생겼을 때 되돌릴 대상을 명확히 할 수 있다. 다만 조합 수는 축의 곱으로 늘어나고, 축 간 상호작용으로 생기는 효과를 놓칠 수 있으며, 평가 설계 자체에도 시간이 든다.

종합 성능 평가는 실제 사용 조건에 가까운 결과를 적은 평가 횟수로 얻고 축 간 상호작용도 반영한다. 하지만 결과가 바뀐 이유를 알 수 없어 다음 개선 방향과 회귀 시 복구 대상을 정하기 어렵다. 전체 수준은 종합 평가로 확인하되, 유의미한 변화가 관측된 지점만 축별로 분해하는 이단계 구성이 비용과 원인 규명력을 함께 확보한다.

아키텍처·통합·품질 측정 관점

모델·도구·환경을 나누는 방식은 관심사 분리와 의존성 역전 원칙을 에이전트 실행 계층에 적용한 것이다. 공통 인터페이스와 어댑터의 배치는 이식성을 위한 계층화 설계에 해당한다.

도구 등록 규격을 통일하는 일은 시스템 통합에서 연계 표준과 인터페이스 명세를 관리하는 문제와 닮아 있다. 샌드박스 경계를 강제하는 위치는 통합 지점에 보안 통제를 배치하는 방식이다.

조합 식별자와 실패 계층 분류는 결함 원인 분석과 측정 기준선을 제공한다. 입력·도구 응답·환경 상태를 남기는 재현 스냅샷은 결함 재현성 확보 요건을 실행 구조에 포함하는 일이다.

하네스 계층이 향하는 방향

2026년에는 하네스 계층이 에이전트 스택의 독립 구성요소로 인식되고, 오픈소스 구현 사이의 규격 수렴이 논의되는 방향이다. 모델 릴리스 주기가 짧아질수록 하네스 분리 여부는 릴리스 대응 속도를 좌우하는 요인이 된다.

실패 원인 계층 분류는 에이전트 운영 로그의 표준 필드로 편입되는 방향이며, 도구 등록 규격이 사실상 표준으로 수렴하면 도구 생태계도 하네스 사이에서 이식 가능해지는 흐름이다.

프롬프트 조정은 여전히 필요하지만, 도구와 실행 환경이 받쳐주지 못하면 품질 개선에는 한계가 있다. 모델·도구·환경을 교체 가능한 축으로 나누고, 실패를 계층으로 분류하며, 조합 식별자와 함께 결과를 남기는 구성이 출발점이다. 평가에서는 한 번에 여러 축을 바꾸지 않아야 분리 구조가 제공하는 원인 규명력을 실제 운영에서 회수할 수 있다.