스프링 AI 2.0으로 배우는 AI 에이전트 개발 완벽 가이드

허제민

삼성SDS에서 클라우드와 데이터 분석 플랫폼을 개발했고, SK플래닛에서 대규모 모니터링, A/B 테스트, 챗봇 플랫폼을 개발하고 운영해 온 AI 플랫폼 엔지니어입니다. 스프링 AI 오픈소스 프로젝트에 벡터 저장소 모듈을 중심으로 기여했으며, 스프링 AI 커뮤니티 인큐베이팅 프로젝트인 Spring AI Playground를 만들고 리드 메인테이너로 활동하고 있습니다. 스프링 AI 기반 엔터프라이즈 AI 에이전트 시스템의 설계와 구현, 스프링 AI 강의, 기술 집필에 집중하고 있습니다.

• ▣ 01장: AI 에이전트, 새로운 패러다임의 시작
• 1.1 LLM을 넘어, 스스로 일하는 ‘에이전트’의 시대로
• 1.2 기업 환경에서의 AI 기술 도입
• __1.2.1 파이썬 중심의 AI 개발 생태계
• __1.2.2 자바 AI 개발 생태계의 전환: 새로운 가능성의 시작
• 1.3 스프링 AI 소개
• __1.3.1 스프링 AI의 목표
• __1.3.2 스프링 생태계에서 스프링 AI의 역할과 장점
• __1.3.3 스프링 AI의 진화: AI 통합의 1.0에서 에이전트의 2.0으로
• 1.4 이 책의 목표와 구성
• __1.4.1 자바 개발자를 위한 실용적인 AI 에이전트 개발 가이드
•  
• ▣ 02장: 스프링 AI 프레임워크
• 2.1 주요 특징과 AI 모델 API 설계 방향
• __2.1.1 주요 특징
• __2.1.2 AI Model API 설계
• 2.2 개발 환경 구축
• __2.2.1 올라마 설치 및 로컬 환경 구성
• __2.2.2 프로젝트 기본 설정
• __2.2.3 간단한 AI 애플리케이션 개발
• 2.3 ChatModel과 ChatClient
• __2.3.1 역할의 분리: 드라이버와 클라이언트
• __2.3.2 ChatModel: 통신 방식과 응답 데이터
• __2.3.3 ChatResponse와 응답 메타데이터
• __2.3.4 ChatClient API 활용
• __2.3.5 ChatClient의 고급 기능과 AI 에이전트로의 확장
• 2.4 프롬프트 엔지니어링
• __2.4.1 Prompt 설계 철학
• __2.4.2 Message API와 역할 기반 설계
• __2.4.3 PromptTemplate: 동적 프롬프트 관리
• __2.4.4 고급 템플릿 기법
• __2.4.5 효과적인 프롬프트 작성
• __2.4.6 ChatOptions 활용
• __2.4.7 모델 전용 옵션 활용과 설정 전략
• __2.4.8 다양한 프롬프트 엔지니어링 기법
• 2.5 토큰
• __2.5.1 토큰의 구조와 개발자의 관점
• __2.5.2 한국어 토큰 효율성의 진화
• __2.5.3 하이브리드 프롬프트 전략
• 2.6 구조화한 출력
• __2.6.1 프레임워크 주도 프롬프트 엔지니어링
• __2.6.2 구조화한 출력의 아키텍처
• __2.6.3 StructuredOutputConverter 구현체
• __2.6.4 다양한 StructuredOutputConverter 구현체 사용 방법
• __2.6.5 네이티브 구조화한 출력
• 2.7 대화 메모리와 컨텍스트 관리
• __2.7.1 ChatMemory 인터페이스와 기본 구현체
• __2.7.2 ChatMemoryRepository 저장소 유형별 상세 분석
• __2.7.3 ChatMemoryRepository의 유연한 저장소 전환
• __2.7.4 단기 기억과 장기 기억의 연동 패턴
• __2.7.5 수동 단기 기억 관리
• 2.8 어드바이저 체인
• __2.8.1 어드바이저 API 클래스 구조
• __2.8.2 어드바이저 실행 흐름과 스택 구조
• __2.8.3 동기식 처리 vs 스트리밍 처리
• __2.8.4 어드바이저 구현과 내장 어드바이저
• __2.8.5 어드바이저 기반 제어: 차단과 대체
• __2.8.6 어드바이저 구현 원칙과 배치 전략
• __2.8.7 스프링 AI 어드바이저: 프레임워크의 코어와 확장성
• 2.9 AI 챗봇 CLI 프로젝트
• __2.9.1 CLI와 AI의 만남
• __2.9.2 프로젝트 구조 및 설정
• __2.9.3 단계별 챗 CLI 구현
• __2.9.4 최종 CLI 챗봇 개발
• __2.9.5 정리
•  
• ▣ 03장: 스프링 AI와 RAG
• 3.1 RAG 등장 배경과 아키텍처
• __3.1.1 LLM의 구조적 한계와 데이터 공백
• __3.1.2 데이터 공백을 채우는 기술: 파인 튜닝 vs 주입
• __3.1.3 스프링 AI의 RAG 아키텍처
• __3.1.4 ETL 파이프라인 프레임워크
• 3.2 ETL 파이프라인 DocumentReader 구현
• __3.2.1 텍스트 파일에서 추출
• __3.2.2 JSON에서 추출
• __3.2.3 PDF에서 추출
• __3.2.4 마크다운에서 추출
• __3.2.5 HTML에서 추출
• __3.2.6 범용 문서 추출
• __3.2.7 커스텀 DocumentReader 구현
• 3.3 ETL 파이프라인 DocumentTransformer 구현
• __3.3.1 문서 변환과 정제
• __3.3.2 메타데이터 포맷 통일
• __3.3.3 메타데이터에 키워드 추가
• __3.3.4 문맥 요약 추가
• __3.3.5 커스텀 DocumentTransformer 구현
• __3.3.6 DocumentTransformer 파이프라인 통합
• 3.4 ETL 파이프라인 DocumentWriter 구현
• __3.4.1 파일에 적재
• __3.4.2 커스텀 DocumentWriter 구현
• 3.5 임베딩 모델
• __3.5.1 임베딩의 개념과 작동 원리
• __3.5.2 EmbeddingModel API 구조
• __3.5.3 임베딩 모델 구동 방식: 클라우드와 로컬
• __3.5.4 CPU 기반 로컬 임베딩 모델 성능과 한글 지원 임베딩 모델
• 3.6 벡터 데이터베이스
• __3.6.1 VectorStore 인터페이스 상세
• __3.6.2 검색 요청(SearchRequest)
• __3.6.3 메타데이터 필터
• __3.6.4 벡터 데이터베이스 스키마
• __3.6.5 대량 문서의 배치 데이터 적재
• __3.6.6 벡터 데이터베이스의 데이터 생명 주기 관리(삭제와 수정)
• __3.6.7 다양한 벡터 데이터베이스
• __3.6.8 내장 인메모리 벡터 데이터베이스(SimpleVectorStore)
• 3.7 스프링 AI의 RAG 프레임워크
• __3.7.1 RAG의 진화와 패러다임
• __3.7.2 Naive RAG 구현
• __3.7.3 Advanced RAG 구현
• __3.7.4 모듈러 RAG를 구성하는 모듈
• __3.7.5 모듈러 RAG의 전처리 단계 구현
• __3.7.6 모듈러 RAG의 검색, 후처리, 생성 단계 구현
• __3.7.7 모듈러 RAG 오케스트레이션
• 3.8 RAG AI 챗봇 CLI 프로젝트
• __3.8.1 프로젝트 목표와 설정
• __3.8.2 오프라인 ETL 파이프라인 구현
• __3.8.3 런타임 RAG 파이프라인 구현
• __3.8.4 RAG CLI 챗봇 개발
•  
• ▣ 04장: 툴 호출
• 4.1 AI 모델의 툴 호출 환경
• __4.1.1 툴 호출의 등장: LLM이 현실 세계와 연결되다
• 4.2 툴 호출 설계
• __4.2.1 스프링 AI 툴 호출의 특징
• __4.2.2 툴 호출 진행 과정
• __4.2.3 툴 명세
• __4.2.4 툴 컨텍스트와 직접 반환
• __4.2.5 툴 호출 결과 변환
• 4.3 툴 구현
• __4.3.1 메서드를 툴로 구현하기
• __4.3.2 함수를 툴로 구현하기
• __4.3.3 툴 구현 방식 비교 및 선택
• __4.3.4 툴을 AI 모델에 전달하는 방법
• 4.4 툴 실행
• __4.4.1 ToolCallingManager API
• __4.4.2 DefaultToolCallingManager의 내부 구현
• __4.4.3 프레임워크-제어 툴 실행
• __4.4.4 어드바이저-제어 툴 실행
• __4.4.5 사용자가 제어하는 툴 실행
• 4.5 툴 지원 AI 챗봇 CLI 프로젝트
• __4.5.1 프로젝트 목표와 설정
• __4.5.2 단계별 툴 호출 CLI 구현
• __4.5.3 툴 지원 AI 챗봇 CLI 개발
•  
• ▣ 05장: 스프링 AI MCP
• 5.1 MCP 기본(호스트/클라이언트/서버, 프리미티브, 전송)
• __5.1.1 MCP 아키텍처
• __5.1.2 자바 MCP 스택 아키텍처
• __5.1.3 자바 MCP 클라이언트 서버 아키텍처
• __5.1.4 직접 툴 호출 vs MCP 툴 호출
• 5.2 스프링 AI MCP 클라이언트
• __5.2.1 MCP 클라이언트 부트 스타터
• __5.2.2 MCP 클라이언트 공통 설정
• __5.2.3 MCP 클라이언트 STDIO 설정
• __5.2.4 MCP 클라이언트 원격 서버 설정
• __5.2.5 MCP 클라이언트의 headers를 사용한 원격 서버 보안 설정
• __5.2.6 MCP 클라이언트 기능 구현
• __5.2.7 MCP 클라이언트 애너테이션
• 5.3 스프링 AI MCP 서버
• __5.3.1 MCP 서버 부트 스타터
• __5.3.2 MCP 서버 공통 설정
• __5.3.3 MCP 서버 프로토콜 설정
• __5.3.4 MCP 서버 툴 기능 구현
• __5.3.5 MCP 서버 다양한 기능 구현
• __5.3.6 MCP 서버 클라이언트 양방향 기능 구현
• __5.3.7 MCP 서버 애너테이션
• __5.3.8 MCP 서버 애너테이션 사용 툴 구현
• __5.3.9 MCP 서버 애너테이션 사용 툴 서버 유형별 구현
• __5.3.10 MCP 서버 애너테이션 사용 추가 기능 구현
• __5.3.11 MCP 서버 애너테이션 사용 추가 기능 서버 유형별 구현
• 5.4 스프링 AI MCP 보안
• __5.4.1 MCP 보안 환경
• __5.4.2 스프링 AI의 MCP 시큐리티
• __5.4.3 MCP 클라이언트 시큐리티 공통 설정
• __5.4.4 MCP 클라이언트 시큐리티 세부 구현
• __5.4.5 MCP 서버 시큐리티 구성
• __5.4.6 MCP 인가 서버 구성
• 5.5 MCP 기반 AI 챗봇 CLI 프로젝트
• __5.5.1 프로젝트 목표와 설정
• __5.5.2 단계별 MCP 서버 구현
• __5.5.3 단계별 MCP 클라이언트 구현
• __5.5.4 MCP 기반 AI 챗봇 CLI 구현
•  
• ▣ 06장: AI 에이전트
• 6.1 AI 에이전트와 실행 루프
• __6.1.1 워크플로와 자율 에이전트
• __6.1.2 워크플로 패턴
• __6.1.3 자율 에이전트
• __6.1.4 스프링 AI가 지원하는 자율 에이전트 개발
• __6.1.5 실용적 AI 에이전트 구현
• 6.2 컨텍스트 엔지니어링
• __6.2.1 프롬프트 엔지니어링에서 컨텍스트 엔지니어링으로
• __6.2.2 생각의 사슬의 프롬프트 설계와 추론 AI 모델
• __6.2.3 리액트: 에이전트 행동 방식
• __6.2.4 컨텍스트 엔지니어링을 사용하는 LLM과 에이전트 시스템
• 6.3 재귀적 어드바이저와 툴 루프 제어
• __6.3.1 툴 루프의 두 가지 방식
• __6.3.2 재귀적 어드바이저의 처리 흐름
• __6.3.3 ToolCallingAdvisor를 사용한 툴 루프 제어
• __6.3.4 ToolCallingAdvisor의 훅과 파라미터 증강
• __6.3.5 구조화한 출력 교정 루프
• 6.4 스프링 AI 에이전트 개발
• __6.4.1 AI 에이전트 서비스 구조: 클로드 코드, 코덱스, 오픈코드, 오픈클로
• __6.4.2 멀티 에이전트와 에이전트 연결 표준
• __6.4.3 스프링 AI 에이전트 아키텍처와 구현
• __6.4.4 사용자 개입 워크플로(HITL): MCP Elicitation을 통한 툴 사용 권한 제어
• __6.4.5 동적 툴 탐색
• 6.5 커뮤니티 지원으로 확장하는 스프링 AI 에이전트
• __6.5.1 범용 에이전트 스킬
• __6.5.2 가정 대신 질문하는 툴(AskUserQuestionTool)
• __6.5.3 작업 계획 작성 툴(TodoWriteTool)
• __6.5.4 멀티 에이전트 지원 하위 에이전트 오케스트레이션
• 6.6 엔터프라이즈 스프링 AI 에이전트 CLI 프로젝트
• __6.6.1 엔터프라이즈 스프링 AI 에이전트 시스템
• __6.6.2 엔터프라이즈 스프링 AI 에이전트 CLI 시스템 설계와 구현 계획
• __6.6.3 스프링 AI 에이전트 CLI 구현
• __6.6.4 MCP 서버 기반 스프링 AI 에이전트 능력 확장 구현
• __6.6.5 멀티 에이전트로 확장
• __6.6.6 메타 툴 기반 오케스트레이션 확장
• __6.6.7 통합과 관측 가능성
•  
• ▣ 부록
• A: 오픈AI API로 실습 환경 구성하기
• B: AI 평가로 응답 품질을 검증하고 에이전트 루프를 보강하기
• C: 외부 AI 에이전트에 연결하기
• D: 스프링 AI 플레이그라운드

• GitHub 저장소: https://github.com/JM-Lab/spring-ai-agent-book
• ZIP 형식으로 다운로드: https://github.com/JM-Lab/spring-ai-agent-book/archive/refs/heads/main.zip