콘텐츠로 이동

P1-14.5 하네스(harness)와 평가 실행 환경

Section ID: P1-14.5 Version: v2026.07.20

P1-14.4에서는 MCP(Model Context Protocol)를 AI 앱과 외부 도구, 데이터가 연결되는 방식을 표준화하는 프로토콜(protocol)로 봤습니다. 이제 질문은 한 단계 더 실무적으로 바뀝니다.

모델을 호출할 수 있다. 도구도 연결할 수 있다. 에이전트가 여러 단계를 이어 갈 수도 있다.

그렇다면 이 실행이 제대로 되었는지는 어떻게 확인할 것인가?

하네스(harness)는 이 질문에서 출발합니다. 이 말은 원래 장비, 마구, 몸이나 물체를 붙잡아 고정하는 장치, 힘을 일의 방향으로 쓰게 하는 장치를 떠올리게 합니다. 소프트웨어에서는 테스트 하네스(test harness)처럼 테스트 대상(system under test)을 일정한 조건에서 실행하고 확인하게 만드는 용례로 이어졌습니다.

AI 서비스 문맥에서는 이 직관을 모델 호출, 도구 호출, 상태 변화, 로그, 평가 기준을 감싸는 실행 환경으로 확장해서 이해할 수 있습니다.

하네스(harness)는 모델과 도구를 실제 작업 흐름 안에서 실행하고, 그 과정을 기록하고, 결과를 검증하고, 반복 평가할 수 있게 감싸는 장치다.

여기서는 하네스를 특정 제품 이름으로 보지 않고, 에이전트 실행을 감싸고 관찰, 검증, 평가하게 하는 실행 장치라는 좁은 의미로 제한합니다.

이 절에서는 하네스(harness), 추적(trace), 로그(log), 평가(evaluation), 그레이더(grader), 재현성(reproducibility)을 중심으로 실행이 어떻게 관찰 가능하고 비교 가능해지는지 정리합니다. 14.3의 에이전트 구조와 14.4의 MCP 연결을 받아, 비용과 운영 제약은 14.6으로 넘깁니다.

여기서는 하네스(harness), 추적(trace), 로그(log), 평가(evaluation), 그레이더(grader)의 기본 역할을 설명합니다. 비용(cost), 지연 시간(latency), 운영(operation) 제약은 P1-14.6에서 다시 다룹니다. 여기서는 먼저 에이전트 실행을 어떻게 관찰 가능하고 비교 가능하게 만들 것인가를 닫는 데 집중합니다.

하네스, 추적, 로그, 평가, 그레이더, 재현성은 서로 다른 실행 검증 요소입니다. 각 용어의 역할은 다음처럼 구분할 수 있습니다.

용어 아주 짧은 뜻 이 절에서의 역할
하네스 실행을 감싸고 관찰하게 하는 장치 이 절의 중심 개념
추적 요청 하나의 단계 흐름 기록 어디서 무슨 일이 일어났는지 보는 단서
로그 나중에 다시 확인할 수 있는 기록 책임과 재현의 기반
평가 결과를 기준에 따라 비교하는 과정 개선 여부 판단
그레이더 평가 기준을 실행 가능한 형태로 만든 것 자동 비교의 도구
재현성 같은 조건에서 다시 확인할 수 있는 성질 회귀와 반복 검증의 전제

여기서는 하네스는 실행을 감싸고, 추적과 로그는 기록을 남기고, 평가는 비교 기준을 만든다는 구분을 기준선으로 둡니다.

주제 이 절에서 볼 질문
하네스(harness) 실행을 왜 감싸야 하는가?
추적(trace) 어떤 단계가 어떤 순서로 실행되었는가?
로그(log) 나중에 무엇을 확인할 수 있어야 하는가?
평가(evaluation) 결과가 좋아졌는지 어떻게 비교하는가?
재현성(reproducibility) 같은 조건에서 다시 확인할 수 있는가?

