하네스 엔지니어링 — AI 에이전트 성과를 좌우하는 작업 환경 설계

Google Chrome 엔지니어링 리더 Addy Osmani가 제시한 에이전트 하네스(Agent Harness) 엔지니어링 개념은 AI 에이전트의 성과가 모델 자체보다 에이전트가 실행되는 작업 환경, 즉 하네스의 설계 품질에 의해 결정된다고 주장한다. 실제로 동일한 Claude Opus 모델이 기본 환경에서 실행될 때와 최적화된 하네스 내에서 실행될 때 벤치마크 순위가 30위에서 5위로 도약한 사례가 이 주장을 뒷받침한다.

모델이 아니라 구성을 의심하라

하네스 엔지니어링은 에이전트 실패가 모델 문제가 아니라 구성(Configuration) 문제임을 전제로 한다. AI 에이전트의 성능 문제가 발생했을 때 더 강력한 모델로 교체하기 전에, 에이전트가 동작하는 환경 자체를 재검토하는 것이 하네스 엔지니어링의 출발점이다.

에이전트 하네스는 다섯 가지 핵심 구성 요소로 이뤄진다. 시스템 프롬프트(에이전트의 역할과 행동 지침), 툴 스펙(에이전트가 사용할 수 있는 도구의 정의), 메모리 레이어(단기·장기 컨텍스트 저장), 평가 루프(에이전트 출력의 품질 측정), 인간 개입 지점(에스컬레이션 조건과 승인 흐름)이 그것이다.

⤢✕

시스템 프롬프트와 툴 스펙 — 하네스의 앞단 레이어

시스템 프롬프트는 에이전트 하네스에서 가장 큰 영향력을 가진 단일 요소다. 단순한 역할 설명을 넘어 에이전트의 사고 방식, 의사결정 프레임워크, 실패 처리 방법까지 인코딩한다. 효과적인 시스템 프롬프트는 네 가지 요소를 포함한다. 역할과 전문 영역 정의는 에이전트가 무엇을 하는 존재인지, 어떤 도메인 지식을 보유하는지 명시한다. 행동 원칙은 에이전트가 어떻게 추론하고 결정을 내려야 하는지의 프로세스를 기술한다. 경계 조건은 에이전트가 절대 해서는 안 되는 행동(금지 목록)을 명시한다. 출력 형식은 에이전트의 응답이 따라야 할 구조와 형식을 정의한다. 작업 유형에 따라 시스템 프롬프트를 최적화해야 하는데, 코드 생성 에이전트에는 테스트 가능성·오류 처리·코드 품질 기준을, 데이터 분석 에이전트에는 통계적 엄밀성과 불확실성 표현 방식을 명시한다.

툴 스펙 설계는 에이전트가 실세계와 상호작용하는 인터페이스를 정의한다. 툴이 너무 적으면 에이전트가 목표를 달성할 수 없고, 너무 많으면 혼란스러워 잘못된 툴을 선택하는 경향이 있다.

⤢✕

툴 설명(description)은 에이전트가 적절한 툴을 선택하는 데 결정적인 역할을 한다. 툴이 무엇을 하는지뿐만 아니라 언제 사용해야 하는지, 어떤 상황에서는 사용하면 안 되는지까지 기술한다. 유사한 기능을 가진 툴이 여러 개 있을 때 선택 기준도 명시한다.

메모리 레이어 — 컨텍스트 엔지니어링의 핵심

Osmani의 하네스 엔지니어링에서 파일시스템 기반 워크스페이스는 메모리 관리의 핵심 인프라다. 에이전트에게 파일시스템을 제공하면 중간 결과를 컨텍스트 창(Context Window) 외부에 오프로드할 수 있고, 여러 에이전트가 공유 파일을 통해 협업할 수 있으며, Git 통합으로 작업 진행 추적과 롤백이 가능해진다.

