一文读懂Agents-Flex核心概念:ChatModel、Tool、RAG与Agent的完整知识地图

原创2026-10-15 15:13:101,663 阅读

一文读懂Agents-Flex核心概念:ChatModel、Tool、RAG与Agent的完整知识地图

Agents-Flex 是一个轻量级的 Java AI Agent 开发框架(定位对标 Spring AI)。本文将带你一图看懂 ChatModel、Tool、RAG、Agent 四大核心概念如何协同工作,并快速掌握 MCP、Skills、Text2SQL 等扩展能力——这是从"调一次大模型"走向"构建能完成任务的智能体"的完整知识地图 🗺️。

Agents-Flex Java AI智能体开发框架概览

一张图看懂:一次 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 步:

  1. 应用把工具名称、描述和参数 Schema 随 Prompt 发给模型;
  2. 模型返回 ToolCall,说明要调用哪个工具、参数是什么;
  3. ToolExecutor 解析参数并执行对应的 Tool;
  4. 执行结果封装为 ToolMessage 加入对话;
  5. 模型读取结果,继续调用其他工具或生成最终回答。

在 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 保存过程:

Agents-Flex Agent运行时演示:ChatModel工具调用与Agent事件流

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 调用,底层由任务仓库、线程池和异步系统支撑:

Agents-Flex Subagent多智能体任务执行架构图

而 Text2SQL 模块内置只读校验与拦截器链:LLM Agent 调用查询工具后,先做只读安全校验,再依次经过租户隔离、LIMIT 限制、审计等拦截器,最后执行 JDBC 查询:

Text2SQL工具调用与SQL拦截器链执行时序图

相关源码: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:

Agents-Flex Model Router负载均衡与熔断流程图

最易混淆概念速查表 ❓

易混淆点 一句话区分
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 在请求时注入外部上下文,不改模型参数;微调改参数,但不适合频繁更新事实知识

建议学习路径 🚀

  1. 从 快速开始 完成同步/流式模型调用;
  2. 读懂 Message、Prompt 与 Memory,理解上下文如何构造;
  3. 用 Function Call 让模型调用一个真实 Java 方法;
  4. 按任务选择 Agent 智能体、MCP 或 Skills;
  5. 需要企业知识时接入 RAG 或 Text2SQL;
  6. 上线前补齐 Model Router 与可观测性。

掌握这些概念边界后,Agents-Flex 就不再是一串零散 API,而是一组可以按任务复杂度逐步组合的 Java AI 构件 🧩。

登录后查看全文
agents-flex