Agent 应用工程：从入门到交付。

先分清 AI、机器学习、语言模型与 Agent

用分类问题分清 AI、机器学习、语言模型和 Agent，再判断自己的任务是否需要模型。

AI、机器学习与深度学习的关系 · 训练与推理的区别 · 分类任务与生成任务

建立能重复运行的 Python 练习环境

跑通第一个 Python 脚本，分清终端、解释器和项目环境，并记录别人怎样重建它。

终端、解释器与源文件 · Python 版本检查 · Windows py 启动器

用列表、字典和函数处理第一份学习数据

用清洗标题的小任务学习列表、字典、函数和测试，掌握 AI 应用马上会用到的 Python。

字符串与空白清理 · 列表索引与遍历 · 字典取值及缺字段

看懂 HTTP 请求、JSON 与 API 错误

接模型前先看清请求地址、身份、正文和响应，再处理超时、错误与格式不合格的情况。

API 契约 · HTTP 方法与地址 · 请求头与请求体

用向量和相似度建立 Embedding 直觉

先用一组数字亲手算相似度，再理解文本向量如何用于查找相关资料。

标量、向量与矩阵 · 维度与对应位置 · 点积

本篇重点：先核对查询和文档的编码模型版本、归一化方式与索引是否兼容；换模型或迁移索引后检查检索结果，再用标注样例确定并检验相似度阈值。

理解 Transformer 如何利用上下文

从一句话怎样逐步生成出发，理解分词、注意力和上下文，不必先实现整套训练。

文本到 Token 标识 · Token 到向量表示 · 位置与顺序信息

本篇重点：画出 Token 怎样变成注意力输出，说明每个位置能看到哪些上下文、为什么不能提前看到未来内容；按需选学，不要求训练模型。

从一次 LLM 请求理解 Token 与上下文

从一次 Java 请求入手，看清模型收到了什么、返回了什么，以及用量、耗时和失败怎样记录。

消息角色与请求选项 · 上下文窗口 · 输入和输出 Token

本篇重点：记录请求用了多少 Token、输出是否被截断以及为什么结束，检查调用是否超出预算。

控制生成随机性与 Token 预算

分清温度、采样和输出长度各控制什么，再用实际任务比较效果和用量。

候选 Token 分数 · 概率归一化与 softmax · 贪心与采样

本篇重点：先累计每项概率，再用二分查找选中一次采样结果；检查边界输入和调用预算，观察生成结果的随机性。

把模糊需求写成可测试的提示

把任务、资料和通过条件写清楚，再用一致的示例说明应该怎样回答、缺资料时怎么办。

任务目标与验收标准 · 输入资料边界 · 零样本提示

让 AI 按指定格式回答：结构化输出与校验

先约定模型返回哪些字段，再检查格式、业务范围和内容对错，让结果能直接用于应用。

业务字段设计 · Java record 映射 · 文本转换器边界

让结构化结果通过三层校验

数据能解析成 Java 对象后，继续检查必填、空值、范围和资源权限，确认业务上能否执行。

JSON 语法校验 · Schema 结构校验 · 业务语义校验

把原始笔记变成可追溯的检索片段

先把资料读对、清理好、按意思切成片段并记录版本，再生成向量用于检索。

提取、转换与写入 · 原文完整性抽查 · 文档来源和版本

工具调用：执行、返回结果与正确停止

走完“模型提出请求—应用检查并执行—返回真实结果—继续回答”的完整工具调用流程。

工具名称和参数 · 调用 ID 与结果关联 · 应用分派和执行

本篇重点：先规定允许调用哪些工具（白名单），再记录调用 ID，处理重复与冲突，并设置执行预算和停止条件。

向量检索：选择距离、建立索引并检查召回

先用逐项比较找出正确结果，再检验近似索引节省了多少时间、漏掉了多少相关内容。

编码模型与维度配置 · 欧氏距离、点积与余弦 · 距离排序方向

组合关键词、向量检索与重排

结合关键词与语义检索，既找准类名和配置键，也找得到换了说法的资料，再重新排序。

关键词与向量检索互补 · BM25 与向量分数尺度 · RRF 排名融合

让 RAG 回答能回到原始证据

先从文档里找依据，再生成带真实引用的回答；资料不够时，明确说明还不能下结论。

RAG 检索与生成分工 · 文档章节与版本元数据 · 租户和权限过滤

单独测量检索召回与排序质量

用固定测试题检查相关资料有没有找到、排得够不够靠前，以及资料外的问题怎样处理。

查询、语料与相关标注 · 文档和片段标注单位 · Hit@k

本篇重点：先检查该找的资料是否找到、排在什么位置，再评估回答质量；用 Recall / MRR / NDCG 按样本类别分别检查，定位遗漏资料的原因。

把工具定义做成可测试的接口契约

把工具参数、返回值和错误说清楚，再分别测试工具本身，以及模型会不会正确使用它。

工具名称与能力边界 · 输入来源与必填参数 · JSON Schema 输入范围

