AI 에이전트와 하네스의 기본 구조

에이전트는 모델 하나가 아니다

AI 에이전트를 처음 접하면 흔히 "LLM이 알아서 일을 처리한다"고 생각하기 쉽다. 하지만 실제 시스템에서 에이전트는 모델 하나로 이루어지지 않는다. 모델은 중요한 부품이지만, 전체 장치의 일부일 뿐이다.

실제로 하나의 에이전트는 보통 다음 요소들이 함께 움직인다.

• LLM: 사용자의 요청을 해석하고 다음 행동을 제안한다.

• 시스템 프롬프트: 에이전트의 역할, 금지 사항, 응답 형식, 우선순위를 정한다.

• 도구 호출: 검색, 계산, 코드 실행, 파일 수정, API 요청 같은 외부 행동을 수행한다.

• 파일 시스템: 작업 대상이 되는 문서, 코드, 설정, 로그를 읽고 쓴다.

• 외부 API: 결제, 고객 관리, 배포, 이슈 트래킹처럼 실제 서비스와 연결된다.

• 메모리와 컨텍스트: 지금까지의 대화, 작업 상태, 관련 문서를 모델에 제공한다.

• 실행 루프: 모델 호출, 도구 실행, 결과 관찰, 다음 판단을 반복한다.

• 검증기: 출력 형식, 정책 위반, 테스트 결과, 품질 기준을 확인한다.

따라서 에이전트를 이해할 때는 "모델이 무엇을 아는가"보다 "모델이 어떤 환경 안에서 무엇을 할 수 있는가"를 보아야 한다. 이 환경을 설계하고 통제하는 일이 하네스 엔지니어링의 출발점이다.

한 번의 실행은 어떻게 흐르는가

간단한 작업 자동화 에이전트를 생각해 보자. 사용자가 "이 저장소의 테스트 실패 원인을 찾아 고쳐줘"라고 요청한다. 에이전트는 곧바로 파일을 수정하지 않는다. 제대로 설계된 하네스 안에서는 대략 이런 순서로 움직인다.

1. 요청 수신: 사용자의 목표와 제약을 받는다.

2. 컨텍스트 구성: 저장소 구조, 관련 파일, 이전 대화, 실행 가능한 도구 목록을 정리한다.

3. 모델 호출: LLM이 현재 정보로 다음 행동을 판단한다.

4. 도구 선택: 파일 읽기, 테스트 실행, 검색, 코드 수정 중 하나를 요청한다.

5. 권한 확인: 해당 도구를 지금 실행해도 되는지 런타임이 확인한다.

6. 도구 실행: 허용된 작업만 실제 환경에서 수행한다.

7. 관찰 반환: 실행 결과, 오류, 로그, 변경 사항을 모델에 다시 전달한다.

8. 검증: 테스트, 린트, 형식 검사, 정책 검사를 수행한다.

9. 반복 또는 종료: 목표가 충족되면 결과를 보고하고, 아니면 다음 루프로 간다.

이 구조에서 중요한 점은 모델이 모든 것을 직접 하지 않는다는 것이다. 모델은 다음 행동을 제안한다. 런타임은 그 행동을 실행할지 결정하고, 실행 결과를 기록하며, 문제가 생기면 중단하거나 복구한다.

하네스를 이루는 다섯 계층

하네스는 에이전트를 감싸는 실행 환경이다. 복잡해 보이지만 크게 다섯 계층으로 나누면 이해하기 쉽다.

프롬프트 계층

프롬프트 계층은 에이전트의 행동 원칙을 정한다. 시스템 프롬프트, 개발자 지시, 사용자 요청, 출력 형식 규칙이 여기에 속한다.

좋은 프롬프트 계층은 단순히 "친절하게 답하라"가 아니다. 어떤 일을 우선해야 하는지, 어떤 정보가 부족하면 질문해야 하는지, 어떤 행동은 절대 하면 안 되는지까지 정한다. 즉 프롬프트는 말투를 꾸미는 문장이 아니라 에이전트의 제어 평면이다.

실행 루프 계층

실행 루프는 에이전트의 심장박동과 같다. 모델을 한 번 호출하고 끝내는 것이 아니라, 판단과 실행과 관찰을 반복한다.

