标签JavaMCPAgentj-langchainMcpAgentExecutor混合工具Function Calling前置阅读McpAgentExecutor用几行代码让模型自主调用 HTTP 工具多步推理 → McpAgentExecutor McpClient让 Agent 直接操作文件系统和数据库适合人群已分别接入 HTTP 工具和 NPX 服务器希望在同一个 Agent 中串联使用的 Java 开发者一、从单一来源到混合来源前两篇文章分别介绍了两种工具来源文章 12McpManagermcp.config.json→ HTTP API 工具查 IP、查天气、调内部接口文章 13McpClientmcp.server.config.json→ NPX MCP 服务器文件系统、数据库、记忆存储但真实业务中一个任务往往横跨两类工具。典型的场景是先调用 HTTP API 获取数据再把结果写入文件或存入数据库。如果为这类任务专门维护两个 Agent、手动拼接结果不仅代码繁琐还引入了不必要的协调层。McpAgentExecutor支持链式.tools(...)调用可以在同一个 Agent 上同时挂载多个来源的工具。模型在推理时能自由选择 HTTP 工具或 NPX 工具开发者不需要关心工具的来源。二、核心用法链式注册工具McpAgentExecutoragentMcpAgentExecutor.builder(chainActor).llm(ChatAliyun.builder().model(qwen3.6-plus).temperature(0f).build()).tools(mcpManager,default)// 第一层HTTP 工具get_export_ip 等.tools(mcpClient,filesystem)// 第二层NPX filesystem 工具.systemPrompt( 你是一个智能助手可以调用工具获取网络信息和操作文件系统。 当你完成用户的所有要求后直接给出最终答案不要再调用任何工具。 ).maxIterations(8).onToolCall(tc-System.out.println( Tool: tc)).onObservation(obs-System.out.println( Result: obs)).build();两次.tools(...)调用的工具列表会在框架内部合并统一转成 Function Calling Schema 交给模型。注册顺序不影响功能但有一点需要注意如果两个来源中存在同名工具后注册的会覆盖前一个建议在mcp.config.json和服务器命名时按业务域区分避免冲突。三、完整示例查询公网 IP 并写入文件TestpublicvoidmcpMixedAgent(){McpAgentExecutoragentMcpAgentExecutor.builder(chainActor).llm(ChatAliyun.builder().model(qwen3.6-plus).temperature(0f).build()).tools(mcpManager,default).tools(mcpClient,filesystem).systemPrompt( 你是一个智能助手可以调用工具获取网络信息和操作文件系统。 当你完成用户的所有要求后直接给出最终答案不要再调用任何工具。 ).maxIterations(8).onToolCall(tc-System.out.println( Tool: tc)).onObservation(obs-System.out.println( Result: obs)).build();ChatGenerationresultagent.invoke(帮我查一下公网 IP然后把 IP 地址写入 /tmp/my_ip.txt 文件读取文件内容确认写入成功);System.out.println(\n 最终答案 );System.out.println(result.getText());}四、完整推理轨迹任务横跨三个工具——一个来自 HTTP两个来自 NPX 服务器——模型自主完成全部调用 Tool: get_export_ip - {} Result: 123.117.177.40 Tool: write_file - {path: /tmp/my_ip.txt, content: 123.117.177.40} Result: 写入成功 Tool: read_file - {path: /tmp/my_ip.txt} Result: 123.117.177.40 最终答案 公网 IP 已成功写入 /tmp/my_ip.txt读取确认内容为 123.117.177.40。模型没有任何这个工具来自 HTTP、那个工具来自 NPX的概念它只看到一份统一的工具列表根据任务需要自行选择。这是混合挂载最核心的价值工具的来源对模型透明对开发者也不需要额外处理。五、工具列表越大越好吗把所有工具都挂到一个 Agent 上听起来很方便但实际使用中工具列表的大小对效果有明显影响。工具越多模型选错的概率越高。Function Calling 本质上是让模型从一组候选函数中选出最合适的候选集越大干扰越多。实际测试中工具数量超过 15~20 个时模型的选择准确率会有明显下降。推荐做法是按任务拆分工具组而不是把所有工具塞进一个 Agent// mcp.config.json{network:[get_export_ip,get_ip_location,get_weather_open_meteo],crm:[query_customer,update_order,send_notification],ops:[check_server_status,get_disk_usage,restart_service]}不同 Agent 只加载自己需要的工具组// 网络诊断 Agent只挂 network 组 filesystem.tools(mcpManager,network).tools(mcpClient,filesystem)// 客服 Agent只挂 crm 组.tools(mcpManager,crm)// 运维 Agent只挂 ops 组 memory.tools(mcpManager,ops).tools(mcpClient,memory)这样每个 Agent 的工具列表保持在 5~10 个选择准确率更高System Prompt 也更容易写得具体。六、System Prompt 写法对混合工具的影响挂载多来源工具后System Prompt 的质量对 Agent 的表现影响更大。以下两种写法的效果差距明显模糊写法容易出问题你是一个智能助手可以调用工具回答用户问题。模型可能会在工具之间来回调用或者在任务完成后继续调用不必要的工具。具体写法推荐你是一个网络诊断助手。 任务流程先用 HTTP 工具获取网络信息再用文件系统工具保存结果保存完成后直接给出结论停止调用工具。 每个工具最多调用一次不要重复查询相同信息。明确的任务流程描述能显著减少模型的无效调用也能让maxIterations的设置更加精准。七、maxIterations 怎么设置混合挂载场景下一次任务可能横跨多个工具maxIterations的设置需要更仔细估算。基本原则预估最坏情况下的工具调用次数再加 2~3 作为 buffer。以本例为例get_export_ip1次write_file1次read_file1次最坏情况合计 3 次 Action设置maxIterations(8)是足够的。如果任务更复杂如查多个数据源、写多个文件相应调大即可。设得过大的副作用是当模型陷入重复调用时需要消耗更多轮次才能触发终止浪费 Token。System Prompt 里加一句完成后停止调用工具能有效减少这种情况。八、总结工具来源对应配置注册方式HTTP APImcp.config.json.tools(mcpManager, 分组名)NPX MCP 服务器mcp.server.config.json.tools(mcpClient, 服务器别名)两者混合两个配置文件各配各的链式调用两次.tools(...)混合挂载没有引入任何新概念只是把前两篇文章的两行.tools(...)拼在一起。框架负责合并工具列表、管理推理循环开发者只需关注工具分组是否合理和System Prompt 是否清晰这两件事。工具分组拆得越细每个 Agent 的职责越单一模型的选择准确率也越高。 相关资源完整示例Article14McpMixedAgent.java对应方法mcpMixedAgent()工具配置mcp.config.json 和 mcp.server.config.jsonj-langchain GitHubhttps://github.com/flower-trees/j-langchainj-langchain Gitee 镜像https://gitee.com/flower-trees-z/j-langchain运行环境需配置阿里云 API Key示例模型qwen3.6-plus需本地安装 Node.js 以运行 npx