前言：为什么现在学习 Agent 工程

这不是一本 API 目录，也不是某个框架的速查表。本书面向已经写过 Java 服务的读者，沿着一个可测试的知识库助手，逐步理解模型、工具、上下文、检索、记忆、审批和评测如何组合。你不需要先学 Python，也不需要先购买模型服务。

学习目标

你将学会把“让模型做事”的愿望拆成可验证的接口，写出能拒绝非法动作、记录工具轨迹、在预算耗尽时停止、从检查点恢复的 Java 程序。

原理

书中示例使用 Java 21、Maven 和 JUnit。前八章的核心示例使用固定假模型与本地文档，因此可以在无密钥环境运行；真实模型接入只在适配层讨论，并明确标记网络调用和费用。每章都包含学习目标、原理、Java 示例、失败分析、练习、参考答案、小结和资料引用。

Java 环境

安装 JDK 21 和 Maven 后，在 examples/agent-core 执行 mvn test。本书不会把 Spring Boot 当成前置条件；当框架能帮助部署时，我们会说明它替换的是哪一层。

练习与答案

先运行示例，再读失败分析，最后完成练习。答案不是唯一实现，重点是边界、证据和测试。

参考资料

论文、OpenAI 工具调用文档、MCP 工具规范和 EPUB 规范的版本信息见 docs/superpowers/specs/2026-10-20-source-notes.md。

Java 示例

实际运行输出（离线模拟）：mvn test 通过。这个输出只证明固定测试通过，不证明真实模型质量。

失败分析

如果读者直接把框架示例复制到生产系统，常见问题是没有超时、没有权限边界和没有回归样本。先完成本书的离线路径，再逐步接入外部服务。

参考答案

学习路线的答案是先掌握循环、工具和证据，再学习协议和多 Agent；每一步都保留可运行基线。

小结

本书把 Agent 还原成可测试的 Java 系统。

示意输出（真实模型适配）：response_id=...。该行只说明格式，不能当作本书已调用供应商服务的证据。