AI 에이전트에서 말하는 ‘하네스’란 무엇인가

요즘 AI 에이전트 이야기를 보다 보면 “하네스”라는 말을 자주 보게 된다.

처음에는 조금 헷갈린다.
모델, 프롬프트, 에이전트, 워크플로우, 오케스트레이션 같은 말도 이미 많은데, 여기에 하네스까지 나오니 비슷한 개념이 하나 더 늘어난 것처럼 느껴진다.

그런데 하네스를 어렵게 볼 필요는 없다.

내가 이해한 하네스는 한 문장으로 말하면 이렇다.

AI 모델을 실제로 일하게 만드는 실행 구조.

모델은 기본적으로 생각하고, 판단하고, 문장을 만든다.
하지만 모델 혼자서는 파일을 열 수도 없고, DB를 수정할 수도 없고, 테스트를 실행할 수도 없고, Gmail이나 캘린더에 접근할 수도 없다.

모델이 이런 일을 하려면 바깥에서 도구를 붙여줘야 한다.
또 어떤 도구를 언제 실행할지, 어디까지 자동화할지, 위험한 작업은 어떻게 막을지, 실행 결과를 어떻게 다시 모델에게 전달할지 같은 구조도 필요하다.

이런 전체 구조를 하네스라고 볼 수 있다.

LangChain 쪽 문서에서도 Agent = Model + Harness라는 식으로 설명한다.
이 표현이 꽤 직관적이다.

모델만 있으면 그냥 대답하는 AI에 가깝다.
그 모델을 실제 작업 환경에 연결하고, 도구를 쓰게 하고, 상태를 기억하게 하고, 권한을 통제하면 비로소 에이전트에 가까워진다.

그래서 하네스는 “모델을 감싸서 실제로 일하게 만드는 시스템”이라고 이해하면 된다.

모델, 하네스, 에이전트는 어떻게 다를까

세 개념을 구분하면 훨씬 이해하기 쉽다.

사람에 비유하면 모델은 두뇌에 가깝다.
하네스는 몸, 손, 기억, 업무 규칙, 작업장, 감시 시스템에 가깝다.

모델은 “어떻게 해야 할지”를 생각한다.
하네스는 그 생각을 실제 행동으로 연결한다.

예를 들어 같은 GPT를 쓰더라도 하네스가 다르면 완전히 다른 결과가 나온다.

어떤 하네스는 웹 검색만 할 수 있다.
어떤 하네스는 파일을 읽고 수정할 수 있다.
어떤 하네스는 테스트를 실행하고, 실패하면 다시 고칠 수 있다.
또 어떤 하네스는 메일 발송이나 결제 같은 위험한 작업 전에 반드시 사람의 승인을 받도록 만들 수 있다.

결국 에이전트의 품질은 모델 성능만으로 결정되지 않는다.
모델을 어떤 환경에 넣고, 어떤 도구를 주고, 어떤 규칙으로 움직이게 하느냐가 중요하다.

1. 시스템 프롬프트

하네스의 가장 기본적인 구성 요소는 시스템 프롬프트다.

예를 들어 개발 리더 역할의 에이전트를 만든다면 이런 식으로 역할을 줄 수 있다.

너는 꼼꼼한 개발 리더다.
항상 파일 위치, 수정 이유, 영향 범위, 테스트 방법을 설명한다.
위험한 변경은 먼저 사용자에게 승인받는다.

이런 프롬프트는 모델의 역할과 말투, 판단 기준을 잡아준다.

다만 프롬프트는 어디까지나 “말로 하는 지시”다.
그래서 프롬프트만 믿으면 약하다.

예를 들어 모델에게 이렇게 말할 수 있다.

절대 파일을 삭제하지 마.

하지만 더 안전한 방식은 하네스 코드에서 아예 막는 것이다.

if (tool.name === "deleteFile") {
  throw new Error("deleteFile is not allowed");
}

둘의 차이는 크다.

프롬프트는 모델에게 “하지 말라”고 부탁하는 것에 가깝다.
반면 하네스에서 막는 것은 “하고 싶어도 못 하게 만드는 것”이다.

