에이전트 개발 실습서 — 소개와 로드맵¶
이 실습서는 설계 문서(00~05)를 실제 코드로 옮겨간 과정을 그대로 재현할 수 있게 기록한 것입니다. 각 장은 실제 개발이 진행된 순서이며, 빈 폴더에서 시작해 따라 하면 같은 결과물이 나옵니다.
- 대상 독자: Java/Spring 경험이 있고 Python·LangGraph는 처음인 개발자
- 다루는 범위: 에이전트(
agent/) 개발만. 설계 문서 작성이나 문서 사이트 구축은 다루지 않습니다 - 읽기 전에: 03 · 인터페이스 명세와 05 · 개발 계획서는 꼭 먼저 읽어주세요. 실습 중 계속 참조합니다
- 출발점이 고민이면: 0장 · 시작 전 진단에서 15분 설문으로 자기 수준을 재고, 어떤 개념 카드를 언제 읽을지 경로를 받으세요
각 장의 구성¶
모든 장은 같은 틀을 따릅니다:
- 목표 — 이 장이 끝나면 무엇이 되는가 (완료 기준)
- 따라하기 — 실행할 명령과 작성할 코드 전문
- 코드 해설 — 왜 이렇게 짰는지, Spring이라면 무엇에 해당하는지
- 동작 확인 — 직접 실행해서 눈으로 확인
- 완성 코드 전문 — 그 장이 다루는 파일들의 저장소 최종본 (접이식)
- 이 장에서 배운 것 — 요약
완성 코드 전문 블록은 저장소와 자동 동기화됩니다 — agent/scripts/refresh_guide_code.py 가 실제 파일에서 생성하고, 불일치는 tests/test_guide_sync.py 가 테스트 실패로 잡습니다. 따라서 빈 폴더에서 이 실습서만 보고 복붙해도 저장소와 같은 결과물이 나옵니다. 예외는 평가 스크립트(agent/scripts/ 4종)로, 09 · 평가 케이스셋이 단일 원본입니다.
로드맵¶
개발 계획서(05 §4)의 Step과 실습서 장의 대응입니다. 개발이 진행될 때마다 장이 추가됩니다.
| 장 | 내용 | 개발 Step | 상태 |
|---|---|---|---|
| 0장 · 시작 전 진단 | 개념 지도(68개), 진단 설문 20문항, 읽기 경로 | — | ✅ |
| 0장 부록 · 사전 개념 카드 | 신규 개념 카드 27장 + Spring 대응표 | — | ✅ |
| 1장 · 환경 준비 | uv, 프로젝트 초기화, 의존성 | Step 1 | ✅ |
| 2장 · 계약을 코드로 | DTO, 설정, 엔드포인트 뼈대 | Step 1 | ✅ |
| 3장 · 계약 테스트 | fixture 전략, pytest | Step 1 | ✅ |
| 4장 · LangGraph 그래프 | 4노드 그래프 + mock LLM | Step 2 | ✅ |
| 5장 · 실제 LLM 연동 | 프롬프트 v1, 방어 계층, 삽질 기록 3종 | Step 3 | ✅ |
| 6장 · 멀티턴과 Redis | 체크포인터, 서수 참조, 삽질 3종 | Step 4 | ✅ |
| 7장 · 예외 흐름 완성 | 멱등성, 실패의 분류, 가드레일 3층 | Step 5 | ✅ |
| 7.5장 · 방어 계층 | 평가가 찾은 구멍을 결정적 코드로 — PII·입력상한·유출필터·서수가드 | Step 5 후 하드닝 | ✅ |
| 8장 · WAS 시뮬레이터 | 브라우저 채팅 화면으로 연동 리허설 | Step 6 사전 | ✅ |
| 9장 · 연동과 배포 | 사내 반입, WAS 실연동, 배포 | Step 6~7 | 예정 (Q3·Q4·Q9 대기) |
| 부록 A · 테스트와 디버깅 | pytest 사용법, 브레이크포인트 3가지 방법 | — | ✅ |
| 부록 B · 브레이크포인트 투어 | Step별 흐름을 디버거로 따라가기 (투어 1~5) | Step 1~4 | ✅ |
| 부록 C · 실제 LLM 대화 기록 | 실제 프롬프트·응답 스냅샷 (오염 사례 포함) | Step 3 | ✅ |