一文读懂Agents-Flex核心概念:ChatModel、Tool、RAG与Agent的完整知识地图
一文读懂Agents-Flex核心概念:ChatModel、Tool、RAG与Agent的完整知识地图
Agents-Flex 是一个轻量级的 Java AI Agent 开发框架(定位对标 Spring AI)。本文将带你一图看懂 ChatModel、Tool、RAG、Agent 四大核心概念如何协同工作,并快速掌握 MCP、Skills、Text2SQL 等扩展能力——这是从"调一次大模型"走向"构建能完成任务的智能体"的完整知识地图 🗺️。
一张图看懂:一次 Agent 请求的完整链路
理解概念边界,比记住某个 API 更重要。在 Agents-Flex 中,各概念各司其职:
模型负责生成,Prompt 负责组织输入,Memory 负责保存历史,Tool 负责连接行动,Agent 负责推进任务,RAG 负责引入外部知识。
它们可以组合,但不是同一个东西。一次简单的问答只需 Prompt → ChatModel → AiMessage;而一个能完成真实任务的 Agent,可能多次经过工具调用、知识检索与模型推理,直到得到最终结果。
| 概念 | 核心抽象 | 负责什么 |
|---|---|---|
| 模型 | ChatModel、EmbeddingModel、RerankModel |
调用具体 AI 模型 |
| 消息 | SystemMessage、UserMessage、AiMessage、ToolMessage |
表达对话中的角色和内容 |
| 提示词 | Prompt、MemoryPrompt |
把消息和工具组织成模型输入 |
| 记忆 | ChatMemory |
保存和读取会话历史 |
| 工具 | Tool、ToolCall、ToolExecutor |
把外部能力暴露给模型并执行 |
| 智能体 | Agent、AgentTurn、AgentRunner |
推进工具调用和多步骤任务 |
| 知识 | Document、VectorStore、SearchWrapper |
检索并引入外部知识 |
完整概念解析见官方文档 docs/zh/intro/concepts.md。
ChatModel:大模型统一接入的"总开关" 🧠
ChatModel 是 Agents-Flex 对对话模型的统一抽象。业务代码只面向它编程,同时支持同步和流式两种 API:
String answer = chatModel.chat("什么是 Tool Calling?"); // 同步调用
chatModel.chatStream(prompt, listener); // 流式输出
OpenAI、Qwen、DeepSeek、Ollama、LiteLLM 以及兼容 OpenAI 协议的服务,都能收敛到同一套接口。切换厂商时,通常不需要改写对话流程——模型是可替换的基础设施,而不是业务系统里拆不掉的依赖。
此外,框架为不同任务提供独立模型接口,而不是把所有能力塞进 ChatModel:
| 模型接口 | 典型用途 |
|---|---|
EmbeddingModel |
文本转向量,支撑 RAG 语义检索 |
RerankModel |
对召回结果做精细相关性排序 |
ImageModel / VideoModel |
文生图、文生视频 |
TextToSpeechModel / SpeechToTextModel |
语音播报、语音识别 |
💡 STT 把语音转成文字 → ChatModel 理解决策 → TTS 生成语音回复,多模态 Agent 由此组合而成。
相关源码位于 agents-flex-core/ 与 agents-flex-chat/,教程见 docs/zh/chat/getting-started.md。
Tool:让模型从"生成文本"走向"执行动作" ✋
只有文本生成能力的模型,知道很多,却无法改变任何真实状态。Tool 是大模型走进业务系统的第一座桥。
一次完整的 Tool Calling(函数调用)闭环包含 5 步:
- 应用把工具名称、描述和参数 Schema 随 Prompt 发给模型;
- 模型返回
ToolCall,说明要调用哪个工具、参数是什么; ToolExecutor解析参数并执行对应的Tool;- 执行结果封装为
ToolMessage加入对话; - 模型读取结果,继续调用其他工具或生成最终回答。
在 Agents-Flex 中,一个普通 Java 方法加上注解就能成为工具:
@ToolDef(description = "根据订单号查询订单状态")
public String queryOrder(@ToolParam(name = "orderNo", description = "订单号", required = true) String orderNo) {
return orderService.queryStatus(orderNo);
}
框架自动把方法描述转成模型可识别的参数结构,并提供 ToolInterceptor 拦截器链——鉴权、审批、限流、审计、脱敏都可以在工具执行前后插入,而不侵入业务方法本身。
详见 docs/zh/chat/function-call.md。
Agent:围绕目标持续推进任务的智能体 🤖
Agent 不是某种特定大模型,而是一种运行方式:它持有目标和状态,根据模型响应决定下一步,必要时调用工具、检索知识、询问用户,直到满足终止条件后交付结果。
初次接触只需记住 4 个核心对象:
| 对象 | 可以理解为 | 主要作用 |
|---|---|---|
Agent |
AI 助手的"岗位说明书" | 配置模型、系统指令、工具和执行规则 |
Tool |
AI 助手可以使用的工具 | 把 Java 方法提供给大模型调用 |
AgentRunner |
任务执行器 | 调用模型、执行工具并推动任务继续 |
AgentTurn |
某一次具体任务 | 保存任务状态、消息、结果和统计 |
Agent 运行过程通过 Snapshot 快照保存状态,可以在其他请求、线程甚至其他进程中暂停、恢复;缺少关键信息时会进入等待状态,敏感操作还可以要求人工审批。
📌 注意:固定步骤、结果确定的业务流程更适合普通 Java 代码;只有当下一步依赖语义判断或动态工具选择时,Agent 循环才真正产生价值。
下图是 Agents-Flex 的 Agent 运行时调试面板演示,左侧配置 Agent、中间是 AI Agent 对话(调用 request_user_input 表单工具向用户追问),右侧实时展示 Model、Tool 调用事件流与 Snapshot 保存过程:
Agent 模块源码见 agents-flex-agent/,入门文档见 docs/zh/agent/overview.md。
RAG:让模型使用企业自己的知识 📚
大模型参数里的知识可能过时,更不了解你的私有数据。RAG(检索增强生成) 先从外部知识源检索相关内容,再作为上下文交给 ChatModel。它分两个阶段:
阶段一:知识入库
文件或网页 → 文本提取 → Document → 切分 → Embedding → VectorStore
阶段二:在线检索与生成
用户问题 → Embedding → 向量召回 + 条件过滤 → Rerank → 上下文 → ChatModel
三者分工明确,缺一不可:Embedding 把语义变成可检索的向量,VectorStore 快速找到候选,Rerank 在候选中做精细排序。
Agents-Flex 覆盖了完整 RAG 链路,已提供 Redis、Milvus、Elasticsearch、OpenSearch、PgVector、Qdrant、Chroma 等存储适配:
| 能力 | 对应模块 |
|---|---|
| PDF/Word/Excel 等文件解析 | agents-flex-doc-extractor/ |
| Embedding 模型 | agents-flex-embedding/ |
| 向量/文档存储 | agents-flex-store/ |
| 重排序 | agents-flex-rerank/ |
更多文档见 docs/zh/rag/document.md、docs/zh/rag/vector-store.md。
进阶能力:MCP、Skills、Subagent 与 Text2SQL 🔧
并非所有外部信息都该进向量数据库。Agents-Flex 按数据形态提供了不同的扩展方式:
| 概念 | 本质 | 最适合的场景 |
|---|---|---|
| Tool | 框架内统一的可调用能力接口 | 暴露 Java 方法、API 或确定动作 |
| MCP | 连接外部工具服务的标准协议 | 跨进程、跨语言复用标准化工具生态 |
| Skills | 含说明、脚本、模板的能力包 | 需要方法论和多步骤执行的复杂能力 |
| Subagent | 独立的后台任务 Tool | 长任务执行与结果获取 |
| Text2SQL | 渐进式读取表结构的只读查询工具 | 自然语言查询结构化业务数据 |
其中 MCP(Model Context Protocol)客户端可管理多个 MCP Server,并把远端 MCP Tool 自动适配为统一的 Tool;Skills 则是可版本化、可隔离执行的能力资产,SKILL.md 描述流程,脚本和模板按需向模型渐进式披露。
下图展示了 Subagent 模块的多智能体任务执行架构,execute_task / get_task_output 两个工具由 LLM Agent 调用,底层由任务仓库、线程池和异步系统支撑:
而 Text2SQL 模块内置只读校验与拦截器链:LLM Agent 调用查询工具后,先做只读安全校验,再依次经过租户隔离、LIMIT 限制、审计等拦截器,最后执行 JDBC 查询:
相关源码:agents-flex-mcp/、agents-flex-skills/、agents-flex-subagent/、agents-flex-text2sql/、agents-flex-websearch/。
生产级加持:Model Router 模型路由与负载均衡 ⚡
真实流量下,单个模型节点随时可能超时或限流。Model Router 可以把多个 Chat 或 Embedding 模型组织成一个逻辑模型:
- 最少活跃与加权随机负载均衡;
- 按
vision、reasoning、cheap等标签选择节点; - 自动重试、熔断与半开恢复。
用户请求 → 过滤(状态/标签/熔断) → 负载均衡器 → 选中节点 → 真实LLM调用
├ 成功 → 记录成功
└ 失败 → 记录失败 & 重试判断
上层仍然调用普通的 ChatModel 接口,模型节点变化完全不侵入业务代码。详细流程见 docs/zh/intro/model-router.png:
最易混淆概念速查表 ❓
| 易混淆点 | 一句话区分 |
|---|---|
| ChatModel vs Agent | ChatModel 完成一次生成;Agent 执行零次或多次模型与工具调用,围绕目标推进任务 |
| Prompt vs Message | Message 是单个角色的一条消息;Prompt 是一次请求的完整输入容器 |
| Memory vs 上下文窗口 | Memory 是应用保存的历史数据;上下文是本次请求实际发送的 Token 上限 |
| Tool vs MCP vs Skills | Tool 是统一调用接口;MCP 是连接外部工具的协议;Skills 是含脚本和资源的能力包 |
| RAG vs 模型微调 | RAG 在请求时注入外部上下文,不改模型参数;微调改参数,但不适合频繁更新事实知识 |
建议学习路径 🚀
- 从 快速开始 完成同步/流式模型调用;
- 读懂 Message、Prompt 与 Memory,理解上下文如何构造;
- 用 Function Call 让模型调用一个真实 Java 方法;
- 按任务选择 Agent 智能体、MCP 或 Skills;
- 需要企业知识时接入 RAG 或 Text2SQL;
- 上线前补齐 Model Router 与可观测性。
掌握这些概念边界后,Agents-Flex 就不再是一串零散 API,而是一组可以按任务复杂度逐步组合的 Java AI 构件 🧩。