평가 실행 환경을 분리하는 기준

  • 하네스(harness)를 모델 자체가 아니라 실행을 감싸는 환경으로 이해합니다.
  • 하네스(harness)의 어원적 직관과 테스트 하네스(test harness)에서 온 용례를 연결합니다.
  • 에이전트(agent)와 도구 사용(tool use)에는 추적(trace)과 로그(log)가 필요함을 이해합니다.
  • 평가(evaluation)를 느낌이 아니라 기준, 데이터셋(dataset), 그레이더(grader), 반복 실행으로 봅니다.
  • 디버깅(debugging), 회귀(regression) 확인, 개선 루프(improvement loop)를 구분합니다.
  • AI 서비스가 “한 번 잘 답한 것”과 “반복적으로 안정적인 것”은 다르다는 점을 이해합니다.

세 가지 기준

여기서는 하네스를 특정 제품 이름으로 이해하지 않게 만듭니다. 본문을 읽을 때 기준이 되는 세 가지 관점은 다음과 같습니다.

기준 왜 중요한가 이 절에서 필요한 이해 수준
하네스(harness)는 모델이 아니라 실행을 감싸는 장치라는 점 하네스를 또 다른 AI 능력으로 오해하지 않게 해 줍니다. 실행을 묶고 기록하고 검증하게 하는 환경으로 이해합니다.
에이전트 실행에는 추적(trace)과 로그(log)가 필요하다는 점 여러 단계 작업을 나중에 다시 읽고 고치게 해 줍니다. 어떤 단계가 어떤 순서로 실행됐는지 남겨야 한다고 이해합니다.
한 번 잘 된 결과와 반복적으로 안정적인 결과는 다르다는 점 평가(evaluation)의 필요성을 가장 잘 보여 줍니다. 우연한 성공이 아니라 반복 확인이 중요하다고 이해합니다.

하네스라는 말이 왜 어울리는가

하네스는 힘을 만드는 장치가 아닙니다. 이미 존재하는 힘이나 움직임이 위험하게 흩어지지 않도록 붙잡고, 연결하고, 일정한 방향으로 쓰게 하는 장치에 가깝습니다. 어원 자료에서도 장비(equipment), 준비(equip), 힘을 쓰도록 제어하기(control for use as power)의 흐름을 확인할 수 있습니다. 이 감각을 놓치면 AI 문맥의 하네스를 모델 자체나 새로운 알고리즘으로 오해하기 쉽습니다.

물리적 하네스: 힘을 만드는 것이 아니라, 힘을 붙잡고 연결한다.

테스트 하네스: 코드를 만드는 것이 아니라, 코드를 일정 조건에서 실행하고 확인하게 한다.

AI 실행 하네스: 모델 능력을 만드는 것이 아니라, 모델과 도구의 실행을 관찰 가능한 작업 흐름으로 묶는다.

소프트웨어 테스트에서 하네스라는 말이 자연스러운 이유도 여기에 있습니다. 테스트 대상은 혼자서는 실제 운영 환경과 같은 조건을 만들기 어렵습니다. 그래서 테스트 하네스가 입력을 넣고, 필요한 환경을 흉내 내고, 출력과 오류를 비교합니다.

AI 에이전트(agent)에서도 비슷합니다. LLM이 문장을 생성할 수 있고 도구를 호출할 수 있어도, 그것만으로는 서비스가 되지 않습니다. 프롬프트(prompt), 컨텍스트(context), 도구(tool), 권한(permission), 승인(approval), 로그(log), 평가(evaluation)가 함께 묶여야 실제 작업 흐름이 됩니다.

모델만 있는 상태: 답변은 만들 수 있지만, 실행 조건과 책임 경계가 흐리다.

하네스가 있는 상태: 입력, 도구, 중간 단계, 출력, 평가 기준이 함께 묶인다.

이렇게 보면 하네스는 AI의 능력을 과장하는 말이 아닙니다. 오히려 AI의 능력을 실제 일에 쓰기 위해 필요한 제약과 관찰 장치를 가리키는 말입니다. “힘을 억누르는 장치”라기보다 “힘을 안전하게 쓰게 하는 연결 장치”로 이해하면 직관적으로 따라가기 쉽습니다.

최근에는 이 느슨한 용어를 학술적으로 정리하려는 시도도 등장했습니다. 2026년 arXiv 프리프린트는 하네스의 계보를 말의 장구, 소프트웨어 테스트 하네스, 머신러닝 평가 하네스, 에이전트 하네스로 이어지는 흐름으로 재구성합니다. 다만 이 자료는 최근 프리프린트이므로, 여기서는 표준 정의의 근거라기보다 “왜 이 용어가 AI 에이전트 문맥에서 중요해졌는가”를 설명하는 보조 근거로만 사용합니다.