장시간 작업에서는 이 계층이 특히 중요하다. 루프가 없으면 모델은 긴 작업을 한 번에 추측해야 한다. 루프가 있으면 작은 단위로 실행하고, 결과를 확인하고, 다시 계획을 고칠 수 있다. 에이전트가 "일을 해내는 시스템"이 되려면 이 반복 구조가 필요하다.

도구 제어 계층

도구는 에이전트의 손과 발이다. 하지만 손과 발이 자유롭다고 항상 좋은 것은 아니다. 파일 삭제, 코드 배포, 고객 데이터 조회, 결제 취소 같은 행동은 큰 영향을 줄 수 있다.

도구 제어 계층은 어떤 도구를 언제, 어떤 입력으로, 어떤 권한 수준에서 사용할 수 있는지 정한다. 읽기 전용 도구와 쓰기 도구를 분리하고, 위험한 작업에는 승인 단계를 두며, 도구 입력을 검증한다. 모델이 도구를 부르는 능력보다 중요한 것은 잘못된 도구 호출을 막는 능력이다.

컨텍스트 관리 계층

LLM은 한 번에 볼 수 있는 정보량에 제한이 있다. 따라서 모든 문서와 모든 로그를 한꺼번에 넣을 수 없다. 컨텍스트 관리 계층은 지금 필요한 정보를 골라 모델에 전달한다.

여기에는 대화 요약, 관련 파일 검색, 작업 상태 저장, 이전 결정 기록, 불필요한 정보 제거가 포함된다. 컨텍스트가 부족하면 모델은 엉뚱한 결정을 한다. 반대로 컨텍스트가 너무 많으면 중요한 신호가 묻힌다. 하네스는 모델에게 "많은 정보"가 아니라 "쓸 수 있는 정보"를 제공해야 한다.

평가·관측 계층

에이전트가 한 일을 믿으려면 확인할 수 있어야 한다. 평가 계층은 결과가 기준을 만족하는지 검사한다. 테스트 통과 여부, 출력 스키마 준수, 금지어 포함 여부, 보안 정책 위반 여부가 여기에 들어간다.

관측 계층은 실행 과정을 기록한다. 어떤 프롬프트가 사용되었는지, 어떤 도구가 호출되었는지, 어디서 실패했는지, 비용과 지연 시간은 얼마였는지 남긴다. 운영 환경에서는 "왜 이런 결과가 나왔는가"를 추적할 수 있어야 한다. 관측 가능성이 없으면 개선도 어렵고 책임도 불분명해진다.

모델은 판단하고, 런타임은 책임진다

에이전트 설계에서 가장 중요한 원칙 중 하나는 책임 분리다. 모델은 자연어와 불완전한 정보를 바탕으로 다음 행동을 판단한다. 여기서 "생각"이라는 말은 비유다. 모델은 사람처럼 의도를 갖고 숙고하는 존재가 아니라, 주어진 입력을 바탕으로 가능성 높은 출력을 생성하는 시스템이다.

반면 런타임은 실제 책임을 진다. 런타임은 다음 일을 해야 한다.

• 허용된 도구만 실행한다.

• 위험한 행동은 차단하거나 승인을 요구한다.

• 모든 호출과 결과를 기록한다.

• 실패하면 재시도, 롤백, 중단 중 하나를 선택한다.

• 결과가 기준을 만족하는지 검증한다.

이 구분이 흐려지면 시스템은 위험해진다. 모델이 "괜찮다"고 말했기 때문에 삭제 명령을 실행하는 구조는 안전하지 않다. 모델의 판단은 후보일 뿐이다. 실제 실행 여부는 하네스가 결정해야 한다.

에이전트 프레임워크와 하네스는 다르다

에이전트 프레임워크는 에이전트를 만들기 쉽게 해 주는 도구 모음이다. 모델 호출 래퍼, 도구 등록 방식, 메모리 모듈, 체인 구성, 에이전트 실행기 같은 기능을 제공한다. 개발자는 이를 이용해 빠르게 프로토타입을 만들 수 있다.

