Spring AI 2.0 Source Code Deep-Dive Series Kicks Off with a 24-Part Call-Chain Breakdown

Foreword

Many business systems now use Spring AI, but in recent conversations with colleagues, I've noticed that many people are still stuck at the usage level and don't really understand the call chain or the underlying logic.

Since I don't have any content to publish right now, I'm starting a new series: a complete read-through of the Spring AI 2.0 source code, along with a full breakdown of the internal source code chain.

This series is tentatively planned for 24 articles.

Articles will be published simultaneously on WeChat Official Accounts and Juejin. Some highlights will be synced to X, and each chapter's content will be synced to a GitHub repository for easy archiving and reading. Later, for parts suitable for demonstration, I will record short videos to share.

Since large models entered Java projects, various Agent frameworks have emerged endlessly. Calling a model is now the simplest step.

But as the amount of code gradually increases, problems will slowly emerge. For example, where exactly is the context stored? How are tools registered? Who controls multi-turn calls? How much code needs to change when switching model providers? And where do you look at logs when something goes wrong...

I believe everyone has many questions about these kinds of issues.

Spring AI has actually created a very "Spring"-style encapsulation for these problems. It's quite handy to use, but it also hides many details behind interfaces, auto-configuration, and Advisors.

So I want to take it apart, just like Mr. Lei disassembles a car, peeling back the layers from the outside in to reveal the real code logic.

Starting with These Few Lines of Code

A conversational call in Spring AI is very brief:

String content = chatClient.prompt()
        .user("Hello")
        .call()
        .content();

Four lines of code to have a conversation with a large model.

But if you dig deeper, the questions become apparent:

Who created ChatClient?
What does prompt() return, and where is the preceding configuration saved?
Why doesn't call() directly call the model?
At which point does the Advisor intervene?
How is a Prompt converted into the request required by a model provider's SDK?
Do streaming calls, tool calls, and structured output go through the same chain?

For a Hello World, these questions don't matter, but what about a real business system?

After adding Chat Memory, historical messages need to enter the request. After integrating Tool Calling, a single request might become multiple "model call—execute tool—call model again" cycles. RAG also adds retrieval and context assembly before the request is sent to the model. MCP puts tools, resources, and prompts into a remote protocol.

If the main call chain isn't clear, these features can easily be misunderstood as several unrelated Starters.

The code might appear to run, but when a problem occurs, you won't even know at which layer to set a breakpoint.

Why 2.0.0

The series will consistently use Spring AI v2.0.0, corresponding to commit ef502da.

As of this article, this is the latest official release.

2.0.0 is also a fitting new starting point. It's based on Spring Boot 4 and Spring Framework 7, and reorganizes Options, null safety, and model integration methods. The tool calling loop has also entered the Advisor Chain. Capabilities requiring multiple rounds of execution, like Tool Calling and structured output retries, can now be organized along the same chain.

If key implementations change in subsequent versions, I will separately supplement the differences and won't mix code from different versions in a single article.

How to Read

I certainly won't go through the project directory from the first package to the last. The source code directory only defines module boundaries; it can't explain how a single request actually runs after it comes in.

I will first get the functionality running, set a breakpoint at the business entry point, and follow the actual execution path layer by layer.

In principle, one article handles only one problem.

If a single call chain diagram can express it clearly, then I'll avoid piling up numerous class diagrams.

I will also only keep the source code parts that affect the flow, not copying entire class files into the article. At the same time, I'll try to paste source code snippets in code blocks for easy searching and reading, minimizing direct screenshots.

A characteristic of Spring family products is using abstraction to reduce complexity, but too much abstraction can become a black box—the complete call chain is hidden too deeply. Therefore, during analysis, it's necessary to look concretely at what problem each layer solves, how much understanding cost it adds, and whether it's necessary to use it directly in ordinary business projects.

Content Sequence

The preliminary content structure has been planned.

The first few articles will revolve around a single conversation request, tracing it from start to finish, including Starter auto-configuration, ChatClient, Prompt, Message, Options, ChatModel, and how OpenAiChatModel calls the provider's SDK. Streaming responses and Structured Output will also be placed in this section.

After the main chain is clear, we'll look at Advisor, Chat Memory, and Tool Calling. The focus here will be on explaining ToolCallingAdvisor: after the model returns a tool request, where exactly is the Java method executed, how does the execution result become a message again, and under what conditions does the loop end.

Next up is MCP. First, we'll see how the Client discovers and registers remote tools, then how the Server exposes Tools, Resources, and Prompts. This way, we can directly see what changes occur in Spring AI's call chain before and after MCP integration.

The final section revolves around RAG and engineering capabilities: Document Reader, document splitting, EmbeddingModel, VectorStore, retrieval augmentation, Retry, Micrometer, and how to extend new model providers, especially integrating those domestic large models.

According to the current plan, it's divided into 3 major sections, with a total estimate of 24 articles. However, there will certainly be some changes during the writing process, but the overall route remains unchanged.

Prioritizing content quality, letting the content dictate the chapters, without padding the word count.

The First Article

The title for the first article is already decided:

"Spring AI 2.0 Source Code Analysis (Part 1): What Exactly Happens During a ChatClient Call?"

I will start from the five lines of code mentioned earlier, first find the creation process of ChatClient, then follow prompt(), call(), and content(), tracing all the way to ChatModel and the provider's SDK.

The subsequent Advisor, Memory, Tool Calling, and RAG will all gradually loop back to this call chain.

Keeping the main thread on track.

The first article starts here.

A journey of a thousand miles begins with a single step.

Interested friends can follow me, and let's dive into the grand blueprint of Spring AI together, experiencing the technical aesthetics of the Spring family.