mobile wallpaper 1mobile wallpaper 2mobile wallpaper 3mobile wallpaper 4
3086 words
8 minutes
从普通对话到 Agent:用 Java 实现一个最小旅行推荐 Agent
2026-05-15
2026-09-27

假设用户问:

我在上海,10 月有 4 天假期,喜欢自然风景和安静的小城。请推荐一个目的地,并介绍几个主要景点。

把这句话发给大模型,就能得到一段回答。但如果我们希望它先查询候选目的地,再结合天气和景点给出建议,程序就不能在收到第一段文本后直接结束。

它需要辨认模型提出的工具请求,执行对应的 Java 方法,把结果交回模型,然后继续。这篇文章用一个最小旅行示例,把这个过程拆开。

你需要具备 Java 基础,知道 HTTP 请求和 JSON 的基本形式。示例使用 Java 21、Maven 和 Jackson,不引入 Agent 框架。

所有旅行工具都使用教学样例,天气内容是虚构数据。即使接入真实模型,也不代表查询了实际天气、交通或景点营业状态。

1. 先把完整示例跑起来#

下载完整 Java 示例

解压后进入 java-travel-agent 目录:

mvn test
mvn compile exec:java

首次运行需要联网下载 Maven 依赖;依赖准备好以后,默认演示本身不访问模型 API,也不需要 API Key。

主要文件只有三个:

java-travel-agent/
├── pom.xml
├── src/main/java/example/TravelAgent.java
└── src/test/java/example/TravelAgentTest.java

为方便从头阅读,工具、模型适配器和循环都放在 TravelAgent.java 的内部类型与方法中。实际项目可以在职责稳定后再拆文件。

默认运行的轨迹如下,工具结果在这里省略了部分字段:

OFFLINE SCRIPTED DEMO
[turn 1]
search_destinations -> 候选:腾冲、婺源
[turn 2]
get_weather -> 虚构天气样例
get_attractions -> 和顺古镇、北海湿地、火山地质公园
[turn 3]
【离线脚本演示,非真实旅行建议】……

这一步使用的是 ScriptedModel:它按预先写好的顺序返回工具调用和最终文本,用于验证程序能否正确处理消息。它不是大模型,也不具备自主选择目的地的能力。

后面接入真实模型时,保留工具和循环,只替换模型实现。这样可以把“程序的控制逻辑是否正确”和“模型的决策质量如何”分开检查。

2. 从普通对话到工具调用,多了哪一步#

普通对话的流程很短:程序发送问题,模型返回文本,程序展示文本。

工具调用多出了一次往返。模型可能先返回“请调用天气工具,并传入这些参数”,由程序真正执行工具。模型本身并不会直接调用你的 Java 方法。

flowchart TD A[用户问题与消息历史] --> B[请求模型] B --> C{返回内容} C -->|工具请求| D[校验参数并执行 Java 工具] D --> E[记录工具结果] E --> B C -->|最终文本| F[返回回答] C -->|异常或超出限制| G[停止并报告原因]

在这个例子中,模型根据已有结果选择下一步,程序负责实际执行与停止条件。这样的结构体现了 Agent 的一种常见实现方式,但不必把“有循环”当成 Agent 的严格定义。

如果业务规定永远按“查目的地、查天气、查景点”的固定顺序执行,直接编排工作流也很合适。这里保留模型决策,是为了学习工具调用循环本身。

OpenAI 的工具调用文档分别介绍了 Responses API 和 Chat Completions 的消息形式。本文选择后者,使用 messages、tool_calls 和 tool_call_id;其他 API 的结构不能直接混用。来源:Function calling

3. 先定义工具能做什么#

示例提供三个工具:

工具用途
search_destinations按月份和偏好查询候选样例
get_weather读取目的地的天气样例
get_attractions根据天数截取景点样例

工具需要同时提供两部分内容:给模型看的定义,以及 程序执行的实现。

以天气工具为例,下面的 JSON 是发送给模型的工具定义:

{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询教学天气样例,绝非实时天气或实际气候统计。",
"strict": true,
"parameters": {
"type": "object",
"properties": {
"destination": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"month": {
"type": "integer",
"minimum": 1,
"maximum": 12
}
},
"required": ["destination", "month"],
"additionalProperties": false
}
}
}

名字用于分派到对应实现,描述帮助模型判断用途,参数定义说明需要哪些输入。把“模拟数据”写进描述,是为了让模型在选择工具时就知道它的能力范围。

strict 用于约束参数结构,但 Java 仍然要检查业务条件。符合 JSON Schema 的“北京、10 月”也可能不在这个小型演示库里。

示例没有为未知城市编造结果,而是返回:

{
"ok": false,
"code": "NO_DEMO_DATA",
"message": "该目的地或月份没有教学天气数据"
}

这里区分了两种情况:“参数格式错误”意味着可以修正调用,“数据不存在”意味着当前工具无法回答。若都返回一段貌似合理的天气描述,模型就失去了判断依据。