에이전트가 실제 업무에 가까워질수록 이 차이가 중요해진다.
단순히 말을 잘 듣는 모델을 만드는 것이 아니라, 위험한 행동을 시스템 차원에서 통제해야 한다.

2. 도구 연결

에이전트가 실제로 일을 하려면 도구가 필요하다.

예를 들어 이런 도구들이 있을 수 있다.

const tools = [
  searchWeb,
  readDatabase,
  writeDatabase,
  readFile,
  writeFile,
  runNpmTest,
  callExternalApi,
  sendEmail,
  createCalendarEvent,
];

모델은 어떤 도구가 필요한지 판단한다.
하네스는 그 도구를 실제로 실행한다.

예를 들어 사용자가 이렇게 말한다고 해보자.

내 Gmail 최근 메일을 찾아서 요약해줘.

모델 혼자서는 Gmail에 접근할 수 없다.
모델은 “Gmail 검색이 필요하겠다”고 판단할 수는 있지만, 실제 검색은 하네스가 제공하는 도구가 있어야 가능하다.

흐름은 대략 이렇게 된다.

사용자 요청
→ 모델이 Gmail 검색이 필요하다고 판단
→ 하네스가 Gmail 검색 도구 실행
→ 검색 결과를 모델에게 전달
→ 모델이 내용을 요약
→ 사용자에게 답변

도구가 없으면 에이전트는 말만 한다.
도구가 붙는 순간부터 실제 행동이 가능해진다.

그래서 하네스를 설계할 때는 “모델에게 어떤 도구를 줄 것인가”가 매우 중요하다.

너무 적게 주면 할 수 있는 일이 제한된다.
너무 많이 주면 위험하거나 산만해질 수 있다.
그래서 도구는 기능만 보고 붙이는 것이 아니라, 권한과 사용 조건까지 같이 설계해야 한다.

3. 에이전트 루프

일반적인 챗봇은 보통 한 번 입력을 받고 한 번 답변한다.

입력
→ 답변

하지만 에이전트는 보통 한 번에 끝나지 않는다.

입력
→ 계획
→ 도구 호출
→ 결과 확인
→ 다시 판단
→ 추가 도구 호출
→ 검증
→ 최종 답변

이런 반복 구조를 에이전트 루프라고 볼 수 있다.

예를 들어 코딩 에이전트라면 이런 식으로 움직일 수 있다.

요구사항 이해
→ 관련 파일 검색
→ 코드 수정
→ 테스트 실행
→ 테스트 실패 확인
→ 원인 분석
→ 다시 수정
→ 테스트 재실행
→ 최종 변경사항 정리

이 흐름을 모델 혼자 알아서 하는 것이 아니다.
하네스가 루프를 돌리고, 도구 실행 결과를 다시 모델에게 전달하고, 언제 멈출지도 관리해야 한다.

여기서 중요한 점은 제한이다.

에이전트에게 아무 제한도 두지 않으면 같은 도구를 계속 호출하거나, 비용을 과하게 쓰거나, 이상한 방향으로 작업을 이어갈 수 있다.

그래서 보통 하네스에는 이런 제한이 들어간다.

최대 도구 호출 횟수
최대 실행 시간
최대 비용
실패 시 재시도 횟수
특정 작업 전 사용자 승인
최종 결과 검증 단계

에이전트를 잘 만든다는 건 단순히 “계속 알아서 하게 만드는 것”이 아니다.
어디까지 하게 할지, 언제 멈추게 할지, 어떤 경우에 사람에게 넘길지를 정하는 일에 가깝다.

4. 상태 관리와 메모리

모델은 기본적으로 현재 입력된 컨텍스트 안에서 판단한다.

이전 작업 내역, 사용자 설정, 진행 중인 파일, 이미 완료한 단계 등을 계속 유지하려면 하네스가 상태를 관리해야 한다.

예를 들어 코딩 에이전트가 있다고 해보자.

처음에 사용자가 “NestJS로 붙이고 싶다”고 말했다.
그다음 에이전트가 관련 파일을 수정했다.
이후 테스트가 실패했다.
그러면 에이전트는 앞에서 어떤 결정을 했는지, 어떤 파일을 건드렸는지, 어떤 테스트가 실패했는지 알고 있어야 한다.

