ToyAgent 总览：智能体的最小公式

系列：ToyAgent 智能体知识库 00/26

一句话核心：智能体不是玄学，它就是一个会调用大模型的 Java 程序——大脑、手脚、记忆、循环、工程化兜底，五件套拼起来就是全部。

为什么需要一张总览图

初学者接触 Agent 领域时最容易被术语淹没：ReAct、Function Calling、MCP、多智能体、A2A、Harness……似乎每个词背后都是一座山。实际上这些东西共享同一个内核，整个领域的演进可以压缩成一条公式：

智能体 = 大模型（大脑）+ 工具（手脚）+ 记忆（延续）+ 循环（节拍）+ 工程化（兜底）

26 个进阶场景，本质上就是把这个公式逐项拆开、再逐项装回去的过程。理解了这条主线，后面每一个具体技术点都能找到自己在地图上的位置，不会学成碎片。

核心机制：一个方法签名统摄一切

整个体系只有一个最小契约，所有场景都是它的实现变体：

public interface Agent {
    // 智能体最小契约：输入一句话，输出一句话
    String chat(String input);
}

这条设计有两个好处：

复杂度无处可藏。任何"高级"能力——ReAct 循环、工具注册、审批门禁、事件溯源——最终都要塞进 chat() 这一个方法里。想看懂某个场景的实现，直接读它的 chat() 即可，不需要在调用链里翻找。
能力是叠加而非重写。01 场景的对话 MVP 是地基，02 加提示词、03 加 ReAct 循环、04 加工具调用……每一层只在骨架上多加一种能力，前一层代码原封不动。

演进地图：26 个场景分几条线

线索	场景	递进关系
基础能力	01 对话 → 02 提示词 → 03 ReAct → 04 工具 → 05 记忆 → 06 意图路由	从"会说话"到"会做事、会记事、会分流"
生态协议	09 MCP → 10 技能 → 11 工具注册表	工具从手写清单到标准化协议、即插即拔
检索与知识	07 RAG → 08 LLM-Wiki	从外部检索到知识编译持久化
协作形态	12 多智能体 → 13 子代理 → 14 A2A	从单体到规划-执行-审查、动态派遣、跨体协作
运行时与安全	15 运行时 → 17 ReAct 运行时 → 19 人工介入 → 20 审批门禁 → 21 沙箱 → 24 Hooks	守卫、保险丝、挂起续跑、风险分级、纵深防御
工程化底座	16 工作流 → 22 事件溯源 → 23 插件 → 25 CLI → 26 定时	状态机编排、可回放、能力热插拔、壳形态、调度

阅读顺序不必按编号：推荐先吃透 01 → 03 ReAct → 04 工具 → 15 运行时 这条主线，其余场景按需取用。

graph TD
    A["用户输入"] --> B["Agent.chat 统一入口"]
    B --> C["大脑 大模型"]
    B --> D["手脚 工具"]
    B --> E["记忆 历史/检索"]
    B --> F["循环 ReAct/状态机"]
    B --> G["工程化 守卫/审批/沙箱"]
    C --> H["输出一句话"]
    D --> H
    E --> H
    F --> H
    G --> H

图示：智能体五件套公式——所有场景能力都从 chat() 这个统一入口叠加进来，最终收敛为一句输出。

举例：零依赖跑通最小骨架

这个体系刻意做到零框架依赖——JDK 17 即可编译运行，这让"跑起来验证"的成本降到最低：

# 编译（无需 Maven/Gradle，纯 javac）
cd ToyAgent
javac -encoding UTF-8 -d target/classes $(find src/main/java -name "*.java")

# 启动服务（默认 8099 端口）
java -cp target/classes cn.xiaofuge.ai.Application

# 接真实大模型：复制模板填 API Key
cp config.properties.example config.properties

一个对生产开发者很有启发的细节：不配 Key 也能玩。未配置 API Key 时自动降级为内置 Mock 模型，所有场景的骨架照常运转——ReAct 的每一步思考、工具调用的每一次决策、路由的每一次分流都能完整看到轨迹。这个"Mock 大脑 + 真骨架"的思路可以直接搬到 Spring Boot 项目里：用 LangChain4j 时给 ChatModel 做一个 Mock 实现，就能在没有配额、没有网络的情况下跑通集成测试和前端联调。

// 生产视角：同样的抽象分层在 LangChain4j 里天然存在
// 智能体代码依赖 ChatModel 接口，而非某个具体厂商
ChatModel model = apiKey != null
        ? OpenAiChatModel.builder().apiKey(apiKey).modelName("gpt-4o").build()
        : new MockChatModel("模拟回复");   // CI/本地联调用

教程章节与工程场景的映射

偏平台化的章节不用单独啃，它们的本质已经内嵌在场景实现里：

提示词工程 / Harness → 三层提示词结构（02）+ 运行时外壳（15）
Dify/Coze 可视化编排 → 节点 + 条件边的后端本质就是工作流状态机（16）
CLI Agent / GUI Agent → 25 是 CLI 完整实现；GUI 只需把工具侧换成浏览器执行器，骨架同 04
评估 / 部署 / 推理框架 → 换掉模型端点即可（Ollama/vLLM 都是 OpenAI 兼容协议）
展望篇 → 读完 26 个场景再看，会非常轻松

面试考点

"Agent 和 Chatbot 的区别？"——最小 MVP 阶段两者没有区别（都是一句话进一句话出）。区别来自后续叠加：Chatbot 停在对话，Agent 在对话之上叠加了工具、记忆、循环与目标导向。
"为什么用单方法接口而不是暴露一堆 API？"——单方法契约让能力叠加成为可能，也让所有复杂度收敛到一处，可测试、可替换。

生产化路径

把 Agent.chat(String) 契约推广到你的服务里：对上层只暴露一个入口方法，内部按需组装提示词、记忆、工具，不要让调用方感知内部编排细节。
自建一套"场景演进清单"：每次给智能体加能力时，先问"这属于公式里的哪一件？"——大脑（换模型/调提示词）、手脚（加工具）、记忆（加历史/检索）、循环（加 ReAct/状态机）、兜底（加守卫/审批/沙箱），避免功能堆叠失控。