AI 에이전트 하네스란? 모델보다 실행 구조가 중요한 이유

이 글에서 사용하는 주요 용어 정의

용어	정의
모델	입력을 받아 다음 응답이나 행동을 제안하는 언어 모델
에이전트	모델이 도구와 실행 환경을 이용해 여러 단계의 목표를 수행하는 시스템
하네스	프롬프트, 상태, 도구, 권한, 실행 루프와 검증을 모델 주변에서 관리하는 구조
오케스트레이터	작업을 나누고 담당 에이전트를 선택하며 결과를 모으는 조정 계층
품질 게이트	결과가 정해진 기준을 통과해야 다음 단계로 진행하게 하는 검증 절차

---

도입

같은 AI 모델을 사용해도 어떤 도구에서는 결과가 안정적이고, 다른 도구에서는 중간에 작업을 잊거나 검증 없이 끝나는 경우가 있습니다. 차이는 모델 성능만이 아니라 모델을 둘러싼 실행 구조, 즉 에이전트 하네스에서 생깁니다.

하네스는 모델에게 한 번 질문하고 답을 받는 화면이 아닙니다. 목표를 작업으로 바꾸고, 필요한 파일과 도구를 연결하고, 실행 결과를 다시 모델에 전달하며, 완료 조건을 검사하는 전체 루프입니다.

모델, 에이전트, 하네스는 무엇이 다른가

모델은 판단 엔진이다

모델은 자연어와 코드 같은 입력을 해석해 응답을 생성합니다. 하지만 파일을 읽거나 명령을 실행하는 능력은 모델 그 자체보다 모델에 연결된 도구와 권한에서 나옵니다.

에이전트는 모델에 행동 능력을 붙인다

에이전트는 모델이 상황을 보고 다음 행동을 선택하게 합니다. 파일 검색, 코드 수정, 테스트 실행, 웹 조회 같은 도구 호출을 반복하면서 목표에 접근합니다.

하네스는 반복 실행을 통제한다

하네스는 에이전트가 무엇을 보고 무엇을 할 수 있는지 정합니다. 실행 결과를 다음 턴에 전달하고, 승인이나 샌드박스를 적용하고, 언제 멈출지도 판단합니다.

사용자 목표
   ↓
지침과 프로젝트 컨텍스트 구성
   ↓
모델이 다음 행동 선택
   ↓
도구 실행 → 결과 수집 → 상태 갱신
   ↖                 ↓
   └──── 완료 전 반복 ────┘
             ↓
          품질 검증

에이전트 하네스의 핵심 구성 요소

지침과 컨텍스트

하네스는 사용자 요청 외에도 프로젝트 규칙, 관련 파일, Skill과 이전 실행 결과를 모델에 제공합니다. 많이 넣는 것이 항상 좋은 것은 아닙니다. 현재 결정에 필요한 정보만 남겨야 중요한 제약이 로그에 묻히지 않습니다.

도구와 실행 환경

파일 읽기·수정, 셸, 웹, 브라우저, 외부 서비스 API가 도구에 해당합니다. 좋은 하네스는 도구의 입력·출력 형식을 분명히 하고 실패를 모델이 구분할 수 있게 전달합니다.

상태 관리

장기 작업에는 현재 목표, 완료된 단계, 변경 파일과 실패 기록이 필요합니다. 상태를 대화에만 쌓으면 컨텍스트가 길어질수록 핵심 정보가 흐려질 수 있습니다. 중요한 결과를 파일이나 구조화된 데이터로 남기는 이유입니다.

권한과 승인

읽기와 쓰기, 로컬 변경과 외부 전송은 위험이 다릅니다. 하네스는 샌드박스 범위를 정하고 삭제, 배포, 결제처럼 영향이 큰 행동 전에 승인을 요구해야 합니다.

검증과 관측성

"코드를 수정했다"는 메시지만으로 작업이 끝난 것은 아닙니다. 테스트, 린트, 결과 파일, diff를 통해 상태를 확인해야 합니다. 어떤 도구를 실행했고 무엇이 실패했는지 추적할 수 있어야 문제도 재현할 수 있습니다.

멀티 에이전트 하네스는 무엇이 추가되나

멀티 에이전트 하네스는 하나의 에이전트가 모든 일을 하는 대신 전문 역할을 나눕니다. Codex 공식 매뉴얼은 독립적인 탐색, 테스트, 분류와 요약 같은 읽기 중심 작업을 병렬화의 좋은 출발점으로 설명합니다.

             ┌─ 탐색 에이전트
오케스트레이터 ├─ 테스트 에이전트  → 결과 요약 → 최종 판단
             └─ 문서 검증 에이전트

핵심은 에이전트 수가 아니라 작업 경계입니다. 서로 같은 파일을 동시에 고치거나 앞 단계 결과가 필요한 작업을 억지로 병렬화하면 충돌과 재작업이 늘어납니다.

언제 하네스가 필요한가

다음과 같은 작업은 하네스의 효과가 큽니다.

• 파일과 명령을 여러 번 오가는 장기 작업
• 조사, 구현, 테스트처럼 단계와 산출물이 분명한 작업
• 결과 형식과 검증 기준을 반복해서 적용해야 하는 작업
• 권한이 다른 도구를 안전하게 연결해야 하는 작업
• 중간 실패 후 재개하거나 감사 기록을 남겨야 하는 작업

반면 한 문장 번역이나 간단한 개념 질문에는 복잡한 하네스가 필요하지 않습니다. 실행 구조의 비용이 실제 작업보다 커질 수 있습니다.

실제 적용과 한계

좋은 하네스도 잘못된 목표를 고쳐주지는 못합니다. 완료 조건이 모호하거나 검증이 결과를 제대로 측정하지 못하면 에이전트는 잘못된 방향으로도 일관되게 움직일 수 있습니다.

멀티 에이전트는 추가 토큰과 조정 비용을 사용합니다. 병렬화 가능한 독립 작업이 있는지, 결과를 누가 통합할지, 동시 쓰기를 어떻게 막을지를 먼저 정해야 합니다.

마무리

AI 에이전트 하네스는 모델의 지능을 키우는 기술이 아니라, 모델이 실제 환경에서 안전하고 반복 가능하게 일하도록 만드는 실행 구조입니다. 지침, 상태, 도구, 권한과 검증이 핵심입니다.

처음부터 거대한 멀티 에이전트 시스템을 만들 필요는 없습니다. 반복 작업 하나를 골라 입력, 출력, 실행 단계와 검증 기준을 파일로 정리하는 것부터 시작하면 됩니다.

참고 자료

• OpenAI Codex Manual - Multi-agent operations
• Harness Handbook: Making Evolving Agent Harnesses Readable, Navigable, and Editable