4. 看懂一次调用的消息往返#

模型请求天气工具时,会返回类似的 assistant 消息:

{
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_2",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"destination\":\"腾冲\",\"month\":10}"
}
}
]
}

注意 arguments 是一个包含 JSON 的 字符串。Java 要先读取这个字符串,再把它解析成对象,而不是直接对字符串节点读取 destination。

执行工具后,程序追加一条结果消息:

{
"role": "tool",
"tool_call_id": "call_2",
"content": "{\"ok\":true,\"simulated\":true,\"destination\":\"腾冲\",\"month\":10,\"weather\":\"虚构天气样例:多云,安排户外活动时准备雨具。\"}"
}

tool_call_id 必须对应原请求的 id,这样模型才能知道这份结果属于哪次调用。原来的 assistant 工具请求也必须保留在历史中。

因此,第二轮请求结束后,消息历史可能长这样:

system:回答规则和工具数据限制
user:上海出发,10 月,4 天,喜欢自然和安静
assistant:请求候选目的地,id = call_1
tool:候选结果,tool_call_id = call_1
assistant:请求天气 call_2,以及景点 call_3
tool:天气结果,tool_call_id = call_2
tool:景点结果,tool_call_id = call_3

模型下一轮看到的是整个过程,而不只是最后一条景点清单。

5. 工具由程序分派,参数由程序检查#

工具注册表只允许执行已经定义的 Java 实现。在示例中,execute 方法先按名称找到工具,再检查参数:

String name = call.path("function").path("name").asText();
Tool tool = tools.stream()
.filter(t -> t.name().equals(name))
.findFirst()
.orElse(null);
if (tool == null) {
return error("UNKNOWN_TOOL", "未注册工具:" + name);
}

以上是完整方法中的分派片段。后续步骤会解析 arguments,拒绝缺失或多余的字段,再由工具检查具体的值。

例如,月份不能只用 asInt() 读取后直接使用,因为字符串、缺失值和小数需要被明确区分。示例使用:

static int integer(JsonNode args, String field, int min, int max) {
JsonNode value = args.get(field);
if (value == null || !value.isIntegralNumber() || !value.canConvertToInt()
|| value.intValue() < min || value.intValue() > max) {
throw new IllegalArgumentException(
field + " 必须是 " + min + "—" + max + " 的整数");
}
return value.intValue();
}

参数错误会在分派层转成 INVALID_ARGUMENTS 工具结果,并带原调用编号回填。模型下一轮有机会修改参数。

这里仅把已知的参数错误当作可恢复结果。代码缺陷、HTTP 失败等其他异常会向上抛出,使本次运行停止,避免把程序故障伪装成正常数据。

6. 核心代码:保存历史,执行工具,继续下一轮#

先定义模型接口,使循环不依赖某个具体 HTTP 客户端:

@FunctionalInterface
interface ChatModel {
ObjectNode chat(List<ObjectNode> messages, ArrayNode tools) throws Exception;
}

返回值是一条完整的 assistant 消息。这里直接使用 Jackson 节点,便于对照前面的协议;没有再加一套消息 DTO 映射。

下面是示例工程中的完整循环方法,辅助方法和导入见下载源码:

static String run(ChatModel model, List<Tool> tools, String question, int maxTurns) throws Exception {
if (maxTurns < 1) throw new IllegalArgumentException("maxTurns must be positive");
List<ObjectNode> messages = new ArrayList<>();
messages.add(message("system", SYSTEM));
messages.add(message("user", question));
for (int turn = 1; turn <= maxTurns; turn++) {
System.out.println("[turn " + turn + "]");
List<ObjectNode> snapshot = messages.stream().map(ObjectNode::deepCopy).toList();
ObjectNode assistant = model.chat(snapshot, definitions(tools));
if (!"assistant".equals(assistant.path("role").asText())) {
throw new IllegalStateException("Expected assistant message");
}
JsonNode calls = assistant.get("tool_calls");
if (calls != null && !calls.isNull() && !calls.isArray()) {
throw new IllegalStateException("Malformed tool_calls");
}
if (calls == null || calls.isNull() || calls.isEmpty()) {
if (assistant.path("refusal").isTextual()) {
throw new IllegalStateException("Model refused the request");
}
JsonNode content = assistant.path("content");
if (!content.isTextual() || content.asText().isBlank()) {
throw new IllegalStateException("Empty model response");
}
return content.asText();
}
if (turn == maxTurns) throw new IllegalStateException("Model turn limit reached");
if (calls.size() > 8) throw new IllegalStateException("Too many tool calls in one turn");
Set<String> ids = new HashSet<>();
for (JsonNode call : calls) {
String id = call.path("id").asText();
if (id.isBlank() || !ids.add(id) || !"function".equals(call.path("type").asText())) {
throw new IllegalStateException("Invalid tool call identity or type");
}
}
// Preserve the entire assistant message, including accompanying text and every call ID.
messages.add(assistant.deepCopy());
for (JsonNode call : calls) {
ObjectNode result = execute(call, tools);
System.out.println(" " + call.path("function").path("name").asText() + " -> " + result);
ObjectNode reply = message("tool", result.toString());
reply.put("tool_call_id", call.path("id").asText());
messages.add(reply);
}
}
throw new IllegalStateException("Model turn limit reached");
}