상태 관리가 없으면 에이전트는 이전 단계를 놓칠 수 있다.
이미 수정한 파일을 다시 수정하거나, 사용자가 정한 방향을 잊거나, 테스트 실패 원인을 제대로 이어서 보지 못할 수 있다.

반대로 상태 관리가 잘 되면 에이전트는 훨씬 “일하는 사람”처럼 보인다.

사용자가 선호하는 방식도 기억할 수 있고, 이전 결정사항을 이어받을 수 있고, 긴 작업을 여러 단계로 나눠서 처리할 수 있다.

이때 필요한 것이 대화 이력, 체크포인트, 작업 상태, 파일 변경 내역, 사용자 설정 같은 것들이다.

즉 메모리는 단순히 “이전 대화를 기억하는 기능”만이 아니다.
에이전트가 실제 업무를 이어서 수행하기 위한 작업 상태 관리에 가깝다.

5. 권한과 승인

에이전트가 강력해질수록 위험도 커진다.

파일을 수정할 수 있고, DB를 변경할 수 있고, 이메일을 보낼 수 있고, 캘린더 일정을 만들 수 있다면 모델에게 모든 권한을 그냥 열어두면 안 된다.

특히 이런 작업은 조심해야 한다.

파일 삭제
DB 데이터 삭제
외부 이메일 발송
결제 요청
운영 서버 배포
개인정보 접근
대량 API 호출

좋은 하네스는 모델을 무조건 믿지 않는다.

모델이 똑똑하더라도 실수할 수 있다.
요청을 잘못 해석할 수도 있고, 위험도를 낮게 판단할 수도 있고, 사용자가 원하지 않은 행동을 할 수도 있다.

그래서 하네스에는 권한 제어와 승인 절차가 필요하다.

예를 들어 이렇게 나눌 수 있다.

낮은 위험 작업 → 자동 실행
중간 위험 작업 → 로그 기록 후 실행
높은 위험 작업 → 사용자 승인 후 실행
금지 작업 → 실행 차단

이 구조가 있으면 에이전트를 더 안전하게 운영할 수 있다.

예를 들어 파일 읽기는 자동으로 허용할 수 있다.
하지만 파일 삭제는 막을 수 있다.
메일 초안 작성은 허용하되, 실제 발송은 사용자 승인 후에만 하도록 만들 수 있다.
운영 DB 수정은 아예 금지하거나 별도 승인 절차를 둘 수 있다.

결국 하네스는 모델을 믿기 위한 장치가 아니라, 모델을 안전하게 쓰기 위한 장치다.

6. 실행 환경

코딩 에이전트를 생각하면 실행 환경의 중요성이 더 잘 보인다.

모델에게 단순히 이렇게 말하는 것과,

이 코드 고쳐줘.

실제로 이런 환경을 제공하는 것은 완전히 다르다.

이 레포지토리를 읽어라.
관련 파일을 찾아라.
코드를 수정해라.
테스트를 실행해라.
실패하면 원인을 분석해라.
다시 수정해라.
최종 변경사항을 요약해라.

두 번째가 가능하려면 하네스가 작업 환경을 제공해야 한다.

예를 들어 이런 것들이 필요하다.

파일 시스템 접근
터미널 실행
패키지 설치
테스트 실행
브라우저 조작
샌드박스 환경
로그 기록
작업 디렉토리 관리

모델에게 “코드 고쳐줘”라고 말하는 것만으로는 부족하다.
모델이 실제 레포지토리를 읽고, 파일을 수정하고, 테스트를 실행할 수 있어야 한다.

물론 실행 환경을 줄수록 위험도도 커진다.
그래서 보통은 샌드박스처럼 제한된 환경에서 실행하거나, 특정 명령어만 허용하거나, 파일 접근 범위를 제한한다.

좋은 코딩 에이전트는 모델이 좋은 것도 중요하지만, 그 모델이 일할 수 있는 작업장이 잘 설계되어 있어야 한다.

7. 오케스트레이션과 핸드오프

에이전트가 하나만 있는 경우도 있지만, 여러 역할로 나눠서 운영할 수도 있다.

