콘텐츠로 이동

엔터프라이즈 AI 에이전트 시스템을 만드는 방법

설계는 4-티어 아키텍처로,
구현은 스프링 AI로

채널, 오케스트레이션, 능력, 파운데이션의 네 계층으로 역할을 나누고, 계층마다 필요한 기술을 스프링 AI 2.0으로 구현합니다. 도메인별 MCP 서버, 승인 게이트, 하위 에이전트, 관측 가능성까지 갖춘 에이전트 시스템을 책의 장 순서를 따라 완성해 갑니다.

4-티어 아키텍처 살펴보기 1장부터 읽기

AI 에이전트 서비스 4-티어 아키텍처

AI 에이전트 서비스 4-티어 아키텍처

한눈에 보는 요약: 티어마다 대응하는 스프링 AI 기술

  • T1 채널 (Channel)

    사용자와 만나는 접점입니다. 터미널 CLI, 웹, 네이티브 앱. 에이전트 코어와 분리돼 있어 채널만 바꿔 끼울 수 있습니다. 책의 예제는 모두 CLI 채널입니다.

    스프링 AI: ChatClient 스트리밍 응답, 사용자 개입(HITL) 표시

    ChatModel과 ChatClient, 2장 챗봇 CLI

  • T2 오케스트레이션 (Orchestration)

    메인 에이전트입니다. 추론하고 계획하고 툴을 고르고 루프를 제어합니다. 경쟁력은 모델이 아니라 여기, 계획과 제어와 상태 관리에 있습니다.

    스프링 AI: ChatClient, 어드바이저 체인, ToolCallingAdvisor, MessageChatMemoryAdvisor, ToolSearchToolCallingAdvisor

    재귀적 어드바이저와 툴 루프 제어

  • T3 능력 (Capability)

    에이전트가 쓰는 외부 능력입니다. 툴, MCP, 검색, 메모리. 로컬 메서드도, 같은 JVM의 하위 에이전트도, MCP로 연결된 원격 서버도 메인 에이전트에게는 모두 같은 툴입니다.

    스프링 AI: @Tool, MCP 클라이언트와 서버, TaskTool 하위 에이전트, 스킬, RAG

    툴 호출 설계, MCP 기본

  • T4 파운데이션 (Foundation)

    두 지능 계층이 사용하는 기반 자원입니다. 모델, 데이터, 인프라. 모델도 추론을 공급하는 기반 자원이므로 이 계층에 둡니다.

    스프링 AI: ChatModel, EmbeddingModel, VectorStore, ETL 파이프라인

    RAG 아키텍처와 ETL, 임베딩과 벡터 저장소

  • 횡단 횡단 관심사 (Cross-cutting)

    특정 티어가 아니라 전 계층의 공통 관심사입니다. 관측 가능성(Observability), 거버넌스와 사용자 개입(HITL), 보안과 샌드박스, 감사 로깅, 비용과 레이트 제어.

    스프링 AI: Micrometer 관측과 OTLP, MCP Elicitation 승인 게이트, MCP 시큐리티(OAuth2, JWT)

    MCP 보안, 승인 게이트

  • 표준 인터페이스: MCP

    오케스트레이션이 능력을 호출하는 경계입니다. 지금의 구현은 MCP 프로토콜입니다. 이 경계를 어디에 두느냐에 따라 클라이언트와 서버, 프로세스와 팀과 배포 단위가 나뉩니다.

    4-티어를 클라이언트와 서버로 배치하기

클라이언트와 서버로 나누어 배치하기

네 계층은 논리적인 구분이라 실제로 어떻게 배치할지는 시스템마다 다를 수 있습니다. 책에서는 사용자가 터미널에서 실행하는 CLI를 메인 에이전트로 두고, 업무 능력은 도메인별 MCP 서버로 나누어 배치합니다.

4-티어 아키텍처를 클라이언트와 서버로 배치한 스프링 AI 에이전트 CLI 시스템 설계

4-티어 아키텍처를 클라이언트와 서버로 배치한 설계

클라이언트인 CLI 프로세스에는 채널(T1)과 오케스트레이션(T2), 그리고 바로 실행하는 로컬 능력(T3)이 함께 들어갑니다. 재고 조회나 사내 문서 검색처럼 따로 운영하는 능력은 MCP 서버로 분리하고, 두 쪽은 Streamable HTTP 기반의 MCP로 연결합니다. 새로운 업무 능력이 필요해지면 메인 에이전트 코드는 그대로 두고 MCP 서버를 추가한 뒤 연결 정보만 등록하면 됩니다.

스프링 AI 에이전트 CLI 시스템의 구성

스프링 AI 컴포넌트로 옮긴 에이전트 CLI 시스템의 구성

이 설계를 스프링 AI 컴포넌트로 옮기면 위와 같은 구성이 됩니다. ChatClient와 어드바이저 체인이 오케스트레이션을 맡고, 로컬 @Tool과 커뮤니티 툴, 원격 MCP 서버의 툴이 모두 하나의 툴 인터페이스로 정리됩니다. 6장의 엔터프라이즈 에이전트 CLI 글에서 이 구성을 코드로 완성하고, 관측 가능성 글에서 전 계층의 추적을 켭니다. 그 앞의 글들은 이 그림에 들어가는 부품을 하나씩 다룹니다.

책의 장을 따라 읽기

책 「스프링 AI 2.0으로 배우는 AI 에이전트 개발 완벽 가이드」를 장 순서대로 따라가는 글입니다. 각 글은 그 장의 핵심 개념과 설명, 그리고 예제 저장소의 코드를 담습니다. 설계한 이유와 내부 구현, 실측 결과까지 깊이 보고 싶은 독자를 위해 글 끝에 책의 해당 절을 적어 두었습니다. 잘못된 곳을 발견하면 오류 제보 안내를 따라 알려 주세요.

책, 예제 저장소, 플레이그라운드

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

스프링 AI 2.0으로 배우는 AI 에이전트 개발 완벽 가이드
허제민 지음, 위키북스, 2026년 9월 17일 출간, 692쪽

이 사이트의 원전입니다. ChatClient부터 RAG, 툴 호출, MCP, 그리고 4-티어 아키텍처로 완성하는 엔터프라이즈 AI 에이전트까지, 스프링 AI 2.0 GA 기준으로 로컬 모델만으로 전부 실습합니다. 이 사이트가 핵심만 담는다면 책은 각 절의 설계 이유와 내부 구현과 실측까지 담습니다.

온라인 구매 책 소개

  • 예제 저장소

    장별 독립 Maven 프로젝트입니다. Java 21, Spring Boot 4, Spring AI 2.0.0 GA, 올라마 qwen3.5:4b와 bge-m3. 이 사이트의 코드 블록은 저장소 파일에서 그대로 가져옵니다.

    JM-Lab/spring-ai-agent-book

  • 스프링 AI 플레이그라운드

    이 책의 저자가 리드 메인테이너로 이끄는 별도의 오픈소스 프로젝트입니다. 스프링 AI 커뮤니티의 인큐베이팅 프로젝트이며, 스프링 AI로 만들고 바딘(Vaadin)으로 UI를 개발한 데스크톱 애플리케이션입니다. 툴 스튜디오, MCP 서버 연결과 인스펙터, 벡터 데이터베이스와 RAG, 에이전트 채팅, 관측 가능성 다섯 축을 한 화면에서 시험합니다. 이 책의 MCP 서버를 그대로 연결해 볼 수 있습니다(부록 D).

    플레이그라운드 소개, 다운로드, GitHub