하네스란 무엇인가 — 텍스트만 뱉는 AI가 파일을 고치고 검색을 하는 트릭
AI 모델은 텍스트를 입력받아 텍스트를 출력한다. 그게 전부다. 그런데 AI 에이전트는 파일을 읽고, 명령어를 실행하고, 웹을 검색한다. 이 간극을 메우는 소프트웨어 층이 하네스(harness)다.
에이전트라는 말이 마법처럼 들린다면 이 글이 그 마법을 해체한다. 모델과 에이전트의 차이, 도구 호출의 실체, 그리고 왜 요즘 AI 경쟁의 무게중심이 이 레이어로 옮겨 가는지까지. AI 동작원리 시리즈 7편이자 마지막 기초편이다.
도구 호출의 실체는 '약속된 형식의 텍스트'
모델이 파일을 읽는 과정을 분해하면 이렇다.
1. 하네스가 시스템 프롬프트에 도구 목록을 적어 준다 "너는 Read(파일경로), Bash(명령어) 도구를 쓸 수 있다" 2. 모델 출력: Read(file="notes/2026-06-10.md") ← 그냥 텍스트다 3. 하네스가 그 텍스트를 파싱해서 실제로 파일을 읽는다 4. 읽은 내용을 다음 호출의 입력에 끼워 넣는다 5. 모델이 그 내용을 보고 다음 행동을 정한다 → 2번으로 반복
모델은 단 한 순간도 파일 시스템을 만지지 않는다. 도구를 부르고 싶다는 의사를 약속된 형식의 텍스트로 표현할 뿐이고, 실행은 전부 하네스가 한다. 데이터베이스 비유로 하면 모델은 쿼리문을 작성하는 쪽이고, 실행하고 결과를 가져오는 쪽은 하네스다.
에이전트 루프: 반복이 자율성을 만든다
위 과정의 2~5번 반복을 에이전트 루프(agentic loop)라고 부른다. 목표를 주면 모델이 도구 호출과 결과 확인을 거듭하며 스스로 일을 진행하는 것처럼 보이는 이유가 이 루프의 전부다.
Anthropic의 Building effective agents 가이드는 이 지점에서 유용한 구분을 한다. 미리 짠 코드 경로대로 모델을 부르는 건 워크플로우(workflow), 모델이 스스로 다음 도구와 순서를 정하는 게 에이전트(agent)다. 에이전트의 강점은 매 단계 도구 실행 결과라는 현실 피드백을 받아 경로를 수정한다는 데 있다.
내 블로그 파이프라인이 좋은 예다. "초안을 변환해서 발행 준비를 해 줘"라고 하면, 에이전트는 파일을 읽고, 변환 스크립트를 돌리고, 에러가 나면 메시지를 읽고 고쳐서 재시도한다. 각 단계는 평범한 도구 호출이지만 루프가 이어지니 일 맡길 만한 동료처럼 움직인다. 그 실전 기록은 블로그 자동화 실전기에 있다.
하네스의 부품들
Claude Code 같은 에이전트 도구를 열어 보면 하네스는 대략 이런 부품으로 구성된다.
| 부품 | 역할 |
|---|---|
| 시스템 프롬프트 | 모델의 정체성, 규칙, 사용 가능한 도구 목록 |
| 도구(Tools) | 파일 읽기/쓰기, 셸 명령, 웹 검색 등 실행 가능한 함수 |
| MCP 서버 | 외부 서비스(노션, DB, 지도 등)를 표준 규격의 도구로 연결 |
| 메모리 | 매 호출 컨텍스트에 주입되는 영속 정보 |
| 권한 관리 | 어떤 도구를 자동 허용하고 어떤 건 사람 승인을 받나 |
| 세션 관리 | 대화가 길어지면 요약·압축으로 컨텍스트를 관리 |
같은 모델이라도 하네스가 다르면 전혀 다른 도구가 된다. 챗봇과 코딩 에이전트의 차이는 모델 차이가 아니라 대부분 이 레이어 차이다. MCP는 외부 연결의 표준 규격인데, 공식 사이트의 비유를 빌리면 "AI계의 USB-C 포트"다. 실전 연동은 MCP 서버 연동 가이드에 따로 썼다.
하네스가 무너지는 지점들
에이전트를 몇 달 굴리면 실패도 패턴으로 보인다. 대부분 모델보다 하네스 설계의 문제다.
도구 호출 형식 오류. 모델이 약속된 형식을 살짝 어겨서 파싱이 실패하는 경우인데, 좋은 하네스는 오류 메시지를 모델에게 돌려줘 재시도하게 만든다. 루프 폭주. 같은 실패를 반복하며 토큰만 태우는 상황이라 횟수 제한과 중단 조건이 필수다. 그리고 권한 사고. 파일 삭제나 외부 발행처럼 되돌리기 어려운 도구는 사람 승인을 끼워 넣는 게 정석이고, 나도 블로그 공개 발행만큼은 자동화에서 빼서 수동 확인으로 남겨 뒀다.
이 안전장치들 자체가 하네스의 일부다. 에이전트 신뢰성이라는 말의 실체는 결국 이 레이어가 얼마나 촘촘하냐는 얘기다.
레버리지는 모델이 아니라 하네스에 있다
모델의 가중치는 사용자가 못 바꾼다. 바꿀 수 있는 건 하네스 쪽 전부다. 어떤 도구를 붙이고, 어떤 규칙 문서를 주입하고, 어떤 작업을 루프에 맡길지.
2026년 들어 모델 발표마다 "에이전트 신뢰성"(도구 호출 정확도, 다단계 계획, 오류 복구)이 핵심 지표로 등장하는 것도 같은 흐름이다. 모델 지능의 격차가 줄어들수록 그 지능을 어떤 환경에 앉히느냐가 결과를 가른다. 개인 사용자 차원에서도 마찬가지라서, 나는 새 모델을 쫓는 시간보다 규칙 문서와 자동화 스크립트를 다듬는 시간이 생산성에 더 크게 돌아온다는 걸 반복해서 확인했다. 멀티에이전트 병렬화 같은 응용은 서브에이전트 가이드에서 다뤘다.
짚고 가는 용어
에이전트 관련 용어가 난립하는 시기라 이 시리즈 기준의 정의를 박아 둔다. 모델은 텍스트를 받아 텍스트를 내는 확률 함수. 하네스는 그 함수를 도구·메모리·권한으로 감싼 런타임. 에이전트는 하네스 위에서 루프를 도는 모델, 즉 "모델 + 하네스 + 반복"의 합이다.
시리즈를 닫으며
AI 동작원리 시리즈 일곱 편이 여기서 모인다. 모델은 ①다음 토큰을 ②토큰 단위로 예측하는 ③어텐션 기반 신경망이고, ④3단계 학습으로 빚어지며, ⑤확률적 생성이라 환각을 동반하고, ⑥기억 없이 매번 컨텍스트를 다시 읽으며, ⑦하네스가 그 함수를 에이전트로 만든다.
이 그림이 머리에 있으면 새 AI 제품이 나와도 "모델이 좋아진 건가, 하네스가 좋아진 건가"부터 가려 볼 수 있게 된다. 도구 선택의 소음에 덜 흔들리는 데 이만한 백신이 없다. 내용은 2026년 6월 기준이며, 인용한 공식 가이드와 문서를 따라가면 더 깊은 층이 나온다.
AI 동작원리 시리즈: ① 다음 토큰 예측 · ② 토큰과 요금 · ③ 어텐션 · ④ 학습 3단계 · ⑤ 환각과 샘플링 · ⑥ 컨텍스트 윈도우 · ⑦ 하네스(이 글)
댓글
댓글 쓰기