米喜1. McpAgentExecutor：Java 开发者实现 AI 多步工具调用的高效方案
作为一名长期深耕企业级 Java 开发的工程师，我一直在探索如何将 AI 能力无缝集成到现有系统中。最近在 j-langchain 项目中发现的 McpAgentExecutor 组件，彻底改变了我们处理多步工具调用的方式。这个工具的核心价值在于：用不到 10 行代码就能实现原本需要 60 行样板代码才能完成的多步推理流程，而且完全保留了底层 Function Calling 机制的灵活性。
在实际项目中，我们经常遇到这样的场景：AI 需要先查询用户 IP，再根据位置获取天气，最后结合业务规则给出建议。传统实现需要手动处理工具调用循环、结果解析和状态维护，而 McpAgentExecutor 将这些繁琐工作全部封装，开发者只需关注三个核心要素：
- 选择支持 Function Calling 的 LLM 模型
- 配置 MCP 工具组
- 设计清晰的系统提示词
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心设计与实现原理
2.1 底层架构解析
McpAgentExecutor 的架构设计遵循了"约定优于配置"的原则。其核心工作流程可以分为四个阶段：
-
初始化阶段：
- 加载指定工具组的 JSON Schema
- 注册到 LLM 的 Function Calling 能力中
- 构建包含系统提示的初始对话上下文
-
推理循环阶段：
- 模型根据当前上下文判断是否需要调用工具
- 自动解析 ToolCall 对象并执行对应的 MCP 工具
- 将执行结果封装为 Observation 并合并到上下文
-
终止判断阶段：
- 检查是否达到最大迭代次数
- 验证模型是否返回最终答案
- 处理异常情况（如工具调用失败）
-
结果返回阶段：
- 提取模型生成的最终响应
- 触发预设的回调函数（如日志记录）
这个架构最精妙之处在于完全保留了 LangChain 的底层能力，同时提供了更高层次的抽象。当我们需要深度定制时，仍然可以回退到手写 Function Calling 循环的模式。
2.2 关键技术实现
在代码层面，McpAgentExecutor 主要解决了以下几个技术难点：
工具描述自动生成：
java复制// 从 MCP 配置生成 Function Calling 所需的 JSON Schema
List<FunctionDefinition> tools = mcpManager.getToolGroup(group)
.stream()
.map(tool -> new FunctionDefinition(tool.getName(), tool.getDescription(), tool.getParameters()))
.collect(Collectors.toList());
多轮对话状态管理：
java复制// 维护对话历史的实现片段
List<ChatMessage> messages = new ArrayList<>();
messages.add(SystemMessage.of(systemPrompt));
messages.add(UserMessage.of(userInput));
while (iterations < maxIterations) {
ChatGeneration generation = llm.generate(messages);
if (!generation.requiresToolCall()) {
return generation;
}
// 处理 ToolCall 和 Observation...
}
异常处理机制：
java复制try {
Object result = mcpManager.runForInput(toolCall.getFunction(), toolCall.getArguments());
messages.add(ToolMessage.of(toolCall.getId(), result));
} catch (Exception e) {
messages.add(ToolMessage.of(toolCall.getId(), "Error: " + e.getMessage()));
}
3. 完整使用指南与最佳实践
3.1 基础配置步骤
要快速启用 McpAgentExecutor，只需完成以下四个步骤：
-
准备 MCP 工具配置：
在项目的 resources 目录下创建mcp.config.json，定义工具组：json复制{ "network": ["get_export_ip", "get_ip_location"], "weather": ["get_weather_open_meteo"] } -
初始化 McpManager：
java复制McpManager mcpManager = McpManager.loadFromClasspath("/mcp.config.json"); -
构建 Agent 实例：
java复制McpAgentExecutor agent = McpAgentExecutor.builder(chainActor) .llm(ChatAliyun.builder().model("qwen3.6-plus").build()) .tools(mcpManager, "network") .systemPrompt("你是一个网络诊断助手...") .maxIterations(5) .build(); -
执行查询：
java复制ChatGeneration result = agent.invoke("我的公网IP是多少？"); System.out.println(result.getText());
3.2 高级配置技巧
动态工具组切换：
对于复杂场景，可以在运行时根据条件切换工具组：
java复制.onToolCall(toolCall -> {
if (needWeatherTools(toolCall)) {
agent.switchToolGroup("weather");
}
})
上下文感知提示：
通过变量注入使系统提示更智能：
java复制String userName = getCurrentUser();
.systemPrompt(String.format("你是%s的专属助手...", userName))
性能调优参数：
java复制.maxIterations(8) // 复杂任务适当增加
.llm(ChatAliyun.builder()
.model("qwen3.6-plus")
.temperature(0.3) // 创造性任务可调高
.topP(0.9)
.build())
4. 实战案例解析
4.1 网络诊断助手实现
下面展示一个完整的网络诊断场景实现：
java复制public class NetworkDiagnosticAgent {
private McpAgentExecutor agent;
public void init() {
this.agent = McpAgentExecutor.builder(chainActor)
.llm(ChatAliyun.builder().model("qwen3.6-plus").build())
.tools(loadTools(), "full_network")
.systemPrompt("""
你是一个专业网络诊断助手，可以执行以下操作：
1. 检测公网IP和地理位置
2. 测试到目标地址的网络延迟
3. 分析DNS解析结果
请根据用户问题选择合适工具，最终给出诊断报告。
""")
.maxIterations(6)
.onToolCall(this::logToolUsage)
.build();
}
public String diagnose(String question) {
return agent.invoke(question).getText();
}
private void logToolUsage(ToolCall toolCall) {
auditService.recordToolCall(
getCurrentUser(),
toolCall.getFunction(),
toolCall.getArguments());
}
}
执行示例：
java复制String report = new NetworkDiagnosticAgent()
.diagnose("帮我检查到 example.com 的网络状况");
可能的输出流程：
code复制>> Tool call: get_export_ip → 203.156.34.12
>> Tool call: get_ip_location → {"city": "Shanghai", "isp": "China Telecom"}
>> Tool call: ping_target → {"host": "example.com", "avg_latency": 148ms}
>> Tool call: dns_lookup → {"a_record": "93.184.216.34"}
=== 诊断报告 ===
您的网络出口位于上海(中国电信)，到 example.com 平均延迟148ms，
DNS解析结果为93.184.216.34，网络状况良好。
4.2 企业CRM集成案例
在企业CRM系统中，我们可以构建智能查询代理：
java复制public class CrmAgent {
public static void main(String[] args) {
McpAgentExecutor agent = McpAgentExecutor.builder(chainActor)
.llm(ChatOpenAI.builder().model("gpt-4").build())
.tools(loadCrmTools(), "crm_ops")
.systemPrompt("""
你是CRM系统智能助手，可以：
- 查询客户资料(需授权)
- 检索订单历史
- 生成销售报表
注意：涉及客户隐私信息时必须验证权限。
""")
.maxIterations(4)
.build();
String answer = agent.invoke(
"查询客户张三最近的订单金额总和").getText();
}
}
关键设计要点：
- 在工具实现层添加权限校验
- 对敏感操作记录完整审计日志
- 使用单独的CRM工具组隔离权限
5. 性能优化与问题排查
5.1 常见问题解决方案
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 工具未被调用 | 1. 工具未在配置组中 2. 模型不理解需求 |
1. 检查mcp.config.json 2. 优化systemPrompt |
| 无限循环 | 1. maxIterations设置过大 2. 模型无法终止 |
1. 设置合理上限(5-8) 2. 在systemPrompt中明确终止条件 |
| 参数解析失败 | 1. JSON格式错误 2. 参数类型不匹配 |
1. 检查工具参数schema 2. 添加参数校验逻辑 |
| 响应速度慢 | 1. 工具执行耗时 2. 模型响应延迟 |
1. 添加工具超时机制 2. 使用更快的LLM模型 |
5.2 性能优化技巧
批量工具注册：
对于大型工具集，采用分组懒加载：
java复制.tools(mcpManager, "essential") // 先加载核心工具
.onToolCall(tc -> {
if (needAdvancedTools(tc)) {
agent.loadAdditionalTools("advanced");
}
})
缓存策略：
对耗时的工具调用结果进行缓存：
java复制.executeMcpTool(msg -> {
String cacheKey = buildCacheKey(toolCall);
if (cache.has(cacheKey)) {
return cache.get(cacheKey);
}
Object result = mcpManager.runForInput(...);
cache.set(cacheKey, result);
return result;
})
异步处理：
对IO密集型工具采用异步执行：
java复制.onToolCallAsync(toolCall ->
CompletableFuture.supplyAsync(() ->
mcpManager.runForInput(toolCall.getFunction(),
toolCall.getArguments())))
6. 扩展应用场景
6.1 与Spring框架集成
在Spring Boot应用中，我们可以将McpAgentExecutor声明为Bean：
java复制@Configuration
public class AiAgentConfig {
@Bean
public McpAgentExecutor customerServiceAgent(
ChainActor chainActor,
McpManager mcpManager) {
return McpAgentExecutor.builder(chainActor)
.llm(openAiChatModel())
.tools(mcpManager, "customer_service")
.systemPrompt(customerServicePrompt())
.maxIterations(5)
.build();
}
@Bean
public McpAgentExecutor dataAnalysisAgent(
ChainActor chainActor,
McpManager mcpManager) {
return McpAgentExecutor.builder(chainActor)
.llm(aliyunChatModel())
.tools(mcpManager, "data_analysis")
.systemPrompt(dataAnalysisPrompt())
.maxIterations(8)
.build();
}
}
6.2 多Agent协作系统
构建多个专业Agent协同工作的系统：
java复制public class AgentOrchestrator {
private Map<String, McpAgentExecutor> agents;
public String handleRequest(String domain, String query) {
McpAgentExecutor agent = agents.get(domain);
if (agent == null) {
agent = defaultAgent;
}
ChatGeneration result = agent.invoke(query);
if (result.requiresTransfer()) {
return transferToOtherAgent(result);
}
return result.getText();
}
}
这种架构下，每个Agent专注于特定领域，通过路由机制实现复杂业务流程。
7. 安全与权限管理
在企业环境中使用时，必须考虑以下安全措施：
工具级权限控制：
java复制.tools(mcpManager, "restricted_tools",
tool -> checkPermission(currentUser, tool))
敏感操作验证：
java复制.onToolCall(toolCall -> {
if (isSensitiveOperation(toolCall)) {
requireApproval(toolCall);
}
return executeWithAudit(toolCall);
})
数据脱敏处理：
java复制.onObservation(obs -> {
auditLog.log(obs);
return maskSensitiveInfo(obs);
})
在实际项目中，我们通常会将这些安全措施实现为可插拔的拦截器，通过Builder模式添加到Agent配置中。
经过多个项目的实践验证，McpAgentExecutor 显著降低了将 AI 能力集成到 Java 应用中的门槛。其设计平衡了易用性和灵活性，既适合快速原型开发，也能满足企业级应用的安全和性能要求。对于已经采用 MCP 协议的系统，这可能是最快捷的 AI 能力升级方案。