메모리 레이어는 세 계층으로 설계한다. **단기 메모리(In-Context)**는 현재 작업과 직접 관련된 정보로, 컨텍스트 창의 한계로 인해 관련성이 높은 정보만 선별해 포함한다 — 정보 선별 로직 자체가 컨텍스트 엔지니어링의 핵심이다. **중기 메모리(External Store)**는 Redis, 벡터 데이터베이스, 구조화된 파일에 저장되는 작업 세션 내 정보로, 에이전트가 이전 단계의 결과를 참조할 때 검색해 컨텍스트에 포함한다. **장기 메모리(Persistent Knowledge)**는 에이전트가 학습한 패턴, 사용자 선호도, 도메인 지식이 저장되는 계층으로 작업 세션을 넘어 지속된다.

평가 루프와 관찰 가능성

에이전트 성능의 지속적 개선은 체계적인 평가 루프 없이는 불가능하다. 평가 루프는 에이전트 출력의 품질을 자동으로 측정하고, 저품질 출력을 감지해 재시도 또는 에스컬레이션을 트리거한다.

⤢✕

에이전트 성능을 정량화하는 지표는 세 가지 차원에서 측정한다. 작업 완료율은 에이전트가 주어진 목표를 얼마나 자주 성공적으로 완료하는가, 컨텍스트 효율은 동일한 품질의 결과를 생성하는 데 소비되는 토큰 수, 재시도율은 에이전트가 첫 시도에 성공하지 못하고 재시도해야 하는 빈도다. Terminal Bench 2.0이나 SWE-Bench 같은 에이전트 벤치마크는 하네스 설계 변경의 효과를 객관적으로 측정하는 데 활용한다. 벤치마크 점수의 변화를 모니터링하면서 시스템 프롬프트 수정, 툴 스펙 변경, 메모리 전략 조정의 효과를 검증한다.

관찰 가능성의 핵심은 에이전트 실행의 모든 단계를 캡처하는 트레이스 시스템이다. 각 툴 호출, 추론 단계, 결정 포인트를 타임스탬프와 함께 기록한다. 실패 케이스 분석 시 트레이스를 역추적해 어느 단계에서 판단이 잘못됐는지 정확히 파악하며, 이 분석 결과가 시스템 프롬프트·툴 스펙·메모리 레이어의 개선으로 이어지는 피드백 루프를 구성한다.

프로덕션 운영: 오류 처리와 비용·안전 가드레일

에이전트가 실패하는 원인은 세 가지로 분류된다. 툴 오류(외부 서비스 장애, 타임아웃), 추론 오류(부적절한 툴 선택, 잘못된 파라미터), 정책 위반(에이전트가 허용되지 않은 행동 시도)이다. 툴 오류는 지수 백오프(Exponential Backoff)와 최대 재시도 횟수 제한으로, 추론 오류는 다른 접근 방식을 지시하는 피드백 프롬프트와 함께 재시도로, 정책 위반은 즉시 인간 개입 루프로 에스컬레이션하는 식으로 각 오류 유형에 맞는 재시도 정책과 에스컬레이션 경로를 설계한다.

프로덕션 에이전트의 비용은 토큰 소비와 직결된다. 에이전트별 일일 토큰 예산을 설정하고, 예산 소진 시 자동으로 실행을 중단하거나 더 경량화된 모델로 전환한다. 복잡한 분석이 필요한 작업에만 대형 모델을 사용하고, 단순한 판단이나 도구 호출에는 소형 모델을 활용하는 계층화된 모델 전략이 비용 최적화의 핵심이다.

안전 가드레일은 에이전트가 설계된 경계를 벗어나지 못하도록 보호한다. 입력 검증(악의적이거나 잘못된 입력 차단), 출력 필터(민감 정보 노출 방지), 액션 제한(허용된 툴과 리소스 범위 강제)의 세 계층으로 구성한다.

에이전트 하네스 엔지니어링은 AI 에이전트 개발의 패러다임을 "어떤 모델을 쓸 것인가"에서 "어떤 환경에서 실행할 것인가"로 전환한다. 시스템 프롬프트, 툴 스펙, 메모리 레이어, 평가 루프, 인간 개입 지점을 체계적으로 설계하면 동일한 모델로도 현저히 높은 성과를 달성할 수 있다.