하네스 엔지니어링으로 완성하는 에이전틱 AI

모델을 바꿔도 남는 문제는 코드로 통제해야 합니다

모델은 API 한 줄로 누구나 쓸 수 있지만, 툴 호출이 같은 자리를 반복하거나 대화가 길어지면서 맥락이 무너지거나 외부 문서에 섞인 지시를 따르는 문제는 모델을 바꿔도 남습니다. 이런 문제는 모델을 코드로 감싸고 제어하는 하네스 엔지니어링으로 풀어야 하고, 최근 개발 현장에서 이 키워드가 주목받는 이유도 여기에 있습니다.
이 책은 에이전트를 잘 시키는 법보다 오류 없이 동작하게 만드는 법에서 출발합니다. 프롬프트를 다듬는 데서 그치지 않고, 에이전트가 실패하는 지점을 코드 단계에서 막는 방법을 다룹니다. 프레임워크 없이 현재의 에이전트 프로젝트의 기본이 되는 ReAct를 직접 구현합니다. 툴 사용 기반과 JSON 기반 두 방식으로 만든 뒤 랭그래프로 옮기기 때문에, 프레임워크가 대신해 주는 일이 무엇인지 확인할 수 있습니다. 이 과정을 거치면 새 도구가 나와도 적용할 수 있는 설계 기준을 얻게 됩니다.

PART 1 에이전트의 핵심 원리

CHAPTER 1 AI 에이전트의 시대
1.1 챗봇, RAG, 에이전트
1.2 에이전트 도입에 적합한 문제
1.3 에이전트의 동작 원리 ReAct
1.4 핵심 구성 요소 LLM, 메모리, 툴
1.5 하네스 엔지니어링
1.6 클로드 코드의 클라이언트 구조
1.7 실습을 위한 준비: 에이전트 개발 환경 구성

CHAPTER 2 툴 사용
2.1 툴 사용의 요청·실행·결과 전달 흐름
2.2 날씨 API를 호출하는 첫 번째 에이전트
2.3 여러 툴을 조합하는 멀티 툴 에이전트
2.4 툴 설계 가이드라인과 스키마 작성법
2.5 MCP vs CLI: 툴을 사용하는 두 가지 방식
2.6 자주 발생하는 오류와 해결 방법

CHAPTER 3 ReAct 패턴 구현
3.1 ReAct 루프 이해
3.2 툴 사용 기반 ReAct 에이전트 구현
3.3 툴 사용 없이 JSON으로 구현하는 ReAct
3.4 랭그래프 기반 ReAct 에이전트 구현
3.5 무한 루프 방지와 탈출 조건 설정

CHAPTER 4 메모리 시스템 구축
4.1 메모리
4.2 단기 메모리: 대화 목록 관리
4.3 요약 메모리 구현
4.4 벡터 DB 기반 장기 메모리 에이전트
4.5 메모리 압축 전략
4.6 체크포인터를 이용한 상태 저장

CHAPTER 5 컨텍스트와 하네스 엔지니어링
5.1 에이전트 컨텍스트의 구성과 관리
5.2 하네스 엔지니어링의 개념과 필요성
5.3 입력 검증: 전처리
5.4 구조화된 출력: 신뢰할 수 있는 응답
5.5 가드레일
5.6 클로드 코드 유출로 본 하네스
5.7 하네스 위치를 결정하는 일반적인 기준

PART 2 에이전트 확장하기

CHAPTER 6 RAG + 에이전트 결합
6.1 외부 지식과 최신 정보를 위한 RAG
6.2 튜토리얼: RAG 파이프라인 구축
6.3 RAG 품질 개선 방법
6.4 튜토리얼: 에이전틱 RAG 구현
6.5 그래프 RAG: 구조화된 청킹과 온톨로지
6.6 하이브리드 RAG

CHAPTER 7 랭그래프 기반 에이전트 워크플로
7.1 랭체인과 랭그래프의 역할
7.2 StateGraph 기반 워크플로 구축
7.3 조건부 라우팅과 툴 통합
7.4 휴먼 인 더 루프: 실행 전 사용자 승인
7.5 스트리밍: 실시간 진행 상황 모니터링
7.6 상태 확장: 커스텀 필드 추가

CHAPTER 8 멀티 에이전트 오케스트레이션
8.1 멀티 에이전트의 상태 관리
8.2 슈퍼바이저 패턴
8.3 핸드오프 패턴
8.4 계층형 패턴
8.5 안전한 상태 관리

PART 3 실전 프로젝트