读这段代码时,先抓住四个动作。

第一,保留上下文。 每次请求都带上用户问题、之前的模型调用和工具结果。示例在调用模型前复制消息节点,避免模型适配器意外修改循环保存的历史。

第二,完整保存调用请求。 messages.add(assistant.deepCopy()) 保留整条消息。有些响应会同时带解释文本和工具调用,不能为了提取调用列表把其余内容丢掉。

第三,回填这一轮的所有结果。 模型一次可以请求多个工具。示例按顺序执行并逐一回填,然后才进入下一轮模型请求;没有实现 Java 并发执行。

第四,明确结束。 没有工具请求且存在非空文本,才作为正常回答返回。空响应、拒绝、错误消息结构以及超出限制都会停止运行。

默认 maxTurns = 6,这里的“轮”指模型请求次数,不是工具调用次数。同一轮最多接收 8 个工具请求;最后一轮若仍然要求工具,程序直接停止,不再执行无法继续交回模型的动作。

这使默认运行最多发生 6 次模型请求和 40 次工具执行,但它不是费用预算控制。真实模型的 Token 数、单次响应大小和工具耗时,还需要独立管理。

7. 接入真实模型时,替换哪一部分#

下载包中的 OpenAiChatModel 已补齐请求构造与响应解析,使用 JDK 的 HttpClient 访问:

POST https://api.openai.com/v1/chat/completions

请求包含模型名、消息历史和工具定义。适配器设置连接超时与请求超时,并检查 HTTP 状态和 finish_reason;截断响应不会被当作成功回答。

要使用真实模型,需要在当前进程环境中配置:

  • OPENAI_API_KEY:你自己的 API Key。
  • OPENAI_MODEL:你的账号可用、支持 Chat Completions 工具调用的模型 ID。

环境准备好后运行:

mvn compile exec:java "-Dexec.args=--live"

这一模式会发出真实 API 请求,并可能产生费用。默认不配置模型名,是为了避免把某个会变化的模型选择写死在教程里。

切换的只有模型实现:

ChatModel model = live
? new OpenAiChatModel(
System.getenv("OPENAI_API_KEY"),
System.getenv("OPENAI_MODEL"))
: new ScriptedModel();

候选、天气和景点工具仍然是模拟数据。真实模型可能选择不同工具顺序、不同候选,也可能请求澄清;不能拿离线脚本的固定输出当作真实模型必然产生的结果。

本文源码使用 Chat Completions。若你选用的模型只支持其他 API,需要更换适配器和消息表示,而不只是改一个 URL。接口说明见官方工具调用文档

8. 这个示例验证了什么#

示例包含 12 项自动化测试,重点检查程序应当稳定保证的行为:

检查内容验证目的
直接回答、多个工具正常路径能完成
调用编号与完整消息结果不会错配或丢失
参数错误后修正可恢复错误能够继续
未知工具、缺失数据不执行未注册功能,不造数据
轮数和批量上限重复调用会停止
请求构造、响应解析协议字段与完成状态正确

测试使用脚本模型和固定响应,不访问真实 API。它们能验证循环、分派和解析逻辑,却不能证明模型会给出高质量旅行建议,也不能替代真实服务联调。

本文配套代码已经通过这组测试和默认模式运行;真实模型模式尚未进行在线联调。后续接入时,应另外观察请求成功率、工具选择、参数修正能力,以及模型是否明确说明模拟数据限制。

9. 下一步扩展,优先替换真实数据#

理解了循环,再扩展工具会更容易。可以先把一个天气工具替换成真实数据源,保留清楚的时间范围、查询时间和来源,再检查模型如何使用返回结果。

月份偏好和短期天气预报也需要分开:只有“10 月”无法查询某段明确日期的天气,远期旅行更不能直接套用短期预报。实际产品应该先补齐出行日期,再决定当前数据源能够提供什么。

这个最小示例还没有会话持久化、流式响应、用户取消、重试策略或费用上限。控制流正确只是起点;把它做成真实应用时,需要逐项补上这些运行能力。

回头看,关键已经很清楚:模型提出调用,Java 执行受支持的工具,结果进入历史,模型据此继续判断。把这一轮往返真正写对,再使用框架时,就能理解框架替你管理了哪些事情。

Share

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

从普通对话到 Agent:用 Java 实现一个最小旅行推荐 Agent
https://mizuki.mysqil.com/posts/java-minimal-travel-agent/
Author
梦幻晨风
Published at
2026-05-15
License
CC BY-NC-SA 4.0

Some information may be outdated

Table of Contents