Agent 开发
优化 Agent 的逻辑和优化人类无异
# Agent 概述
# Agent 是什么
- 智能体是能自主感知环境、决策并执行动作以达成目标的实体。核心能力是工具调用——把 LLM 连到外部世界。
- Agent vs Workflow:Workflow 是人工编排的固定步骤,Agent 让模型自主决定工具调用与规划,更灵活但不可控。选型看任务开放性:边界清晰用 Workflow,模糊探索用 Agent。
- LLM 能力链:输入 Prompt → LLM → output(纯文本)。通过工具调用,Agent 能访问数据库/API/知识库,突破纯文本限制。
flowchart LR
U[用户请求] --> LLM[LLM 推理]
LLM -->|决策| T[工具调用]
T --> DB[(数据库 / API / 知识库)]
DB -->|结果| LLM
LLM --> A[自主回答]
2
3
4
5
6
# 智能体架构
Agent 系统可拆解成若干模块,按需求组合:
- 意图识别:路由到不同服务(客服/订单/退款),也可用 RAG 从知识库检索相似案例
- 规划:任务拆解(CoT / ReAct);LLM 输出
PlanJSON(steps + tools),后续按计划执行或实时重规划 - 记忆:短期记忆(对话历史/当前会话)、长期记忆(跨会话的用户偏好/知识,用向量库实现)
- 工具:定义 Tool Schema,LLM 按 Function Calling 返回工具名+参数,Agent 执行后把结果喂回 LLM
- 行动:执行层,对接外部 API/数据库
- 反思:让 LLM 审视输出/计划并迭代改进(Reflexion)
Agent 循环:思考 → 行动 → 观察 → 调整,直到目标达成:
flowchart TD
A[用户输入] --> B[Thought 思考]
B --> C[Action 调用工具]
C --> D[Observation 观察结果]
D --> E{目标达成?}
E -->|否| B
E -->|是| F[输出最终答案]
2
3
4
5
6
7
多智能体系统:群体协作(类似对讲机,有组织/通信/协作/决策机制)或个体+工具栈(把专家能力打包成 Skill)。ReAct 范式 = Reasoning + Acting,每步都记录思考与行动。
# 主流框架
| 框架 | 定位 |
|---|---|
| LangChain | 组件丰富,链式编排 |
| LangGraph | 有状态、多 Actor 编排 |
| Dify | 可视化拖拽,快速原型 |
| Coze | 字节出品,插件生态 |
| AutoGen | 多智能体对话协作 |
# 大模型应用开发
AI 应用分层:
- 模型层:LLM(文本生成/推理)、Embedding(文本向量化)+ Reranker(相关性重排)
- 应用开发层:Prompt 工程、RAG 检索、Agent(记忆+规划+工具调用+Action)、Function Calling
- AI 应用:ChatBot、Copilot、AI 原生应用
# Spring AI 基础
# ChatClient 响应式编程
ChatClient 用流式(Stream)输出降低首字延迟:Prompt → LLM → Flux<ChatResponse>,逐片段推送到前端。服务端用 SSE 或 WebSocket 把每个片段实时发出。
# ChatClient advisors 机制
Advisor 是拦截器链,在调用 LLM 前后插入逻辑(记忆、日志、RAG):
ChatClient.create(chatModel)
.prompt()
.user(message)
.advisors(
MessageChatMemoryAdvisor.builder(chatMemory).build(), // 会话记忆
new LoggerAdvisor(), // 日志
new QuestionAnswerAdvisor(vectorStore) // RAG
)
.call().content();
2
3
4
5
6
7
8
9
内置 advisor:MessageChatMemoryAdvisor(历史入消息)、VectorStoreChatMemoryAdvisor(历史走向量检索)、QuestionAnswerAdvisor(RAG)、SafeAdvisor(内容审核)、LoggerAdvisor。
自定义 Advisor 实现 RequestAdvisor / ResponseAdvisor(或 BaseAdvisor),在 before() 改写 Prompt、after() 处理响应,通过 getOrder() 控制顺序。
# Structured Output Converter
把 LLM 的非结构化文本确定性转换为 Java POJO。原理:Prompt 里附带 JSON Schema 要求格式化输出 → 拿到文本后用 BeanOutputConverter 解析映射为对象:
BeanOutputConverter<ActorsFilms> converter =
new BeanOutputConverter<>(ActorsFilms.class);
String format = converter.getFormat(); // 注入 prompt,告知输出格式
String response = chatClient.prompt().user(u -> u.text(...).param("format", format)).call().content();
ActorsFilms result = converter.convert(response); // 解析为对象
2
3
4
5
# 声明式工具 Function Calling
把 Spring Bean 方法暴露为 LLM 可调用工具:
@Service
public class WeatherService {
@Tool(description = "根据城市名查询天气")
public String getWeather(@ToolParameter(description = "城市名") String city) {
return weatherApi.query(city);
}
}
2
3
4
5
6
7
@Tool+@ToolParameter描述工具用途与参数,框架自动生成 Tool Schema- 调用流程:LLM 返回 toolCalls → 框架按名字匹配 Bean 方法、反序列化参数 → 执行 → 结果作为 ToolResponseMessage 回喂 LLM
- 1.0 GA 后
@Tool方法可直接在 ChatClient 中通过.tools(bean)注册,也可用ToolCallbackProvider编程式注册
# 工具增强 Advisor
ToolCallbackAdvisor 把工具调用与 advisor 链结合,在流式响应中处理工具回调。Spring AI 的 ToolCallingManager 负责执行工具并把结果回填消息列表,支持同步与异步(Reactive)两种模式。
# Prompt 提示词工程
四大因素:角色、任务、上下文、格式
# Few Shot 和 CoT
- Zero/Few Shot:零/少样本学习,用少量样本告知 LLM 该干嘛
- CoT:Chain of Thinking 思考链,即告知 LLM 先干嘛再干嘛最后干嘛
Few-Shot 示例结构:<Examples> 放 Q&A 样本,<Output format> 用 JSON 规定输出字段(reasoning / result / nextPlan)。
检验 Prompt 质量:多次输入相同 Prompt,输出一致说明质量不错,否则 LLM 不确定需求、需反复输入。
减少幻觉、稳定回复:优化提示词 / 微调模型 / 调低温度 / 接入 RAG。
# 系统和用户提示词
角色定义五要素:基本资料(语言/角色/背景/性格/领域)、核心技能、规则、工作流、初始化指令。
系统提示词在创建对话前载入,限定角色/技能/约束;User Prompt 用 JSON 格式承载工程化任务,结构:
{
"currentInformation": { "iteration": "", "goal": "", "observation": "", "callChain": "" },
"coreTask": { "objective": "", "steps": [], "thinkingRules": [] },
"attention": { "taintPropagation": {}, "executionOrder": {}, "defenseFunctions": {} },
"responseFormat": { "requiredFields": { "reasoning": "", "plan": "", "nextAction": "" } }
}
2
3
4
5
6
构造对象时用 toString() 生成 String 变量,避免 ObjectMapper 映射出错。
# Json 结构化输出
让 LLM 稳定输出 JSON 的组合拳:提示词 → 原生能力 → 底层约束 → 兜底机制。
- 提示词:Few-Shot 打底,系统/用户提示词里写明期望的 JSON 结构与字段示例
- 原生能力:定义本地 Function Call(结构化输出工具),用
@Tool强制 LLM 按固定结构返回 - 底层约束:降低温度、微调模型减少幻觉
- 兜底机制:ObjectMapper 映射失败时,把错误封装成 ErrorJsonOutput 丢进下一轮对话,让 LLM 重新处理
# Context 上下文工程
ACE,Agentic Context Engineering
Prompt 告诉模型如何思考,Context 赋予模型完成工作所需的知识和工具。
# 上下文工程概述
在正确的时间、以正确的格式为 LLM 提供正确的信息和工具,可靠、可扩展地完成复杂任务。
- 根本目的:解决上下文腐败——信息少模型理解不了,信息太多模型幻觉多。在有限上下文窗口里塞最高效的信息
- 通过格式化、结构化关键信息,缩减对话上下文长度,防止注意力发散和幻觉,提高准确率
- 从直觉调优到工程式优化,是 Agent 从 Demo 到产品的必经之路
# 基于污点分析的 ACE
静态代码分析里,RestAPI 只需关注"从接口入参到风险函数(命令执行/SQL)是否存在有效路径"。入参 arg1 影响 output1 → output1 受污(tainted),即污点传播。
Agent 每轮 Loop 只处理当前函数,判定"是否有受污参数从用户输入影响到风险函数",用 JSON 精简输入:
{
"function": { "filename": "src/test.java", "functionName": "Test", "paramsList": ["String arg1", "int arg2"] },
"tainted": [true, false]
}
2
3
4
分析 arg1 是否传到下一层函数入参,问题逐轮抛给下一 Loop,直到 exec() 风险点。这种 JSON 格式化输入输出比纯文字简洁高效,且与 rules 呼应。
# RAG 检索增强生成
整体流程:文档分片 → 每片生成 embedding 存 ES → 用户提问向量化 → ES 混合检索(向量+BM25)→ 召回 chunk 拼进 prompt → LLM 生成 → WebSocket 流式返回。
# RAG 概述
RAG = Retrieval-Augmented Generation,检索增强文本生成,目的是降低幻觉。知识库辅助从 Tuning → RAG → Agentic Search 不断进化,本质都是提高准确度的 prompt 工具。RAG 自身也在迭代:RAG → Graph RAG → Agentic RAG。
2026 年的方向:31B 小模型专做检索辅助主模型生成、LLM Wiki(用渐进式披露的 markdown 代替向量库)、结构化搜索 vs grep 之争(CodeGraph 图索引 vs 全文 grep)。
# RAG 构建
核心四步:文档收集切割 → 向量转换存储 → 文档过滤检索 → 查询增强关联。会用到 Embedding 模型(部署:vLLM / Ollama;资源:ModelScope / HuggingFace)。
# ETL 处理
Spring AI 的 ETL Pipeline 支持文档抽取-转换-加载。用 MarkdownDocumentReader 读取 md 文档,配置项指定是否读代码块/引用块,并提取 fileName 作为元信息便于召回。
分片策略:切太短(256–384 token)上下文丢失、语义太碎;切太长(768–1024 token)超过模型上限 80% 则语义稀释、embedding 质量下降。1 token ≈ 1.2–1.5 个中文字符。
overlap 策略:固定大小分片(512 token),相邻 chunk 重叠 25%(10–25%),避免关键信息落在切割边界丢失。滑动窗口伪码:
chunk_size, overlap := 512, 128
step := chunk_size - overlap
for start := 0; start < len(tokens); start += step {
store(tokens[start : min(start+chunk_size, len(tokens))])
}
2
3
4
5
# 向量数据库
向量库本质是搜索引擎:ES 搜 string(BM25),向量库搜向量(ANN 算法)。
# VectorStore 内存向量
Spring AI 内置 SimpleVectorStore(基于内存,实现 VectorStore 接口)。写入前先调 Embedding 模型把文档转成向量再存。配置流程:加载 md → 关键词元信息增强(KeywordMetadataEnricher)→ 可选自定义切分(TokenTextSplitter)→ simpleVectorStore.add(documents)。
检索增强:构造 chatClient 时用 QuestionAnswerAdvisor(vectorStore) 注入向量库,CHAT_MEMORY_RETRIEVE_SIZE_KEY 控制召回数量。
# pgvector 和 Qdrant
- pgvector:已有 Postgres 时首选,借助 B-Link 树索引 + WAL 机制,通过开放接口实现向量索引。规模上不如专用向量库
- 专用向量库:Qdrant(AI 原生语义搜索)、Milvus(云原生 ANN)、VectorDB(基于 bRaft,C++ 编写)
# LLM Wiki
结构化搜索与 Grep 之争
业内共识:直接用 LLM 做 grep 比 RAG 性能和效果都好。与其切分/向量化/嵌入,不如用一个 Skill 高效检索。三个问题:
- 文档解析:用外置命令行工具,让 AI 具备自我解析能力
- 文档索引:教 AI 建 Markdown 索引、渐进式披露(LLM Wiki 核心),提供
/build-index接口 - 文档搜索:教 AI 按索引 grep,全局搜索兜底
开源实现:VectifyAI/PageIndex。思路与 RAG 一致:向量检索 + 语义检索 → 渐进式披露。
# MCP 服务
MCP(Model Context Protocol),模型上下文协议,在原有业务逻辑上套一层网络协议的壳。
# Tool Calling 方法
MCP 的前奏,通过 @Tool 注解注入 Spring。辅助工具:Kryo(文档生成)、Knife4j、Hutool、Jsoup(网页抓取)、SearchAPI。
选型原则:优先用工具调用,而非 MCP。只有公共服务(如 LSP 服务)需要提供给多个 AI 应用时才考虑 MCP 部署,符合最小设计原则——从 Tool 提取到 MCP Server 很简单,但从 MCP 耦合回单个项目很麻烦。
工具定义与调用:
@Tool(description = "获取指定城市的天气信息")
public String getWeather(@ToolParameter(description = "城市名称") String city) { ... }
2
两种注册方式:
- 手动注入:Controller 里
.tools(weatherService),只对该 ChatClient 生效 - 全局注入:声明
ToolCallbackProviderBean(MethodToolCallbackProvider.builder().toolObjects(weatherService).build()),所有 ChatClient 自动携带
# MCP 协议流程
基于 JSON-RPC 2.0,三个生命周期阶段,可理解为一次微服务调用:
sequenceDiagram
participant C as Client
participant S as Server
C->>S: initialize (协议版本 + capabilities)
S-->>C: initialize 响应 (协商版本 + 服务端能力)
C->>S: notifications/initialized (无 id,确认初始化完成)
C->>S: tools/list 查询工具
S-->>C: 工具列表 (name + description + inputSchema)
C->>S: tools/call (工具名 + arguments)
S-->>C: 执行结果 (content)
C->>S: notifications/cancel (断开)
2
3
4
5
6
7
8
9
10
11
- 初始化:类似三次握手,
initialize请求带协议版本与客户端能力,服务端回协商版本与能力(tools / resources / prompts / logging) - 发现:
tools/list拿工具清单(每个工具含 name、description、inputSchema),resources/list拿资源列表 - 调用:
tools/call传工具名与参数,服务端执行后以 JSON 返回结果 - 关闭:
notifications/cancel断开连接
# MCP 构建与应用
MCP 不是银弹,不要用 MCP 代替 Tool Calling
常见平台:MCP.So、阿里百炼、Glama。
Server 端:引入 spring-ai-mcp-server-spring-boot-starter,在 YAML 配 SSE 端点(sse-endpoint、sse-message-endpoint、type)。工具写法和 @Tool 完全一样,区别是要在 ToolCallbackProvider 处注入 Bean——启动时自动扫描并暴露到配置端口。也支持 stdio 模式。
Client 端:引入 spring-ai-mcp-client-spring-boot-starter,配置 SSE 连接(url)或 stdio 连接(command + args + env),启动时自动扫描对应端口的 Tool。
# GF HTTP MCP
实际使用中可以不用 MCP 协议实现 MCP 功能——无非是微服务提供。百度 GenFlow 的 MCP 工具就是直接注册 HTTP 接口,参数构造、调用流程由基础层适配,调用流程与微服务 BNS 完全一致。
注册典型 MCP 工具(在线搜索、文档转换、海报生成、网盘/知识库搜索、架构图、脑图、学术搜索、PPT 生成/大纲):
mcprouter := router.Group("/mcp")
mcprouter.HandleStd("post", "/makepptoutline", mcpapi.NewMakePPTOutlineCallFunc())
mcprouter.HandleStd("post", "/makepptbyoutline", mcpapi.NewMakePPTCallFunc())
// ...
2
3
4
Controller 遵循 Init(参数反序列化)/ InitBase(注入基础控制器、设 SSE 输出)/ OnExecute(主逻辑)三段式。OnExecute 从 CommonParam 提取 UserID/QueryID/ChatID/Channel 等注入请求参数,按 PPTMode(html / 传统)选择服务层函数,拿到 chatChan 后逐帧写入 OutCh(),错误帧写 ErrCh():
flowchart LR
A[HTTP 请求] --> B[OnInit 反序列化]
B --> C[InitBase 注入控制器]
C --> D[OnExecute]
D -->|PPTMode=html| E[PptAgentOutline]
D -->|传统| F[MakePPTOutline]
E & F --> G[chatChan 逐帧]
G --> H[OutCh / ErrCh → SSE]
2
3
4
5
6
7
8
关键点:Controller 逻辑收敛于服务层两个函数 PptAgentOutline / MakePPTOutline。
# 大纲生成
makepptoutline 用管道返回 SSE 数据,逐帧返回,帧结构 PPTOutlineFrame(Title、Result、ResultBdjson、LayoutFlag、SpecialLayoutSwitch)。
准备阶段 PPTPrepareMultiQuery:加载参考文档并构造请求。按文件后缀区分文档(doc/docx/pdf/ppt/xls/txt)和图片(jpg/png/jpeg),处理逻辑:
- 图片和文档混合、或多图片 → 图片解析成 txt → 转 bdjson → 走文档生成
- 只有单图片 → 可走文本生成
- 高优先级来源:网盘、网页搜索摘要、学术搜索摘要
后续流程:构造 LLM 请求 → 流式生成大纲 → 按帧推送,每帧携带标题与 bdjson 结果。
完整实现见:makepptoutline_controller.go(Controller)、PPTPrepareMultiQuery.go(请求准备)。
# PPT 生成
makeppt 直接根据大纲内容封装参数请求策略,帧更复杂,直接返回 PPT 内容在前端渲染。
策略返回帧 StrategyOutlineToPPTSSEResp 关键字段:ErrNo / ErrMsg、LogID、UserID、QueryID、ChatID、IsEnd、Title、Data(PPT 内容)、SlidesSign。生成模式分 SSE(流式)和 original。业务侧常量含跳转路径格式(预览/编辑 bdwenku:// scheme)和渠道标识。
完整实现见:PPTGenerate.go、ppt_constants.go。
# 文档转存
PPT 生成完成后,把结果落库转存为文档,涉及 bdjson 结构、PPT 注册信息(RegisterPPT)、SSE 文件信息等结构,最终生成可预览/编辑的文档链接。
完整实现见:GetFileInfosWait.go。