mobile wallpaper 1mobile wallpaper 2mobile wallpaper 3mobile wallpaper 4
2582 words
7 minutes
商城 Agent 实战(二):用 LangChain4j Tool 查询真实商品
2026-08-06
2026-09-28

用户说“找几款华为手机,再看看有没有库存”。模型可以理解关键词和查询意图,但实际有哪些商品、价格多少、哪个 SKU 有货,只能由商城提供。

商品 Tool 的作用,就是把模型提出的查询请求,转换成受限制的 Java 业务调用。模型选择工具,Java 查询数据,模型再组织回答。读完这一篇,应能沿着一次请求解释:数据从哪里来,参数在哪校验,以及怎样证明工具确实执行了。

本文基于 AgentShop 的 PortalProductTools、PortalAiConfig 和商品 Service,按 2026-09-28 源码核对。代码片段聚焦商品查询,完整 Assistant 还包含订单、售后、RAG 与 Memory。

1. Tool Calling 是一次来回,不是模型直接查库#

一次典型的查询过程如下:

用户:查一下华为手机
↓
模型返回工具名与参数
↓
LangChain4j 执行 searchProducts
↓
商品 Service 查询商城
↓
Java 返回精简商品数据
↓
模型读取结果,生成中文答案

模型返回的是“调用哪个工具、使用什么参数”的结构化请求,不是已经查询完成的商品。Java 执行之后,还要把结果发回模型。

例如,工具请求可以包含:

{
"name": "searchProducts",
"arguments": {
"keyword": "华为",
"pageNum": 1,
"pageSize": 5
}
}

这是方便阅读的请求示意,不是供应商原始响应,也不是完整 JSON Schema。框架根据 Java 方法上的 @Tool、参数类型和 @P 生成模型可见的工具描述,再负责执行与结果回传。LangChain4j Tools

一次用户请求可能调用模型多次,因此要分别计算模型调用耗时、工具耗时和总耗时。

2. 先把工具设计成三个业务问题#

当前商品工具有三个:

工具回答的问题
searchProducts哪些商品符合关键词?
getProductDetail这个商品的基本信息是什么?
getProductStock这个商品有哪些库存信息?

它们都留在 mall-portal,调用已有 PmsPortalProductService。共享模块 mall-ai 提供模型基础能力,不依赖前台的具体商品逻辑。

PortalAiAssistantController
→ PortalAssistant
→ PortalProductTools
→ PmsPortalProductService
→ Mapper / 数据库

同一个应用内不需要让 Tool 绕回 Controller 或重新发一遍 HTTP 请求。Controller 与 Tool 是两个入口,业务规则应由它们共同调用的 Service 承担。

工具粒度要让模型容易选择,也便于限制开销。不要直接提供“执行任意 SQL”,也不必把每个 Getter 都变成一个工具。搜索返回候选商品 ID,用户追问具体商品时再查详情,这样每一步的输入和结果都明确。

3. 参数描述帮助模型,Java 校验限制实际执行#

搜索方法公开三个参数:

@Tool("Search published AgentShop products by keyword.")
public String searchProducts(
@P("Product keyword") String keyword,
@P("Page number, starts from 1") Integer pageNum,
@P("Page size, at most 5") Integer pageSize) {
// 校验、查询和 DTO 转换见下文
}

这是缩减后的签名示意。实际限制不能停留在描述文字中。当前实现将页码限制在 1~100,每页最多 5 条,关键词最多 50 个字符。页大小的处理是:

private int sanitizePageSize(Integer pageSize) {
if (pageSize == null || pageSize < 1) {
return 5;
}
return Math.min(pageSize, 5);
}

空关键词先返回输入问题,不进行无条件全库搜索。商品 ID 也需要检查是否为有效正数。

限制后的实际参数应体现在结果里,让模型知道自己拿到的是第几页、多少条。静默把“我要 1000 条”改成 5 条,却让回答声称列出了全部商品,会产生另一种误导。

Tool 输入是外部请求数据:即使它由模型生成,也需要长度、范围和业务合法性校验。

4. 可见商品范围不能只写在工具说明里#

搜索 Service 的查询条件包含:

criteria.andDeleteStatusEqualTo(0);
criteria.andPublishStatusEqualTo(1);

这决定了前台搜索只返回未删除、已发布的商品。

详情和库存按商品 ID 读取,不能因为模型“正常应该只使用搜索结果里的 ID”,就忽略可见性检查。用户可以直接提供 ID,模型也可能从旧历史中取得已经下架的 ID。

当前 Tool 会检查商品的删除和发布状态;不可见商品不应继续把 SKU、详情和内部信息交给模型。若多个业务入口都依赖这条规则,最好让可见性约束成为 Service 的统一契约,避免每个入口各写一套。

这里要区分两个问题:

  • 能否看这个商品:由当前业务规则判断。
  • 数据库是否成功返回:属于运行状态。

查询异常不能随意改写成“商城没有该商品”,否则用户会把系统故障当作真实搜索结果。

5. DTO 决定模型看见哪些数据#

直接序列化 PmsProduct 或完整商品详情,会把很多与回答无关的字段送进上下文,也会让数据库结构变化影响模型行为。

