Java 程序员第 20 阶段：Agent 工具调用开发，对接第三方接口自动任务
作者：洛水石
标签：Java，大模型，Agent，工具调用
时间：2026-05-19
概述
在大模型Agent架构中，工具调用（Tool Use）是实现自主任务执行的核心能力。通过定义标准化的Tool接口，Agent能够调用各类外部工具——从简单的计算器到复杂的第三方REST API——完成单靠大模型无法胜任的任务。本篇文章聚焦Java后端视角，讲解Tool接口设计、第三方API对接、工具注册与调用机制的完整实现。
一、Tool接口核心设计
1.1 为什么要定义Tool接口
大模型本身具备强大的推理能力，但无法直接与外部系统交互。通过Tool接口，我们将外部能力封装为Agent可调用的"技能"。当用户提出需要实时数据或外部操作的需求时，Agent通过Function Calling机制选择合适的工具并执行。
一个设计良好的Tool接口需要包含以下元信息：
-name：工具唯一标识符，供Agent识别和选择
-description：工具功能描述，帮助LLM理解何时该调用此工具
-parameters：参数schema，定义LLM需要传递哪些参数
-invoke()：核心执行方法，执行业务逻辑并返回结果
1.2 Tool接口定义
``__INLINE_java
public interface Tool {
String getName();
String getDescription();
String getParameters(); // JSON Schema
ToolResult invoke(Map<String, Object> params);
}
__`__INLINE_
ToolResult为执行结果的封装类：
__`__INLINE_java
public class ToolResult {
private boolean success;
private String output;
private String error;
public ToolResult(boolean success, String output) {
this.success = success;
this.output = output;
}
// getters...
}
__`__INLINE_
1.3 工具分类
根据实现复杂度，工具可分为三类：
-轻量工具：计算器、日期查询、字符串处理等纯本地逻辑
-API工具：调用第三方REST API获取数据
-编排工具：组合多个工具完成复杂任务
图1：Tool 接口核心架构
二、第三方API对接实战
2.1 API工具设计模式
第三方API工具需要处理认证、请求构建、响应解析等环节。建议采用模板方法模式，将通用逻辑抽取到抽象基类：
__`__INLINE_java
public abstract class ApiTool implements Tool {
protected abstract String getBaseUrl();
protected abstract Map<String, String> getHeaders();
protected abstract String buildPath(Map<String, Object> params);
protected abstract ToolResult parseResponse(String response);
@Override
public ToolResult invoke(Map<String, Object> params) {
try {
String url = getBaseUrl() + buildPath(params);
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.headers(getHeaders().entrySet().stream()
.flatMap(e -> Stream.of(e.getKey(), e.getValue()))
.toArray(String[]::new))
.GET()
.build();
HttpResponse<String> response = httpClient.send(request,
HttpResponse.BodyHandlers.ofString());
return parseResponse(response.body());
} catch (Exception e) {
return new ToolResult(false, null, e.getMessage());
}
}
}
__`__INLINE_
2.2 认证机制处理
不同第三方API的认证方式各异，常见的有：
-API Key认证：在请求头或参数中携带key
-OAuth 2.0：获取access_token后携带在Authorization头
-JWT认证：使用预生成的token
__`__INLINE_java
public class OAuthTool extends ApiTool {
private String clientId;
private String clientSecret;
private String accessToken;
@Override
protected Map<String, String> getHeaders() {
Map<String, String> headers = new HashMap<>();
headers.put("Authorization", "Bearer " + accessToken);
headers.put("Content-Type", "application/json");
return headers;
}
// token刷新逻辑
public void refreshToken() {
// 调用OAuth token接口刷新access_token
}
}
__`__INLINE_
2.3 天气预报工具实现
以天气查询为例，展示完整的API工具实现：
__`__INLINE_java
public class WeatherTool extends ApiTool {
private static final String BASE_URL = "https://api.weather.example.com/v1";
private final String apiKey;
public WeatherTool(String apiKey) {
this.apiKey = apiKey;
}
@Override
public String getName() {
return "weather";
}
@Override
public String getDescription() {
return "查询指定城市的实时天气信息，返回温度、湿度、风力等数据";
}
@Override
public String getParameters() {
return """
{
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名称，如：北京、上海"}
},
"required": ["city"]
}
""";
}
@Override
protected String buildPath(Map<String, Object> params) {
String city = (String) params.get("city");
return "/weather?city=" + URLEncoder.encode(city, StandardCharsets.UTF_8)
+ "&apikey=" + apiKey;
}
@Override
protected ToolResult parseResponse(String response) {
try {
JSONObject json = new JSONObject(response);
String temp = json.getJSONObject("data").getString("temperature");
String humidity = json.getJSONObject("data").getString("humidity");
String result = String.format("温度：%s，湿度：%s", temp, humidity);
return new ToolResult(true, result);
} catch (JSONException e) {
return new ToolResult(false, null, "解析天气数据失败：" + e.getMessage());
}
}
}
__`__INLINE_
图2：第三方 API 对接流程
三、工具注册与调用机制
3.1 工具注册中心
工具注册中心负责管理所有可用工具的元信息，供Agent在决策时查询：
__`__INLINE_java
public class ToolRegistry {
private final Map<String, Tool> tools = new ConcurrentHashMap<>();
public void register(Tool tool) {
tools.put(tool.getName(), tool);
}
public void unregister(String name) {
tools.remove(name);
}
public Tool get(String name) {
return tools.get(name);
}
public List<Tool> getAll() {
return new ArrayList<>(tools.values());
}
// 获取所有工具的schema，用于LLM理解可用工具
public String getToolSchemas() {
return getAll().stream()
.map(tool -> String.format("""
{
"name": "%s",
"description": "%s",
"parameters": %s
}
""", tool.getName(), tool.getDescription(), tool.getParameters()))
.collect(Collectors.joining(",", "[", "]"));
}
}
__`__INLINE_
3.2 工具选择策略
当Agent需要执行任务时，根据LLM的Function Calling结果选择对应工具。常见的策略有：
-精确匹配：LLM直接指定工具名
-语义匹配：通过embedding相似度匹配最相关的工具
-意图分类：先做意图分类，再匹配对应类别的工具
__`__INLINE_java
public class ToolSelector {
private final ToolRegistry registry;
private final LlmClient llmClient;
public ToolSelection select(String userQuery) {
String schemas = registry.getToolSchemas();
// 构建Prompt让LLM选择工具
String prompt = String.format("""
用户需求：%s
可用工具：%s
请选择最合适的工具并提取参数。
""", userQuery, schemas);
String llmResponse = llmClient.chat(prompt);
// 解析LLM返回的工具调用指令
return parseToolCall(llmResponse);
}
}
__`__INLINE_
3.3 工具执行器
执行器负责调用被选中的工具，并处理执行过程中的异常：
__`__INLINE_java
public class ToolExecutor {
private final ToolRegistry registry;
private final Map<String, Object> context = new ConcurrentHashMap<>();
public ToolResult execute(String toolName, Map<String, Object> params) {
Tool tool = registry.get(toolName);
if (tool == null) {
return new ToolResult(false, null, "未找到工具：" + toolName);
}
try {
// 执行前拦截
preInvoke(toolName, params);
// 调用工具
ToolResult result = tool.invoke(params);
// 执行后拦截
postInvoke(toolName, result);
return result;
} catch (Exception e) {
return new ToolResult(false, null, "执行异常：" + e.getMessage());
}
}
private void preInvoke(String toolName, Map<String, Object> params) {
// 日志记录、参数校验等
log.info("执行工具：{}，参数：{}", toolName, params);
}
private void postInvoke(String toolName, ToolResult result) {
// 结果缓存、监控埋点等
if (result.isSuccess()) {
log.info("工具执行成功：{}，结果：{}", toolName, result.getOutput());
} else {
log.error("工具执行失败：{}，错误：{}", toolName, result.getError());
}
}
}
__`__INLINE_
图3：工具注册与调用机制
四、自动任务执行集成
4.1 ReAct模式下的工具调用
ReAct（Reasoning + Acting）模式将推理和执行交替进行：
1.Thought：分析当前情况，决定下一步行动
2.Action：选择并执行工具
3.Observation：获取工具返回结果
4.重复直到任务完成
__`__INLINE_java
public class ReActAgent {
private final LlmClient llmClient;
private final ToolExecutor toolExecutor;
public String run(String task) {
String history = "";
String currentInput = task;
for (int i = 0; i < maxIterations; i++) {
// 构建ReAct Prompt
String prompt = buildReActPrompt(task, history);
// LLM推理下一步行动
LlmResponse response = llmClient.chat(prompt);
if (response.isFinalAnswer()) {
return response.getAnswer();
}
// 解析并执行工具
ToolCall toolCall = response.getToolCall();
ToolResult result = toolExecutor.execute(
toolCall.getToolName(),
toolCall.getParameters()
);
// 更新历史
history += response.getThought() + "\n";
history += "Action: " + toolCall.getToolName() + "\n";
history += "Observation: " + result.getOutput() + "\n";
}
return "任务执行超时";
}
}
__`__INLINE_
4.2 异步任务处理
对于耗时的API调用，建议采用异步处理避免阻塞：
__`__INLINE_java
public class AsyncToolExecutor {
private final ToolRegistry registry;
private final ExecutorService executor = Executors.newCachedThreadPool();
public CompletableFuture<ToolResult> executeAsync(
String toolName, Map<String, Object> params) {
return CompletableFuture.supplyAsync(() -> {
Tool tool = registry.get(toolName);
if (tool == null) {
return new ToolResult(false, null, "未找到工具");
}
return tool.invoke(params);
}, executor);
}
}
__`__INLINE_
4.3 任务队列集成
生产环境中，工具调用通常接入消息队列实现削峰填谷：
__`__INLINE_java
public class QueuedToolExecutor {
private final BlockingQueue<ToolTask> taskQueue;
private final ToolExecutor executor;
@PostConstruct
public void start() {
IntStream.range(0, 10).forEach(i -> {
Executors.newSingleThreadExecutor().submit(() -> {
while (true) {
try {
ToolTask task = taskQueue.take();
ToolResult result = executor.execute(
task.getToolName(), task.getParams());
task.getCallback().accept(result);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
break;
}
}
});
});
}
public void submit(ToolTask task) {
taskQueue.offer(task);
}
}
__``
五、最佳实践与注意事项
5.1 工具设计原则
-单一职责：每个工具只做一件事，保持功能内聚
-幂等性：相同参数多次调用应返回一致结果
-超时控制：API调用必须设置合理的超时时间
-错误处理：区分可重试错误和不可重试错误
5.2 安全考虑
-敏感信息：API密钥等敏感信息不要硬编码，使用配置中心或密钥管理服务
-参数校验：严格校验LLM传来的参数，防止注入攻击
-调用限流：对第三方API调用进行限流，保护下游服务
5.3 性能优化
-结果缓存：对于相同参数的请求，缓存结果避免重复调用
-连接复用：使用HTTP连接池复用TCP连接
-批量接口：如第三方API支持批量查询，优先使用批量接口
图4：Java Tool 接口实现示例
六、总结
本文详细讲解了Agent工具调用开发的核心组件：Tool接口设计、第三方API对接方案、工具注册与调用机制。通过Java实现示例，展示了从接口定义到生产环境部署的完整链路。掌握这些内容后，开发者能够构建出可对接任意外部系统的智能Agent，实现复杂的自动化任务。
工具调用能力是大模型Agent与现实世界交互的桥梁，合理的设计能让Agent的能力得到充分发挥。希望本文能为你的Agent开发提供有价值的参考。
作者：洛水石
作者：洛水石