提示注入与权限检查：限制工具能做什么

区分资料里的文字与真正的操作授权，在后端检查身份、资源和动作，拦住提示注入带来的越权。

用户、模型与工具信任边界 · 直接提示注入 · 检索和工具中的间接注入

用 MCP 连接工具，保留应用控制权

看懂应用、连接端和能力服务各负责什么，再实际完成一次工具发现与调用。

Host、Client、Server 职责 · 工具、资源与提示 · JSON-RPC 请求标识

排查 MCP 初始化、传输与会话问题

按初始化、协商、调用和断线几个阶段检查 MCP，分清本地进程与 HTTP 两种传输方式。

initialize 请求 · 版本与能力协商 · initialized 通知

用状态机决定哪里需要 Agent

先写清业务要经过哪些步骤，再把需要临场判断的选择交给模型，并限制它能走的路径。

工作流与 Agent 控制权 · 固定节点与动态决策 · 显式状态数据

不用真实模型也能验证状态机

把状态、事件和合法变化写成可测试的规则，确认完成、取消、重复通知时都走对流程。

状态和事件区分 · 状态转换表 · 纯函数迁移

分开保存历史、工作记忆与长期偏好

把历史、当前任务信息和长期记忆分开保存，让对话接得上，也给眼前的问题留够空间。

完整历史与工作记忆 · 长期偏好 · 消息条数与 Token 预算

本篇重点：记录记忆中的事实、出处和权限；以完整记忆组为单位选取内容，并检查是否超出上下文预算。

让执行能重启、重试与等待确认

保存长任务进度，防止恢复时重复操作，并让用户确认对应到具体内容和版本。

持久检查点 · 内存状态与进程重启 · 节点重放

流式与异步：用背压控制待处理数据

分清先显示一部分与真正完成，处理慢客户端、断线和取消，避免缓存越积越多。

流式与异步的区别 · 增量和完整结果 · 网络分块与事件边界

建立不会自我欺骗的 Agent 评测集

把真实任务、正确行为和失败类型整理成固定测试数据，让每次改进都有同一把尺子。

任务类型覆盖 · 输入、资料和预期行为 · 禁止行为约束

本篇重点：写清系统允许和禁止做什么，把同一原始案例的变体归为一组，记录失败类型，并固定回归测试的版本与通过条件。

用评测和执行轨迹判断 Agent 是否可靠

既检查任务有没有做成，也记录检索、决策和工具执行过程，让失败能找到具体原因。

结果和过程分别评估 · Schema 权限预算检查 · 引用支持与人工核对

本篇重点：沿一次请求的完整记录（trace）和各步骤记录（span）查找失败位置与耗时，再结合指标排查线上问题。

把 Spring 服务接入模型工具

沿用熟悉的 Service、Repository 分层，把小而明确的 Java 业务方法开放为模型工具。

ChatClient 接入 · @Tool 与 @ToolParam · 工具注册

为学习助手实现接口、存储与测试骨架

用 Java 后端保存任务、步骤和资料，设计发起、查询、取消、确认等接口，为完整项目做准备。

Controller Service Adapter 分层 · 兼容版本与构建配置 · 请求和响应 DTO

让记忆可以纠错、过期并保持隔离

给长期记忆记录来源、版本和有效期，并处理修改与撤回，避免旧信息重新生效。

记忆来源与确认状态 · 事实与推测区分 · 临时要求和长期偏好

管理重试预算、幂等键与并发恢复

分清哪些失败能重试，处理超时后结果未知，并防止重复请求和多个进程执行同一笔操作。

可重试与不可重试错误 · 指数退避和抖动 · 整体截止时间

在预算内拆解任务与协作

把计划写成有输入、结果和先后顺序的任务表，再让真正独立的子任务并行处理。

单代理基线 · 任务独立性和依赖 · 结构化计划

本篇重点：画出没有循环依赖的任务图（DAG），找出耗时最长的依赖路径（关键路径），再规定角色、预算和失败后受影响的任务。 安排固定角色的权限、依赖、通信与结果合并，判断是否需要多个 Agent。

设计评分规则并公平比较两个版本

组合程序检查、人工评审和模型评分，逐题比较新旧版本，说明提升、退步和不确定性。

确定性规则检查 · 硬约束门槛 · 人工评分 Rubric

本篇重点：先列出发布必须通过的检查，校准评分器，再比较新旧版本有没有退步，决定能否发布。

质量、成本与尾延迟：关注等待较久的请求

统计一整次任务的模型、工具用量和等待时间，在质量相同的条件下优化上下文、并发与缓存。

全任务调用量统计 · 输入输出及缓存计量 · 未知用量处理

本篇重点：逐次记录调用费用，缺少用量时标为未知；拆开从请求开始到结束各阶段的耗时，再设置应用预算。

毕业项目：可验证的 Java 学习助手

完成一个 Java 学习助手：查资料、出练习、保存计划，并用测试说明正常与失败时的行为。

授权笔记问答 · 来源引用与资料不足 · 练习题结构化生成