예를 들어 AI 직원 구조를 만든다고 해보자.

마케팅 리서처
→ 제품 기획자
→ UI/UX 디자이너
→ 개발 리더
→ QA 리뷰어

각 에이전트는 다른 역할을 맡는다.

마케팅 리서처는 시장과 사용자 니즈를 본다.
제품 기획자는 기능과 MVP 범위를 정리한다.
UI/UX 디자이너는 화면 구조와 사용자 흐름을 설계한다.
개발 리더는 구현 방식과 기술 구조를 잡는다.
QA 리뷰어는 누락된 요구사항, 엣지 케이스, 출시 리스크를 확인한다.

이때 중요한 것은 역할 간 넘김이다.

마케팅 리서처의 결과가 제품 기획자에게 전달되어야 한다.
제품 기획자의 결과가 UI/UX 디자이너에게 전달되어야 한다.
UI/UX 디자이너의 결과가 개발 리더에게 전달되어야 한다.
개발 리더의 결과는 다시 QA 리뷰어가 검토할 수 있어야 한다.

이런 흐름을 관리하는 것이 오케스트레이션이다.

또 어떤 에이전트가 자기 역할을 벗어난 작업을 만나면 다른 에이전트에게 넘길 수도 있다.
이런 역할 넘김을 핸드오프라고 볼 수 있다.

예를 들어 UI/UX 디자이너가 화면을 설계하다가 API 응답 구조가 애매하다는 걸 발견할 수 있다.
그러면 개발 리더나 백엔드 담당 에이전트에게 다시 확인을 요청해야 한다.

이런 구조가 없으면 여러 에이전트를 나눠도 결과가 따로 논다.
반대로 오케스트레이션이 잘 되어 있으면 여러 AI 직원이 하나의 팀처럼 움직일 수 있다.

에이전트를 여러 개 만든다는 건 단순히 역할 프롬프트를 여러 개 만드는 일이 아니다.
누가 언제 판단하고, 어떤 결과를 누구에게 넘기고, 어디서 검증하고, 어디서 멈출지까지 설계해야 한다.

8. 구조화 출력

에이전트가 매번 자유롭게 말하면 사람이 읽기에는 편할 수 있다.
하지만 시스템에 연결하기는 어렵다.

예를 들어 제품 기획 에이전트가 이렇게 답했다고 해보자.

이 기능은 중요해 보입니다.
우선순위는 높은 편이고, MVP에 넣는 게 좋겠습니다.

사람은 이해할 수 있다.
하지만 이 결과를 다음 단계의 시스템이 바로 처리하기는 애매하다.

반대로 출력 형식을 정해두면 이렇게 받을 수 있다.

{
  "featureName": "실시간 지역 이슈 피드",
  "priority": "P0",
  "mvpIncluded": true,
  "riskLevel": "medium",
  "reason": "서비스 핵심 가치와 직접 연결됨"
}

이렇게 구조화된 결과는 다음 단계로 넘기기 쉽다.

예를 들어 이런 흐름이 가능하다.

마케팅 리서처 결과 JSON
→ 제품 기획자 입력
→ 기능 명세 JSON
→ UI/UX 디자이너 입력
→ 화면 설계 JSON
→ 개발 리더 입력
→ 개발 티켓 생성

이 구조가 중요한 이유는 에이전트를 단순한 대화 상대가 아니라 시스템의 일부로 만들 수 있기 때문이다.

사람이 읽고 끝나는 답변이 아니라, 다음 도구나 다른 에이전트가 바로 사용할 수 있는 결과가 된다.

그래서 하네스에는 구조화 출력도 포함될 수 있다.
어떤 형식으로 답을 받을지, 어떤 필드가 필수인지, 값이 잘못되면 어떻게 다시 요청할지 같은 것까지 관리할 수 있다.

프롬프트 엔지니어링, 컨텍스트 엔지니어링, 하네스 엔지니어링

하네스를 이해하려면 프롬프트, 컨텍스트, 하네스의 차이를 구분하는 게 좋다.

프롬프트 엔지니어링

프롬프트 엔지니어링은 모델에게 말로 지시하는 것이다.