当前 ProductToolDtos 提供摘要、详情和库存结果。搜索摘要主要包含商品 ID、名称、品牌、价格、库存等字段。对于一句“查几款手机”,应优先提供足够比较和继续查询的信息。

一个用于说明的搜索结果可以是:

{
"keyword": "华为",
"pageNum": 1,
"pageSize": 5,
"returnedCount": 1,
"products": [
{
"productId": 1001,
"name": "示例手机",
"price": 3999.00,
"stock": 20
}
]
}

这是裁剪后的演示数据,不代表商城真实商品。DTO 中没有需要回答的字段,就不应让模型凭空补充。

价格字段尤其需要解释清楚:商品标价、促销价和最终结算价不是同一概念。只有查询和校验了活动条件,才能向用户承诺优惠后的价格;实际支付金额仍以结算服务为准。

6. 明细可以截断,汇总口径要保持完整#

一个商品可能有 20 个 SKU。把所有明细发送给模型成本较高,因此当前工具最多展示 10 条,但总库存应基于完整 SKU 列表计算。

完整 SKU 列表
├─ 汇总可用库存
└─ 裁剪前 10 条作为展示明细

响应同时表达截断情况:

{
"availableStock": 180,
"skuCount": 20,
"returnedSkuCount": 10,
"skuDetailsTruncated": true
}

这些数字是示例,重点是“总数量”与“当前展示数量”分别有字段。如果先截断再求和,就会把局部明细错误地当成总库存。

项目根据 stock 与 lockStock 计算 SKU 可用量,缺少 SKU 数据时使用商品库存作为回退。回答需要说明查询口径,不能把商品总数当作用户选定颜色、容量的可售数量。

库存查询也不是库存预留。查询时有 20 件,不代表稍后下单一定成功;下单服务仍需以提交时的库存约束为准。

7. 工具注册决定模型能请求哪些能力#

只演示商品能力时,绑定结构可以简化为:

PortalAssistant assistant =
AiServices.builder(PortalAssistant.class)
.chatModel(chatModel)
.tools(portalProductTools)
.maxToolCallingRoundTrips(3)
.build();

这是说明绑定关系的片段,不是当前 PortalAiConfig 的完整替换版本。当前完整配置还注册了订单和售后工具,并将往返上限设为 5。

往返上限控制的是工具交互轮数,不能把它直接理解成“最多执行 3 个 Java 方法”:一次模型响应可能请求多个工具。总时间、单个工具预算、结果大小与模型调用费用,仍要独立限制。

商品描述也可能包含与商品无关的指令。去 HTML、清理控制字符和截断长度有助于压缩内容,但不能可靠识别所有提示注入。模型收到的商品文本始终应当作数据;真正可执行的能力由注册的工具、Java 参数校验和 Service 规则限制。

前台 Assistant 不应注册后台商品编辑或全量订单管理工具。与其要求模型“不要使用”,更可靠的是前台根本不提供这些能力。

8. 三层测试分别能证明什么#

Tool 方法测试#

Mock 商品 Service,直接调用 Tool,检查参数限制、可见性、DTO 字段和 SKU 截断。它能证明 Java 逻辑是否符合约定,但还没有经过模型和框架。

特别要覆盖“20 个 SKU、只返回 10 个明细”的场景,断言汇总依旧使用全部 SKU。

框架协议测试#

使用可控的假 ChatModel,第一轮返回 searchProducts 请求,第二轮检查是否收到 ToolExecutionResultMessage,再返回固定答案。

这能证明工具已注册、参数能绑定、Java 方法执行后结果能回到模型。假模型已经被安排选择这个工具,因此不能证明真实 DeepSeek 会正确选择工具。

项目中的 PortalAssistantToolCallingTest 适合检查这条协议链。

真实模型评测#

准备一组真实表达,例如“华为手机有哪些”“第二款有货吗”“查一个不存在的商品”。观察实际工具名、参数、返回商品 ID 与最终答案是否一致。

不要只检查回答包含“已查询”三个字。模型可以说自己查过,却没有发生工具调用;反过来,工具正常返回,也不保证最终答案没有改错价格。

9. 用当前入口复现商品查询#

前台仍调用 POST /ai/portal/chat,携带有效会员登录态:

{
"conversationId": "product-demo",
"message": "查一下华为手机,并告诉我具体商品 ID"
}

然后在同一会话追问某个真实返回的商品 ID。检查三个结果是否对应:

  1. 工具轨迹中的查询参数。
  2. Tool Result 中的商品、价格与库存。
  3. 最终答案中的具体字段。

当前接口的 data 是包含 conversationId 与 answer 的对象,旧 /ai/chat 已移除,接入方式见模型接入篇。

本文核对了源码和现有测试结构,没有重新执行真实模型评测。商品查询连通以后,涉及“我的订单”的问题还需要订单归属约束,不能直接复用公开商品的访问方式。

Share

If this article helped you, please share it with others!

商城 Agent 实战(二):用 LangChain4j Tool 查询真实商品
https://github.com/huanchenfeng/agentShop
Author
梦幻晨风
Published at
2026-08-06
License
CC BY-NC-SA 4.0

Some information may be outdated

Table of Contents