CHAPTER 9 프로젝트: 출근하는 증권맨(정보 워크플로 에이전트)
9.1 시나리오 작성
9.2 설계: 지표 수집 → 종목 점검 → 뉴스 수집 → 브리핑 작성 → 전송
9.3 성공, 실패 기준 정의
9.4 툴 준비: 시장 데이터, 뉴스, 포맷터, 카카오톡/슬랙
9.5 랭그래프 상태 그래프 구축과 노드별 구현
9.6 실행과 디버깅: 데이터 누락, API 실패, 빈 결과를 다루는 법
9.7 운영: 매일 아침 자동 실행과 알림 채널 연동
9.8 평가: 로그 분석으로 보는 브리핑 품질과 개선 지점
9.9 전체 코드와 확장 아이디어

CHAPTER 10 프로젝트: 끈질긴 주니어 데이터 분석가(자기수정 에이전트)
10.1 시나리오 작성
10.2 설계: 생성 → 실행 → 해석 → 자기수정으로 종료되는 루프
10.3 데이터/실행 환경: DuckDB와 영속 커널
10.4 계층별 자기수정 구현
10.5 휴먼 인 더 루프: 위험한 작업 전 사용자 승인 게이트
10.6 날씨 API를 활용한 분석 보강
10.7 랭그래프 통합과 실행
10.8 평가: 정확도, 재시도 횟수, 첫 시도 성공률
10.9 전체 코드와 확장 아이디어

CHAPTER 11 프로젝트: 부탁을 듣는 집사 로봇(멀티모달 에이전트)
11.1 시나리오
11.2 설계: 비전 인지 → 계획 → 행동 → 재인지 루프
11.3 사전 준비
11.4 헤드리스 렌더링과 스모크 테스트
11.5 Space와 Action: 로봇의 공간·행동 정의
11.6 Perception: VLM 입력을 위한 카메라 이미지 최적화
11.7 Planner와 Executor: 명령 분해와 액션 실행
11.8 랭그래프 통합: 인지·계획·행동 루프와 종료 조건
11.9 실행 시나리오: 단순 명령에서 복합/모호한 명령으로
11.10 실패와 복구: 객체 미발견, 물리 실패, 계획 오류 대응
11.11 평가: 작업 성공률, 단계 효율, 복구 횟수
11.12 전체 코드와 확장 아이디어

PART 4 프로덕션과 운영

CHAPTER 12 하네스 보안: 안전성과 가드레일
12.1 웹 보안과 다른 에이전트 보안의 공격면
12.2 프롬프트 인젝션 방어(LLM01)
12.3 입출력 검증 레이어 설계(LLM02/LLM05)
12.4 실행 차단 및 예외 처리(LLM06)
12.5 샌드박스 런타임 격리(LLM10)
12.6 통합: 가드레일을 갖춘 에이전트

CHAPTER 13 비용과 보안을 위한 오픈소스 LLM 서빙
13.1 상용 API의 한계: 비용 폭탄과 데이터 유출
13.2 vLLM 아키텍처와 PagedAttention 원리
13.3 튜토리얼: RTX 3090 기반 Qwen2.5·Llama 3.1 서빙
13.4 API 호환성을 활용한 로컬 에이전트 전환
13.5 에이전트 속도 극대화를 위한 프리픽스 캐싱 활성화

CHAPTER 14 배포와 운영
14.1 요청형 에이전트 서비스 배포의 필요성
14.2 FastAPI로 에이전트 API 서버 구축
14.3 튜토리얼: AWS Lambda 서버리스 배포
14.4 관측성과 비용 모니터링

마치면서
찾아보기

고돈호 병역특례로 개발자 경력을 시작했다. 전자정부 전자민원 시스템 개발에 참여했으며, 전자정부 고도화 사업에서는 SA·TA로 근무했다. 삼성전자 GAPS, 외환은행 PMS, SKT 망 연동 테스트 시스템 등 대규모 엔터프라이즈 시스템 개발에 참여했으며, 삼성전자 갤럭시 시리즈 프로모션 앱 개발을 비롯해 모바일 개발자로도 일했다.
2018년부터 AI 개발 분야로 전향해 FaceNet 기반 안면 인식 출입 통제 시스템과 자연어 처리 기반 증상 자가 진단 시스템을 개발했으며, 2024년에는 개발한 모델이 허깅페이스(Hugging Face)의 글로벌 및 한국어 LLM 리더보드에서 1위에 올랐다. 현재는 HyperAgents 기반 자기 개선 에이전트를 개발하고 있다.