假设用户问:
我在上海,10 月有 4 天假期,喜欢自然风景和安静的小城。请推荐一个目的地,并介绍几个主要景点。
把这句话发给大模型,就能得到一段回答。但如果我们希望它先查询候选目的地,再结合天气和景点给出建议,程序就不能在收到第一段文本后直接结束。
它需要辨认模型提出的工具请求,执行对应的 Java 方法,把结果交回模型,然后继续。这篇文章用一个最小旅行示例,把这个过程拆开。
你需要具备 Java 基础,知道 HTTP 请求和 JSON 的基本形式。示例使用 Java 21、Maven 和 Jackson,不引入 Agent 框架。
所有旅行工具都使用教学样例,天气内容是虚构数据。即使接入真实模型,也不代表查询了实际天气、交通或景点营业状态。
1. 先把完整示例跑起来
解压后进入 java-travel-agent 目录:
mvn testmvn 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 方法。
在这个例子中,模型根据已有结果选择下一步,程序负责实际执行与停止条件。这样的结构体现了 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_1tool:候选结果,tool_call_id = call_1assistant:请求天气 call_2,以及景点 call_3tool:天气结果,tool_call_id = call_2tool:景点结果,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 客户端:
@FunctionalInterfaceinterface 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 执行受支持的工具,结果进入历史,模型据此继续判断。把这一轮往返真正写对,再使用框架时,就能理解框架替你管理了哪些事情。
If this article helped you, please share it with others!
Some information may be outdated