하지만 프레임워크를 사용한다고 해서 자동으로 좋은 하네스가 생기지는 않는다. 하네스는 특정 제품과 조직의 목적에 맞게 설계된 통제 구조다.

비유하면 프레임워크는 부품과 배관에 가깝다. 하네스는 그 부품을 어떤 순서로 연결하고, 어디에 차단기를 두고, 어떤 계기판으로 상태를 볼지 정하는 설계다.

복잡도에 따라 필요한 하네스도 달라진다

모든 AI 시스템에 같은 수준의 하네스가 필요한 것은 아니다. 작업의 길이, 도구의 위험도, 실패 비용에 따라 구조가 달라진다.

단일 턴 챗봇

단일 턴 챗봇은 사용자의 질문에 한 번 답하는 구조다. 외부 도구가 없거나 제한적이고, 상태도 오래 유지하지 않는다. 이 경우 핵심은 출력 품질, 금지 응답 방지, 기본적인 형식 검증이다.

하지만 단순하다고 해서 하네스가 필요 없는 것은 아니다. 고객 상담, 의료, 법률, 금융처럼 답변의 영향이 큰 영역에서는 단일 턴이라도 강한 검증과 정책 제어가 필요하다.

작업 자동화 봇

작업 자동화 봇은 캘린더 등록, 티켓 생성, 문서 요약, 데이터 조회처럼 외부 시스템과 연결된다. 여기서부터 도구 권한이 중요해진다.

읽기 작업과 쓰기 작업을 구분해야 하고, 사용자의 의도를 확인해야 하며, 실행 결과를 기록해야 한다. "요청을 이해했는가"보다 "정말 이 행동을 해도 되는가"가 더 중요해지는 단계다.

장시간 코딩 에이전트

장시간 코딩 에이전트는 여러 파일을 읽고, 코드를 수정하고, 테스트를 실행하고, 실패 원인을 추적한다. 이 시스템에는 실행 루프, 작업 기억, 파일 변경 추적, 테스트 기반 검증이 필요하다.

코딩 에이전트가 위험한 이유는 한 번의 실수가 누적될 수 있기 때문이다. 잘못된 가정을 바탕으로 여러 파일을 바꾸면 나중에 원인을 찾기 어렵다. 따라서 작은 변경, 자주 검증, 명확한 로그, 되돌릴 수 있는 구조가 중요하다.

다중 에이전트 시스템

다중 에이전트 시스템은 여러 에이전트가 역할을 나누어 협업한다. 예를 들어 기획 에이전트, 구현 에이전트, 리뷰 에이전트, 테스트 에이전트가 함께 일할 수 있다.

이 단계에서는 개별 에이전트보다 조정 문제가 커진다. 누가 최종 결정을 내리는지, 충돌하는 의견을 어떻게 해결하는지, 같은 도구를 동시에 호출해도 되는지, 전체 상태를 어디에 저장할지가 중요하다. 하네스는 단순한 실행기가 아니라 오케스트레이션 계층이 된다.

전체 지도를 먼저 가져야 한다

하네스 엔지니어링을 배우는 이유는 모델을 더 신비롭게 보기 위해서가 아니다. 오히려 반대다. 에이전트 시스템을 구성 요소로 분해하고, 각 요소의 책임을 명확히 하려는 것이다.

모델은 판단한다. 프롬프트는 방향을 준다. 도구는 행동을 가능하게 한다. 메모리는 작업의 연속성을 만든다. 런타임은 허용하고 차단하고 기록하고 복구한다. 검증기는 결과를 확인한다. 관측 계층은 다음 개선의 근거를 남긴다.

이 전체 지도를 이해하면 이후의 주제들이 자연스럽게 연결된다. 입출력 계약은 예측 가능성을 만든다. 프롬프트 설계는 제어 평면을 다듬는다. 컨텍스트 엔지니어링은 모델이 볼 정보를 관리한다. 도구와 권한 설계는 안전한 자율성을 만든다. 평가와 관측은 시스템을 운영 가능한 제품으로 바꾼다.

에이전트는 모델이 아니라 시스템이다. 하네스는 그 시스템이 실제 세계에서 안전하고 반복 가능하게 작동하도록 만드는 구조다.