너는 꼼꼼한 개발자야.
항상 테스트를 확인해.
코드를 안전하게 수정해.

모델의 역할, 말투, 판단 기준을 잡아주는 작업에 가깝다.

컨텍스트 엔지니어링

컨텍스트 엔지니어링은 모델에게 필요한 정보를 잘 넣어주는 것이다.

관련 파일
최근 변경사항
사용자 요구사항
DB 스키마
API 명세
에러 로그
이전 결정사항

모델이 아무리 좋아도 필요한 정보가 없으면 제대로 판단하기 어렵다.
그래서 어떤 정보를 넣고, 어떤 정보는 빼고, 얼마나 압축해서 전달할지가 중요하다.

하네스 엔지니어링

하네스 엔지니어링은 모델이 실제로 일하는 구조 전체를 설계하는 것이다.

어떤 도구를 줄 것인가
어떤 순서로 실행할 것인가
어디까지 자동화할 것인가
언제 멈출 것인가
무엇을 기록할 것인가
어떻게 평가할 것인가
권한을 어떻게 제한할 것인가
실패하면 어떻게 복구할 것인가

셋을 짧게 비교하면 이렇다.

프롬프트 = 말로 시키기
컨텍스트 = 필요한 자료 챙겨주기
하네스 = 실제 업무 환경과 규칙 만들기

프롬프트만 좋아서는 부족하다.
컨텍스트가 좋아야 정확도가 올라간다.
그리고 하네스가 있어야 실제 행동과 자동화가 가능해진다.

이 세 가지가 합쳐질 때 우리가 말하는 “쓸만한 에이전트”에 가까워진다.

하네스가 중요한 이유

AI 에이전트를 만들 때 흔히 먼저 고민하는 것은 모델이다.

GPT를 쓸지, Claude를 쓸지, Gemini를 쓸지 고민한다.
물론 모델 선택은 중요하다.

하지만 실제 업무 자동화나 서비스 수준으로 가면 모델만큼이나 하네스가 중요해진다.

같은 모델을 써도 결과는 하네스에 따라 달라진다.

도구가 없는 에이전트
도구는 있지만 권한 제어가 없는 에이전트
도구, 메모리, 로그, 승인, 테스트, 재시도까지 갖춘 에이전트

이 셋은 같은 에이전트라고 부르기 어렵다.

첫 번째는 말은 잘하지만 실제 행동은 거의 못 한다.
두 번째는 행동은 할 수 있지만 위험하다.
세 번째는 실제 업무에 투입할 수 있는 구조에 가까워진다.

그래서 에이전트를 만든다는 건 단순히 모델 API를 호출하는 일이 아니다.

모델 주변에 도구를 붙이고, 상태를 관리하고, 권한을 제한하고, 실행 환경을 만들고, 결과를 검증하고, 로그를 남기고, 실패했을 때 복구하는 구조까지 설계해야 한다.

그 전체가 하네스다.

결론

하네스는 AI 모델을 실제로 일하게 만드는 실행 구조다.

모델은 생각하고 문장을 만든다.
하지만 실제 업무를 하려면 도구가 필요하고, 상태 관리가 필요하고, 권한 통제가 필요하고, 실행 환경이 필요하다.

이 모든 것을 모델 바깥에서 감싸는 구조가 하네스다.

그래서 좋은 에이전트를 만들고 싶다면 “어떤 모델을 쓸까?”만 보면 부족하다.

오히려 이런 질문을 같이 해야 한다.

이 모델에게 어떤 도구를 줄 것인가?
어떤 정보를 기억하게 할 것인가?
어떤 행동은 막을 것인가?
어떤 행동은 승인받게 할 것인가?
실패하면 어떻게 복구할 것인가?
결과를 어떻게 검증할 것인가?
다른 에이전트와 어떻게 협업하게 할 것인가?

이 질문들에 대한 답이 하네스 설계다.

결국 하네스는 모델을 챗봇에서 에이전트로 바꾸는 핵심 구조다.
AI를 단순히 대답하는 도구가 아니라, 실제로 일하는 직원처럼 쓰고 싶다면 하네스를 이해해야 한다.