가까운 말들과 구분하기

하네스는 워크플로우(workflow), 파이프라인(pipeline), 운영(Ops), 프레임워크(framework)와 비교할 수 있습니다. 그러나 이 말들은 서로 겹치지만 같은 말은 아닙니다.

관점 중심 질문 이 절에서의 위치
워크플로우(workflow) 일이 어떤 순서로 흘러가는가? 에이전트 실행의 단계 흐름을 이해하는 말
파이프라인(pipeline) 입력이 어떤 처리 단계를 지나 출력이 되는가? 반복 가능한 처리 흐름을 이해하는 말
운영(Ops) 실행을 어떻게 안정적으로 반복, 관찰, 개선할 것인가? 하네스를 이해하기 위한 비교 배경
프레임워크(framework) 개발자가 무엇을 만들 수 있게 구조와 API를 제공하는가? 하네스를 포함하거나 하네스 구현에 사용될 수 있는 더 넓은 구조
하네스(harness) 실행을 어떻게 감싸고 기록하고 평가할 것인가? 이 절의 중심 개념

따라서 하네스를 DevOps, MLOps, LLMOps 같은 하나의 운영 방법론이나 도구 묶음으로 이해하면 안 됩니다. 운영 관점은 “왜 관찰, 반복, 검증이 필요한가”를 떠올리게 하는 비교 배경일 뿐입니다. 또한 하네스가 반드시 trace 도구 + log 도구 + eval 도구처럼 별도 제품 묶음으로 존재하는 것도 아닙니다.

어떤 시스템에서는 에이전트가 다른 에이전트를 호출하고, 검토 에이전트가 결과를 점검하고, 별도 평가 흐름이 실행을 다시 확인하는 식으로 하네스와 비슷한 역할을 합니다. 이때 하네스는 하나의 도구 이름이라기보다, 실행을 연결하고 붙잡고 검증 가능하게 만드는 패턴으로 나타납니다.

하지만 여러 에이전트를 연결했다고 해서 자동으로 하네스가 되는 것도 아닙니다. 그 연결이 실행 조건을 제한하고, 중간 단계를 남기고, 결과를 비교하고, 실패를 다시 확인하게 할 때 하네스 관점으로 볼 수 있습니다.

왜 실행을 감싸야 하는가

단순한 모델 호출은 비교적 관찰하기 쉽습니다.

입력(input) -> 모델(model) -> 출력(output)

하지만 P1-14.3과 P1-14.4에서 본 에이전트와 MCP 흐름은 더 복잡합니다.

사용자 요청 -> 모델 호출 -> 문서 검색 -> 도구 목록 확인 -> 도구 호출 -> 결과 관찰 -> 다시 모델 호출 -> 최종 답변

이런 흐름에서 결과가 틀렸을 때 “모델이 틀렸다”라고만 말하면 원인을 찾기 어렵습니다.

실패 원인 예
입력 문제 사용자 요청을 잘못 해석함
검색 문제 관련 없는 문서를 가져옴
도구 문제 잘못된 인자로 API를 호출함
상태 문제 이전 단계 결과를 잘못 기억함
판단 문제 도구 결과를 잘못 해석함
출력 문제 근거 없이 단정하거나 형식을 어김

하네스는 이 복잡한 실행을 단계별로 감싸서 “어디에서 문제가 생겼는지”를 볼 수 있게 합니다.

실행을 감싸지 않은 상태: 결과만 보인다.

실행을 감싼 상태: 입력, 검색, 도구 호출, 중간 결과, 최종 출력, 오류가 함께 보인다.

추적은 실행의 흐름을 남긴다

추적(trace)은 하나의 요청이 어떤 단계를 거쳐 처리되었는지 남기는 기록입니다. 로그(log)가 넓은 의미의 기록이라면, trace는 특히 요청 하나의 흐름과 단계 관계를 보는 데 가깝습니다.

