AI 에이전트에서 하네스(harness)는 모델이 도구를 쓰며 작업을 이어 가도록 연결하는 실행 구조, 가드레일(guardrail)은 입력·출력·행동이 정해진 정책을 따르는지 검사하고 제한하는 통제를 뜻한다. 하네스는 작업을 어떻게 진행할지에, 가드레일은 어떤 조건에서 진행을 허용할지에 초점이 있다.
두 용어는 실제 제품에서 자주 겹친다. 하네스 안에 도구 승인 기능이 들어갈 수 있고, 가드레일 도구가 대화 흐름까지 제어하기도 한다. 따라서 두 제품군 중 하나를 고르는 문제로만 접근하면 구성 요소의 책임을 놓치기 쉽다.
이 글은 AI 에이전트 문맥을 기준으로 두 개념의 특징, 함께 동작하는 방식, 혼동하기 쉬운 용어를 정리한다. 제품 기능은 2026년 10월 1일 확인한 공식 자료를 기준으로 하며, 고객 보고서 사례와 구성도는 설명을 위해 만든 설계 예시다.
1. 같은 모델도 작업을 진행하는 방식은 달라진다
“지난달 고객 문의를 분석해 보고서를 만들고 담당자에게 보내 줘”라는 요청을 생각해 보자. 언어 모델이 보고서 문장을 작성할 수 있다고 해서 곧바로 업무 전체가 완성되는 것은 아니다. 문의 데이터를 어디서 읽을지, 어떤 도구를 호출할지, 중간 결과를 어디에 보관할지, 전송이 성공했는지 확인하는 과정이 필요하다.
모델이 문의 검색이라는 도구 호출을 제안하면 실제 프로그램이 그 도구를 실행한다. 프로그램은 검색 결과를 다시 모델에 전달하고, 모델은 그 결과를 보고 다음 행동이나 최종 응답을 만든다. 이 반복을 에이전트 루프(agent loop)라고 부른다. Claude Agent SDK 공식 문서도 도구, 에이전트 루프, 컨텍스트 관리를 함께 제공하는 구조를 설명한다. Claude Agent SDK 개요
이때 컨텍스트는 모델이 현재 판단에 참고하는 정보다. 원래 요청, 대화 기록, 도구 사용법, 검색 결과가 여기에 들어간다. 모델이 한 번에 참고할 수 있는 정보량에는 한계가 있으므로, 긴 작업에서는 무엇을 남기고 무엇을 요약할지도 실행 구조의 일부가 된다.
하네스라는 표현은 이런 모델 주변의 작업 구조를 설명할 때 사용된다. 다만 모든 문서가 동일한 범위를 가리키지는 않는다. 어떤 문서에서는 모델 호출과 도구 실행을 잇는 반복 구조에 집중하고, 어떤 제품에서는 파일 관리, 기억, 승인, 하위 에이전트까지 묶은 실행 환경을 뜻한다.
따라서 “하네스를 도입했다”는 설명을 들으면 포함된 기능을 함께 확인하는 것이 좋다. 도구 실행만 제공하는지, 작업 중단 뒤 복구까지 제공하는지에 따라 실제 운영 범위가 달라진다.
2. 하네스가 맡는 일: 연결하고, 기억하고, 이어 간다
하네스의 핵심은 모델의 한 번짜리 응답을 여러 단계의 작업으로 연결하는 데 있다. 다음은 구현을 살펴볼 때 유용한 기능별 구분이다. 모든 하네스가 아래 항목을 전부 제공해야 한다는 규격은 아니다.
도구 실행과 다음 단계 연결
하네스는 모델에 사용할 수 있는 도구를 알려 주고, 모델이 요청한 도구의 이름과 인수를 실제 실행 코드에 연결한다. 실행 결과와 오류를 다음 모델 호출에 전달하는 역할도 맡는다. 작업이 끝났는지, 추가 호출이 필요한지, 반복을 중단할지는 애플리케이션과 하네스의 설계에 따라 결정된다.
보고서 사례에서는 검색 결과가 부족하면 다른 조건으로 다시 검색하고, 충분하면 요약으로 넘어갈 수 있다. 반대로 도구 오류가 계속 발생하면 정해 둔 재시도 횟수에서 멈추도록 구성할 수 있다. 이런 종료 조건이 없으면 같은 요청을 반복하며 시간과 비용을 쓸 수 있다.
작업 상태와 컨텍스트 관리
보고서 초안, 완료한 단계, 남은 단계, 도구 결과를 저장하면 작업을 이어 가기 쉬워진다. 하지만 저장했다는 사실과 다음 모델 호출에서 필요한 내용을 정확히 읽는다는 사실은 다르다. 저장 위치, 불러오는 시점, 요약에 남길 내용을 함께 설계해야 한다.
Anthropic의 장시간 작업 사례에서는 초기 환경을 구성하는 단계와 이후 점진적으로 작업하는 단계를 나누고, 진행 기록과 Git 이력, 기능 목록을 활용했다. 이는 컨텍스트가 바뀌어도 다음 세션이 현재 상태를 파악하도록 만드는 구체적인 하네스 설계 사례다. 모든 작업에 같은 파일 구성을 적용해야 한다는 뜻은 아니다. Effective harnesses for long-running agents
실행 환경과 관찰 지점 제공
파일 시스템, 코드 실행 환경, 사용자 승인, 하위 에이전트 연결도 하네스에 포함될 수 있다. 예를 들어 Deep Agents는 파일 시스템과 컨텍스트 관리, 하위 에이전트, 사람의 개입을 주요 기능으로 설명한다. Deep Agents 공식 개요
운영에서는 이 흐름을 추적할 기록도 필요하다. 어느 모델 호출이 어떤 도구 실행으로 이어졌는지, 실패한 단계는 어디인지 알 수 있어야 한다. 다만 실행 기록을 남기는 기능과 위험 행동을 실제로 차단하는 기능은 별도로 확인해야 한다. 로그에 “전송 시도”가 남았다는 것만으로 전송이 통제되었다고 판단할 수는 없다.
그림 1. 실행 구조와 정책 검사 지점을 함께 배치한 참조 설계. Deep Agents, NeMo Guardrails, Claude Agent SDK 권한 제어 공식 문서를 바탕으로 재구성. 특정 제품의 내부 구조를 그대로 나타낸 그림은 아니다.
3. 가드레일이 맡는 일: 검사하고, 결정하고, 적용한다
가드레일은 하나의 검사 방식이나 제품 이름에만 해당하지 않는다. 이 글에서는 애플리케이션의 정책을 실행 흐름에 적용하는 통제를 넓게 가리킨다. 제품에 따라 콘텐츠 검사만을 뜻하기도 하고, 도구 실행이나 대화 흐름 제어까지 포함하기도 한다.
예를 들어 개인정보가 포함된 입력을 수정하거나, 검색한 문서의 일부를 모델에 전달하지 않거나, 허용되지 않은 도구 호출을 막을 수 있다. 결과가 정해진 JSON 형식인지 확인하는 품질 검사도 가드레일이라는 이름으로 묶이는 경우가 있다. 따라서 “보안 가드레일”과 “출력 형식 가드레일”이 동일한 위험을 다룬다고 볼 수는 없다.
NeMo Guardrails는 입력, 대화, 검색 결과, 실행, 출력의 다섯 유형을 설명한다. 특히 실행 가드레일은 사용자 정의 도구의 입력과 출력에 적용되고, 대화 가드레일은 다음 동작이나 응답 흐름에 영향을 준다. 가드레일을 최종 답변의 금칙어 필터로만 이해하면 이런 범위를 놓치게 된다. NeMo Guardrails의 유형
탐지 결과가 실제 실행에 반영되어야 한다
보고서에서 민감정보를 발견하는 것은 탐지다. 그 보고서를 외부에 보내도 되는지 정하는 것은 정책 판단이다. 전송 도구를 실행하지 않거나 승인 대기로 바꾸는 것은 집행(enforcement)이다. 세 역할을 한 모듈이 수행할 수도 있고 여러 서비스가 나눌 수도 있다.
예를 들어 개인정보 탐지기가 민감정보 있음을 반환했는데 전송 코드가 그 결과를 무시하면, 검사는 수행됐지만 유출 방지 정책은 적용되지 않은 것이다. 반대로 탐지 결과를 받아 마스킹한 뒤 다시 검사하고, 통과한 결과만 전송하도록 만들면 탐지와 집행이 연결된다.
규칙과 모델 판단은 다른 특성을 가진다
허용된 도구 이름인지, 요청 금액이 한도 이내인지, 필수 필드가 있는지는 코드 규칙으로 검사할 수 있다. 문맥상 민감한 요청인지, 특정 업무 범위를 벗어났는지는 분류 모델이나 LLM을 활용할 수 있다. 이 둘을 조합하는 설계도 가능하다.
규칙 검사는 작성된 조건에 대해서 일관되게 동작하지만 조건이 빠진 경우까지 해결하지는 않는다. 모델을 사용하는 검사는 문맥을 다룰 수 있지만 오탐과 미탐을 측정해야 한다. 오탐은 정상 요청을 잘못 막는 것이고, 미탐은 막아야 할 요청을 통과시키는 것이다. 어느 방식이든 이름만으로 보호 수준을 판단하기보다 검사 대상과 실패 시 동작을 확인해야 한다.
4. 둘의 차이는 ‘업무 진행’과 ‘정책 적용’에서 드러난다
다음 표는 여러 구현을 이해하기 위한 역할 중심의 비교다. 개별 제품은 양쪽 기능을 함께 제공할 수 있다.
차이를 구체적으로 보려면 고객 보고서 사례를 다시 따라가면 된다. 다음 과정은 특정 SDK의 기본 동작이 아니라 설명을 위한 설계 예시다.
- 요청 접수: 애플리케이션이 사용자와 업무 범위를 확인하고, 입력 검사 결과를 받은 뒤 작업을 시작한다.
- 자료 검색: 하네스가 검색 도구를 실행한다. 검색 서비스는 사용자가 볼 수 있는 자료만 반환하고, 필요한 경우 반환된 내용에도 검사를 적용한다.
- 보고서 작성: 하네스가 허용된 자료를 모델에 전달한다. 생성된 초안에서 민감정보와 필요한 출력 조건을 검사한다.
- 전송 요청 검토: 모델이 제안한 수신 대상과 첨부 내용을 실제 전송 직전에 검증한다. 정책상 필요한 경우 사용자가 구체적인 전송 내용을 승인하도록 한다.
- 실행과 완료 확인: 허용된 요청만 전송 도구를 실행하고, 도구 결과를 기록한다. 실행에 실패했다면 성공했다고 응답하지 않는다.
여기서 하네스는 다섯 단계를 연결한다. 가드레일은 그 사이에 있는 검사와 제한을 담당한다. 전송 서비스의 접근 권한 검사는 그 서비스가 책임져야 하는 별도의 통제다.
그림 2. 외부 전송 전에 검사 결과를 적용하는 설계 예시. NeMo Guardrails와 Claude Agent SDK 권한 제어 공식 문서를 바탕으로 재구성. 승인 여부와 장애 시 처리 방식은 업무 정책에 맞게 정한다.
최종 답변을 막는 것과 도구 실행을 막는 것은 다르다
보고서를 이미 전송한 뒤 “전송했습니다”라는 답변만 차단해도 외부 전송은 되돌아오지 않는다. 데이터 변경이나 메시지 전송처럼 실제 시스템 상태를 바꾸는 행동은 행동이 실행되기 전에 필요한 판단이 끝나야 한다.
성능을 위해 검사와 생성을 동시에 실행하는 설계라면, 검사 완료 전에 어떤 작업까지 진행될 수 있는지 확인해야 한다. 텍스트를 임시로 생성하는 것과 외부 API의 변경 작업을 확정하는 것은 영향이 다르다. 스트리밍 응답도 검사가 끝나기 전에 사용자에게 전달된 내용은 이후 차단으로 회수할 수 없다.
실제 적용에서는 훅이나 콜백의 이름보다 호출 순서가 중요하다. Claude Agent SDK의 권한 문서는 도구 실행 전에 훅과 권한 규칙 등을 평가하는 순서를 설명하며, 앞 단계에서 결정된 호출이 특정 콜백까지 도달하지 않을 수 있음을 보여 준다. 설치한 버전의 문서에서 어떤 경로가 검사를 거치는지를 확인해야 한다. 권한 평가 순서
5. 용어가 혼동되는 다섯 가지 지점
하네스가 항상 에이전트 실행기를 뜻하지는 않는다
소프트웨어에서 하네스는 어떤 대상을 실행하거나 시험하기 위해 주변을 연결해 둔 구조라는 뜻으로도 쓰인다. 대표적으로 평가 하네스(evaluation harness)는 데이터셋과 모델 실행, 점수 계산을 연결하는 평가 도구다. EleutherAI의 lm-evaluation-harness도 언어 모델 평가 프레임워크다. 이름에 harness가 있다는 이유로 업무용 에이전트 실행 제품으로 분류할 수는 없다. EleutherAI 공식 저장소
프레임워크·런타임·하네스는 경계가 겹친다
프레임워크는 개발에 쓰는 구성 요소와 추상화를, 런타임은 상태를 유지하며 실행하는 기반을, 하네스는 작업에 필요한 도구와 실행 방식을 갖춘 구성을 강조한다고 이해하면 편하다. 다만 이것은 문서를 읽기 위한 구분이며 모든 제품에 적용되는 고정된 계층도는 아니다.
LangChain은 자사 문서에서 LangChain을 프레임워크, LangGraph를 런타임, Deep Agents를 하네스로 구분한다. 동시에 하네스를 여러 기능이 내장된 프레임워크로 설명한다. 이처럼 한 제품이 더 넓은 의미의 다른 범주에도 들어갈 수 있다. Runtimes, frameworks, and harnesses
가드레일은 안전장치의 목적을 말할 때도, 특정 기능을 말할 때도 쓰인다
“가드레일이 있다”는 말만으로 개인정보 보호, 환각 감소, 도구 권한, 출력 형식이 모두 통제된다고 해석하기는 어렵다. JSON 형식 검사를 통과한 응답에도 틀린 사실이 들어갈 수 있고, 유해 표현이 없는 도구 요청도 권한 없는 데이터에 접근할 수 있다.
문서에서는 가능하면 “출력의 개인정보 검사”, “전송 도구의 수신 대상 제한”처럼 대상과 조건을 붙인 표현을 쓰는 편이 명확하다. 가드레일이라는 상위 이름 아래 실제로 무엇을 구현했는지가 드러난다.
하네스의 승인 기능도 가드레일 역할을 할 수 있다
하네스가 도구 호출 전 사용자 승인을 받는 기능을 제공한다면, 실행 구조의 한 기능이 정책 통제 역할도 수행한다. 이를 하네스 기능이라고 부르는 것과 가드레일이라고 설명하는 것은 동시에 가능하다.
반대로 NeMo Guardrails처럼 대화 흐름과 동작 선택까지 다루는 도구도 있다. 따라서 하네스는 오직 실행만, 가드레일은 오직 문자열 필터링만 한다고 선을 긋기보다, 어떤 구성 요소가 어느 단계의 결정을 맡는지 확인하는 편이 정확하다.
샌드박스와 권한 시스템은 별도로 봐야 한다
샌드박스는 실행 코드가 접근할 수 있는 파일이나 네트워크 같은 환경 범위를 제한하는 격리 수단이다. 가드레일은 요청이나 결과가 정책을 만족하는지 검사하는 역할을 맡을 수 있다. 두 기능을 함께 사용하면 서로 다른 경계를 다룰 수 있지만, 하나의 존재만으로 다른 기능까지 있다고 추정해서는 안 된다.
예를 들어 보고서 작성 코드가 격리된 환경에서 실행돼도 전송 API에 과도한 권한이 부여돼 있으면 별도의 문제가 남는다. 반대로 전송 문구를 검사하더라도 실행 프로세스의 파일 접근 범위가 자동으로 줄어드는 것은 아니다.
6. 실제 설계에서는 제품 이름보다 책임을 적는다
구성도를 그릴 때 “하네스 + 가드레일”이라는 두 상자만으로는 충분한 정보가 전달되지 않는다. 보고서 사례라면 다음처럼 검사 대상과 실행 책임을 함께 적을 수 있다.
- 자료 접근: 검색 API가 사용자 권한에 맞는 문서만 반환한다. 반환 후 마스킹으로 접근 권한 검사를 대신하지 않는다.
- 생성 내용: 초안을 검사하고, 정책에 따라 수정·거부·검토 대기로 보낸다. 수정한 결과도 필요한 조건을 다시 확인한다.
- 도구 실행: 전송 직전에 실제 수신 대상과 첨부물을 검증한다. 승인된 내용과 실행할 내용이 달라졌다면 승인을 다시 평가한다.
- 작업 관리: 시간·비용·반복 횟수의 한도를 두고, 전송처럼 중복 실행이 문제인 작업은 재시도 시 중복 처리 여부를 확인한다.
- 운영 기록: 적용한 정책 버전, 검사 결과, 실제 실행 여부를 연결해 남긴다. 로그에도 개인정보와 비밀정보를 불필요하게 기록하지 않는다.
이 목록은 특정 제품의 제공 기능을 주장하는 것이 아니라, 책임을 나눌 때 사용할 수 있는 설계 항목이다. 팀의 시스템에서는 어느 항목을 하네스가 맡고 어느 항목을 API 서버나 정책 서비스가 맡는지 표시하면 된다.
검증도 두 방향으로 나누면 명확하다. 하네스는 작업을 끝낼 수 있는지, 중단 후 올바르게 이어 가는지, 도구 실패를 처리하는지 살펴본다. 가드레일은 정상 요청이 통과하는지, 금지된 요청이 실제 실행 전에 멈추는지, 검사 서비스가 응답하지 않을 때 어떤 일이 생기는지 살펴본다.
외부 전송 같은 중요한 동작은 검사 결과를 얻지 못한 상태에서 대기하거나 중단하도록 설계할 수 있다. 반면 영향이 작은 기능은 다른 장애 정책을 선택할 수 있다. 이 선택을 서비스별로 명시해야 장애가 발생했을 때 통과와 차단 중 어느 동작이 나올지 예측할 수 있다.
7. 정리: 하네스는 진행 구조, 가드레일은 정책 통제
하네스는 모델, 도구, 컨텍스트와 작업 상태를 연결해 에이전트가 일을 이어 가게 한다. 가드레일은 필요한 지점에서 입력·출력·행동을 검사하고 정책을 적용한다. 실제 시스템에서는 하네스가 가드레일을 포함할 수 있고, 별도의 정책 서비스나 API가 일부 통제를 담당할 수도 있다.
용어가 애매할 때는 세 가지를 확인하면 된다. 무엇을 실행하는 구조인가, 무엇을 검사하는 통제인가, 검사 결과를 누가 실제 행동에 반영하는가. 이 세 질문에 답하면 기능이 겹치는 제품도 책임과 경계에 따라 비교할 수 있다.
좋은 설계 문서는 하네스나 가드레일이라는 이름에서 설명을 끝내지 않는다. 작업을 이어 가는 경로와 허용되지 않은 행동을 멈추는 지점을 함께 보여 준다. 그 구조가 보여야 기능, 운영 안정성, 보호 범위를 같은 그림 위에서 판단할 수 있다.
'일반IT > AI' 카테고리의 다른 글
| GPT‑6.1 Sol로 바꿔야 할까? 6 Sol·Astra와 비교할 기준 (0) | 2026.10.04 |
|---|---|
| AWS Bedrock Guardrails의 HIGH, 정확히 무엇을 뜻할까? (0) | 2026.10.04 |
| ChatGPT Pro 200 사용량 절반 축소, 무엇이 달라지나? (0) | 2026.09.30 |
| LLM vs Jev, 무엇을 맡겨야 할까? 생성·판단·비용으로 비교하기 (0) | 2026.09.28 |
| LLM 시스템 아키텍처: 프론트엔드부터 RAG·에이전트·공급망까지 (0) | 2026.09.28 |
