에이전트 하네스 (Agent Harness)

에이전트 하네스(Agent Harness)는 AI 모델이 도구를 호출하고 작업을 이어가도록 입력, 실행 환경, 세션, 종료 조건을 관리하는 소프트웨어입니다. 같은 모델을 쓰더라도 어떤 자료와 도구를 연결하고 실행을 어떻게 제어하느냐에 따라 에이전트의 동작이 달라집니다.

모델의 결정을 실제 실행으로 잇는다

언어 모델이 “파일을 읽겠다”는 도구 호출을 생성했다고 해서 파일이 저절로 열리지는 않습니다. 호출 내용을 받아 허용된 요청인지 확인하고, 파일을 읽은 뒤 결과를 모델에 돌려주는 프로그램이 필요합니다. 모델이 다음 행동을 결정하고, 프로그램이 그 행동을 실행하는 과정을 반복하면 에이전트 루프가 됩니다. 하네스는 이 반복을 운영하면서 모델에 보낼 컨텍스트와 사용할 도구, 작업을 끝낼 조건을 관리합니다.

예를 들어 상품 목록의 빠진 설명을 채우는 에이전트를 생각해 보겠습니다. 모델은 목록에서 빈칸을 찾고 상품 자료를 검색한 뒤 새 설명을 제안합니다. 하네스는 읽을 수 있는 폴더와 검색 도구를 제공하고, 파일 저장 요청을 처리하며, 실패한 호출을 모델에 알립니다. 저장 권한이 없다면 수정안을 답변으로 반환하게 구성할 수도 있습니다. 이때 모델의 글쓰기 능력과 실제 파일을 변경할 수 있는 범위는 서로 다른 설정에 달려 있습니다.

Anthropic의 에이전트 평가 설명은 하네스를 입력 처리, 도구 호출 조정, 결과 반환을 담당하는 부분으로 설명합니다. 그래서 에이전트 성능을 비교할 때는 모델 이름만으로 조건을 설명하기 어렵습니다. 같은 모델이라도 검색 가능한 자료, 도구 설명, 재시도 방식, 작업 시간 제한이 다르면 결과가 달라질 수 있습니다. 어떤 환경에서 얻은 성능인지 함께 살펴야 비교의 의미가 분명해집니다.

세션과 작업 상태를 이어간다

긴 작업은 한 번의 모델 호출이나 한 세션 안에서 끝나지 않을 수 있습니다. 앞선 대화가 컨텍스트 윈도우를 채우면 내용을 압축하거나 필요한 부분을 골라 다음 호출에 넣어야 합니다. 이 과정에서 끝난 작업, 남은 작업, 변경된 파일, 지켜야 할 조건을 잃으면 에이전트가 같은 일을 반복하거나 잘못된 전제에서 다시 시작할 수 있습니다. 하네스에 남아 있는 전체 기록과 모델이 이번 호출에서 읽는 입력은 같지 않을 수 있습니다.

Anthropic의 장시간 에이전트 작업 사례는 진행 상황 파일과 버전 관리 기록을 남겨 다음 세션이 작업을 이어받는 구성을 다룹니다. 이를 일반적인 문서 작업에 적용하면, “기사 수정 중”이라고만 남기는 대신 수정한 항목과 아직 근거가 없는 주장을 따로 기록할 수 있습니다. 이 문서 예시는 해당 구성을 설명하기 위한 응용입니다. 모든 하네스가 같은 파일 형식이나 저장 방식을 요구하는 것은 아닙니다.

샌드박스는 파일이나 명령을 실행하는 격리 환경이고, 하네스는 그 환경을 사용하며 작업 진행을 관리합니다. 세션은 요청과 응답, 도구 실행 같은 작업 이력을 묶는 단위로 쓰입니다. Anthropic의 Managed Agents 설계는 세션 기록, 하네스, 샌드박스를 분리한 사례입니다. 실행 환경에 문제가 생겨도 외부에 남긴 기록으로 상황을 파악하고 작업을 복구할 수 있도록 구성했습니다. 이는 한 제품의 설계이며 모든 에이전트의 필수 구조를 뜻하지 않습니다.

프레임워크는 이런 프로그램을 만드는 데 쓰는 구성 요소를 제공할 수 있습니다. Agent Skills는 반복 작업의 지침과 자료를 묶고, MCP는 외부 도구나 데이터를 연결하는 방식을 정합니다. 하네스는 지원하는 범위에서 이들을 실제 작업 흐름에 연결합니다. 서브에이전트에 일을 나누는 기능도 여기에 포함될 수 있지만, 여러 에이전트를 반드시 사용해야 하네스라고 부르는 것은 아닙니다.

완료 조건과 실행 권한을 확인한다

좋은 하네스를 판단하려면 어떤 작업을 맡길지부터 구체적으로 정해야 합니다. 파일 한 개를 요약하는 작업에는 복잡한 분업이 필요하지 않을 수 있습니다. 여러 자료를 수정하는 작업에는 중단 지점 보존, 실패 보고, 재개 기능이 더 중요할 수 있습니다. 호출 횟수나 시간 한도를 두는 것도 가능한 설계입니다. 다만 한도에 도달해 멈춘 상태를 작업 완료로 표시하면 사용자는 결과를 잘못 이해하게 됩니다.

도구 응답이 성공했다고 전체 과제가 성공한 것도 아닙니다. 파일을 저장했어도 내용이 틀릴 수 있고, 모델이 완료했다고 말했어도 실제 저장이 실패했을 수 있습니다. 앞선 평가 설명도 에이전트의 실행 기록과 환경에 남은 최종 결과를 구분합니다. 상품 설명 작업이라면 저장된 파일과 누락 항목을 확인하고, 확인하지 못한 부분은 결과에 남겨야 합니다. 완료 기준은 최종 답변의 자신감보다 사용자가 요청한 변화에 맞추는 편이 정확합니다.

권한 역시 프롬프트에 “조심하라”고 쓰는 것만으로 정해지지 않습니다. 읽기와 쓰기 도구를 어떻게 노출하는지, 실행 환경이 어떤 경로에 접근할 수 있는지, 외부 전송을 어디서 제한하는지가 실제 동작을 결정합니다. 필요한 권한만 제공하고 중요한 변경에는 적절한 확인 절차를 두면, 모델의 판단 오류가 넓은 범위의 변경으로 이어질 가능성을 줄일 수 있습니다. 구체적인 통제 방식은 제품과 작업 환경에 따라 다릅니다.

실행 기록을 남기는 기능은 에이전트 관측성과도 연결됩니다. 어떤 도구에서 지연됐는지, 재시도가 얼마나 반복됐는지, 어느 단계에서 작업이 끊겼는지 확인할 수 있어야 하네스의 문제를 고칠 수 있습니다. 모델 선택과 도구 연결만으로 설명하기 어려운 실행 방식의 차이를 이해할 때 하네스라는 개념이 유용합니다.