OpenAI Agents SDK 문서는 실행 추적이 모델 호출, 도구 호출, 핸드오프(handoff), 가드레일(guardrail), 커스텀 스팬(custom span)을 구조화된 기록으로 남길 수 있음을 설명합니다. 이 문서를 제품 사용법으로 외울 필요는 없습니다. 여기서는 “에이전트 실행은 단계별 관찰이 필요하다”는 근거로 읽으면 됩니다.

추적 대상 확인하려는 질문
모델 호출(model call) 어떤 입력을 넣고 어떤 출력을 받았는가?
검색(retrieval) 어떤 문서가 선택되었는가?
도구 호출(tool call) 어떤 도구를 어떤 인자로 실행했는가?
가드레일(guardrail) 어떤 검증이나 차단 조건이 작동했는가?
오류(error) 어느 단계에서 실패했는가?
시간(duration) 어느 단계가 오래 걸렸는가?

예를 들어 “문서를 찾아 요약하고 이슈를 생성해 줘”라는 요청이 실패했다고 합시다.

실패 결과: 이슈 내용이 엉뚱함

trace로 확인할 수 있는 질문: 검색된 문서가 맞았는가? 요약이 틀렸는가? 이슈 생성 도구의 인자가 틀렸는가? 중간에 사용자 승인을 건너뛰었는가?

trace는 정답을 자동으로 알려 주지는 않습니다. 하지만 원인을 찾아갈 단서를 제공합니다.

로그는 나중에 설명할 수 있게 한다

로그(log)는 실행 이후에 확인할 수 있는 기록입니다. AI 서비스에서는 로그가 단순한 개발자 디버깅 자료를 넘어 책임과 재현성의 기반이 됩니다.

로그에 남길 수 있는 것 이유
요청 식별자(request id) 특정 실행을 다시 찾기 위해
입력 요약(input summary) 어떤 요청이었는지 확인하기 위해
사용한 모델(model) 모델 변경 전후를 비교하기 위해
검색 결과(retrieved context) 어떤 근거를 사용했는지 확인하기 위해
도구 호출(tool call) 외부 시스템에 어떤 행동을 했는지 확인하기 위해
승인 기록(approval record) 사람이 승인했는지 확인하기 위해
최종 출력(final output) 사용자에게 무엇을 보냈는지 확인하기 위해
오류(error) 실패 원인을 분석하기 위해

다만 로그는 무조건 많이 남기면 좋은 것이 아닙니다. 개인정보(personal information), 비밀키(secret), 내부 문서, 사용자의 민감한 입력이 그대로 남으면 보안 문제가 됩니다. 그래서 로그는 “나중에 설명할 수 있을 만큼 충분히, 위험한 정보는 줄여서” 남겨야 합니다.

이 문제는 Part 1 Chapter 15의 보안과 개인정보 논의로 이어집니다. 여기서는 하네스가 기록을 남겨야 하지만, 기록 자체도 설계 대상이라는 점만 잡습니다.

평가는 느낌이 아니라 반복 가능한 비교다

AI 결과를 보고 “괜찮아 보인다”라고 느끼는 것은 시작점일 수 있습니다. 하지만 서비스로 만들려면 반복 가능한 평가(evaluation)가 필요합니다.

평가는 보통 다음 요소를 포함합니다.

요소 설명
데이터셋(dataset) 반복해서 확인할 입력 사례 모음
기대 결과(expected output) 정답, 기준 답변, 사람이 기대하는 속성
그레이더(grader) 결과를 점수화하거나 통과/실패로 판단하는 기준
평가 실행(eval run) 같은 기준으로 여러 사례를 실행하는 과정
보고서(report) 어떤 항목이 좋아졌고 나빠졌는지 보는 결과

OpenAI의 에이전트 평가 문서는 개별 trace를 살펴본 뒤, 반복성이 필요해지면 데이터셋과 평가 실행으로 넘어가라고 설명합니다. 이 흐름은 특정 도구에만 해당하는 이야기가 아니라, AI 서비스를 개선할 때 일반적으로 필요한 사고방식입니다.

개별 사례 확인: 이 요청은 왜 실패했는가?

반복 평가: 이 변경이 여러 요청에서 성능을 개선했는가?

그레이더는 평가 기준을 실행 가능한 형태로 만든다

그레이더(grader)는 결과를 평가하는 기준을 실행 가능한 형태로 만든 것입니다. 전통적인 테스트에서는 정답이 명확한 경우가 많습니다.

