How to build enterprise AI agent systems
Design with a 4-tier architecture,
build with Spring AI¶
Divide the system into four tiers: Channel, Orchestration, Capability, and Foundation. Then build what each tier needs with Spring AI 2.0. Following the book's chapters, you put together an agent system with domain-specific MCP servers, approval gates, subagents, and observability.
Explore the 4-tier architecture Start with Chapter 1
At a glance: Spring AI technologies for each tier¶
-
T1 Channel
Where users meet the agent: a terminal CLI, the web, or a native app. Because the channel is separate from the agent core, you can swap the channel alone. Every example in the book uses a CLI channel.
Spring AI:
ChatClientstreaming responses, showing human-in-the-loop (HITL) requests -
T2 Orchestration
The main agent. It reasons, plans, picks tools, and controls the loop. The competitive edge is not the model but this tier: planning, control, and state management.
Spring AI:
ChatClient, the advisor chain,ToolCallingAdvisor,MessageChatMemoryAdvisor,ToolSearchToolCallingAdvisor -
T3 Capability
The external capabilities an agent uses: tools, MCP, search, and memory. A local method, a subagent in the same JVM, and a remote server connected over MCP all look like the same kind of tool to the main agent.
Spring AI:
@Tool, MCP clients and servers,TaskToolsubagents, skills, RAG -
T4 Foundation
The underlying resources that the two intelligence tiers use: models, data, and infrastructure. Models belong here too, because they are a resource that supplies reasoning.
Spring AI:
ChatModel,EmbeddingModel,VectorStore, the ETL pipeline -
Cross Cross-cutting concerns
Concerns shared by every tier rather than owned by one: observability, governance and human-in-the-loop (HITL), security and sandboxing, audit logging, and cost and rate control.
Spring AI: Micrometer observations and OTLP, MCP Elicitation approval gates, MCP Security (OAuth2, JWT)
-
Standard interface: MCP
The boundary where Orchestration calls Capability, implemented today with the MCP protocol. Where you place this boundary decides how clients and servers, processes, teams, and deployment units are divided.
Splitting the deployment across clients and servers¶
The four tiers are a logical division, so how you deploy them can differ from system to system. The book makes the CLI that users run in a terminal the main agent and splits business capabilities into domain-specific MCP servers.
The client CLI process holds the Channel (T1), Orchestration (T2), and the local capabilities that run directly (T3). Capabilities operated separately, such as inventory lookup or internal document search, move to MCP servers, and the two sides connect over MCP on Streamable HTTP. When a new business capability is needed, you can leave the main agent's code as it is, add an MCP server, and register only its connection details.
Mapped to Spring AI components, the design looks like the figure above. ChatClient and the advisor chain handle orchestration, and local @Tool methods, community tools, and tools on remote MCP servers all come together behind a single tool interface. In Chapter 6, the enterprise agent CLI article completes this setup in code, and the observability article turns on tracing across every tier. The articles before them cover the parts in this figure one at a time.
Reading along with the book's chapters¶
These articles follow the Korean book The Complete Guide to AI Agent Development with Spring AI 2.0 chapter by chapter. Each article covers the chapter's key concepts and explanations, along with code from the example repository. For readers who want to dig into design rationale, internals, and measured results, each article lists the matching sections of the book at the end. If you find a mistake, please report it by following the error reporting guide.
The example code is shared with the Korean edition, so prompts, comments, and console output inside code blocks stay in Korean, as do the figures taken from the book; the articles explain what each example does.
-
Chapter 1 AI Agents: The Start of a New Paradigm
-
Chapter 2 The Spring AI Framework
-
Chapter 3 Spring AI and RAG
-
Chapter 4 Tool Calling
-
Chapter 5 Spring AI MCP
-
Chapter 6 AI Agents
- 4-Tier Architecture for AI Agent Systems
- The Agent Loop and Context Engineering
- Recursive Advisors and Tool Loop Control
- Spring AI Agent Architecture, Implementation, and Dynamic Tool Discovery
- Human-in-the-Loop (HITL): An Approval Gate with MCP Elicitation
- Agent Skills: Extending Agent Capabilities with Reusable Skills
- An Enterprise Spring AI Agent CLI: Multi-Agent and Meta-Tool Orchestration
- Observability for AI Agents: Micrometer, OTel GenAI Semantic Conventions, and OTLP
-
Appendix Taking the hands-on work further
The book, the example repository, and the Playground¶
The Complete Guide to AI Agent Development with Spring AI 2.0
Korean title: 스프링 AI 2.0으로 배우는 AI 에이전트 개발 완벽 가이드
By Jemin Huh, Wikibooks, published September 17, 2026, 692 pages, in Korean
The source of this site. From ChatClient to RAG, tool calling, MCP, and enterprise AI agents built on the 4-tier architecture, every exercise runs on Spring AI 2.0 GA with local models only. This site covers the essentials, and the book goes further into the design rationale, internals, and measured results of each section.
-
Example repository
An independent Maven project for each chapter, using Java 21, Spring Boot 4, Spring AI 2.0.0 GA, and Ollama with
qwen3.5:4bandbge-m3. Code blocks on this site come straight from the repository files. -
Spring AI Playground
A separate open source project, with the author as lead maintainer. It is an incubating project of the Spring AI Community: a desktop application built with Spring AI, with a UI developed in Vaadin. It lets you try five areas in one place: Tool Studio, MCP server connections and the MCP Inspector, Vector Database and RAG, Agentic Chat, and Observability. You can connect the book's MCP servers to it as they are (Appendix D of the book).