Java AI Agent 开发实战

PREFACE前言

这本书的起点是一个观察：AI Agent 的教程和开源项目几乎全部以 Python 为母语，而真正要把 Agent 落地到企业系统里的那批人，一大半写的是 Java。他们熟悉 Spring、Maven、JdbcTemplate 和线上排查，却被一句"先装个 Python 3.11"挡在门外。这不是能力差距，是生态时差——Java 侧的工具链在 2024 到 2026 这两年里其实已经齐了：LangChain4j 稳定到了 1.0，Spring AI 进了 Spring 官方家族，MCP 有了官方 Java SDK，AgentScope 出了 Java 版本。缺的是一条把这些串起来、按 Java 工程师的心智习惯讲清楚的路。

本书就是这条路。全书六篇二十二章，走一条"先手写、再协议、后框架、终多智能体"的主线：第一篇用纯 JDK 从零写出 Agent 的全部核心机制——对话循环、工具调用、Agent 循环、记忆、结构化输出，一个框架都不用；第二篇把工具层升级成协议，手写 MCP 客户端、用官方 SDK 写 server；第三篇和第四篇是双主线框架，LangChain4j 与 Spring AI 各占一篇，同一个工单分派需求在两边各实现一遍，优劣对照自己看；第五篇进入 AgentScope Java 的多智能体与 harness 世界；第六篇是毕业项目，把全书攒下的零件组装成一个带事件溯源和安全护栏的教学版编码 Agent。

为什么坚持先手写？因为框架的抽象只有在你知道它替你挡掉了什么之后才有价值。第一篇写过工具调用回路的人，看 AiServices 的动态代理和 Spring AI 的 ToolCallback 时看到的是老朋友；直接从框架入手的人，遇到工具参数绑不上、循环不终止这类问题时只能搜报错。手写那六百行代码，是这本书里回报率最高的投入。

关于可运行性，先做三个声明。第一，全书代码基于 JDK 17、LangChain4j 1.0.0、Spring AI 1.0.0、MCP SDK 0.17.0、AgentScope 2.0.1，版本全部锁死在附录 A 的对照表里；框架升级可能破坏示例兼容，书的核心机制（第一、二篇和第六篇的内核）不依赖任何框架版本。第二，所有章节项目都配了一个脚本化模型（ScriptedModel）：不配任何 API key，测试和演示照常运行；要接真实模型，设一个 DEEPSEEK_API_KEY 环境变量即可，书里的客户端走 OpenAI 兼容协议。第三，涉及真实外部服务的实验（比如把 MCP server 接入真实客户端）在章内明确标注，读者按需进行。

书里难免有错漏，欢迎批注。祝你的 Agent 早日上生产。