입력: 2 + 2 기대 결과: 4

하지만 생성형 AI(generative AI)에서는 정답이 하나가 아닐 수 있습니다. 그래서 그레이더는 더 다양한 기준을 가질 수 있습니다.

평가 기준 예
정확성(accuracy) 답변이 근거 문서와 맞는가?
형식(format) JSON 형식이나 표 형식을 지켰는가?
근거성(groundedness) 출처 없는 주장을 하지 않았는가?
안전성(safety) 금지된 행동이나 민감 정보 노출이 없는가?
작업 성공(task success) 실제로 요청한 작업이 끝났는가?

그레이더도 완벽하지 않습니다. 사람 평가(human review)가 필요할 수 있고, 자동 평가가 놓치는 품질 문제가 있을 수 있습니다. 따라서 그레이더는 사람의 판단을 완전히 대체하기보다 반복 확인을 돕는 기준으로 보는 것이 안전합니다.

회귀를 막는 것이 중요하다

소프트웨어에서는 새 기능을 추가했더니 기존 기능이 깨지는 일을 회귀(regression)라고 부릅니다. AI 서비스에서도 비슷한 일이 생깁니다.

프롬프트를 고쳤더니 답변이 더 친절해졌다. 하지만 출처 표시는 더 자주 빠지게 되었다.

모델을 바꿨더니 요약 품질은 좋아졌다. 하지만 비용과 지연 시간이 늘었다.

하네스와 평가는 이런 변화를 확인하게 도와줍니다.

변경 확인할 것
프롬프트 수정 기존 사례에서 품질이 유지되는가?
모델 교체 정확도, 비용, 지연 시간이 어떻게 바뀌는가?
RAG 검색 방식 변경 근거 문서 선택이 나아졌는가?
도구 추가 잘못된 도구 호출이 늘지 않았는가?
승인 정책 변경 위험한 행동이 차단되는가?

이 관점이 없으면 AI 서비스는 “오늘은 잘 되는 것처럼 보이는 상태”에 머무르기 쉽습니다. 학습자 입장에서도 평가 기준을 세우면 AI 결과를 더 차분하게 검토할 수 있습니다.

하네스가 해결하지 않는 것

하네스가 있다고 해서 AI 서비스가 자동으로 안전하고 정확해지는 것은 아닙니다.

해결하지 않는 문제 이유
좋은 평가 기준 정의 무엇을 좋은 결과로 볼지는 사람이 정해야 함
데이터셋 대표성 평가 사례가 현실 요청을 충분히 대표해야 함
자동 평가 오류 그레이더도 잘못 판단할 수 있음
보안 정책 로그와 도구 실행에는 별도 보안 설계가 필요함
비용과 지연 시간 평가와 추적 자체도 비용을 만든다

따라서 하네스는 “정답을 보장하는 장치”가 아니라 “실행을 관찰하고 개선할 수 있게 만드는 장치”입니다.

체크리스트

  • 하네스(harness)를 모델 자체가 아니라 실행을 감싸는 환경으로 설명할 수 있다.
  • 하네스의 어원적 직관을 장비, 고정, 연결, 활용의 흐름으로 설명할 수 있다.
  • 테스트 하네스(test harness)에서 에이전트 하네스(agent harness)로 의미가 확장되는 흐름을 설명할 수 있다.
  • 하네스를 DevOps, 프레임워크, trace/log/eval 도구 묶음과 동일시하지 않아야 함을 설명할 수 있다.
  • 추적(trace)과 로그(log)가 에이전트 실행을 이해하는 데 왜 필요한지 설명할 수 있다.
  • 평가(evaluation)를 데이터셋(dataset), 기준(criteria), 그레이더(grader), 평가 실행(eval run)의 조합으로 설명할 수 있다.
  • 프롬프트, 모델, RAG, 도구 변경 후 회귀(regression)를 확인해야 함을 설명할 수 있다.
  • 하네스가 정답을 보장하는 장치가 아니라 관찰과 개선을 가능하게 하는 장치임을 설명할 수 있다.
  • 실행을 감싼다, 단계를 기록한다, 반복 비교한다를 기준으로 하네스의 역할을 설명할 수 있다.

출처와 참고 자료