SubAgent 进阶：LLM 策略、工具借用与 Skill 嵌套

标签JavaSubAgentLLM策略llmFactoryallowedToolsSkill嵌套j-langchain前置阅读SubAgent 基础拥有自主工具的子代理适合人群已掌握 SubAgent 基础用法希望灵活控制模型选择、工具权限与多层嵌套的 Java 开发者一、四个进阶场景上一篇介绍了 SubAgent 的三种基础用法独立运行、注册到 Master、代码构造。本篇聚焦四个进阶场景场景解决的问题modelinheritSubAgent 直接复用主 Agent 的 LLM无需重复配置llmFactorySubAgent 在配置文件里声明模型名运行时按名构建LLM 实例由主 Agent 统一管理allowedToolsSubAgent 从主 Agent 借用部分工具遵循最小权限原则SKILL 内嵌 SubAgentSkill 的agents/目录放置轻量 SubAgent形成两层嵌套二、LLM 三级解析优先链理解这四个场景之前先明确 SubAgent 的 LLM 解析规则。每次invoke()时SubAgent 按以下优先级确定使用哪个 LLM优先级 场景 配置方式 ────────────────────────────────────────────────────────── 1 显式注入开发者指定 SubAgent.Builder.llm(llm) 2 inherit继承主 Agent AGENT.md: model: inherit 主 Agent build() 时自动调用 injectLlm(masterLlm) 3 模型工厂按名构建 AGENT.md: model: qwen-plus 主 Agent build() 时调用 injectLlmFactory(factory) 首次 invoke() 前 factory.apply(qwen-plus) 执行三个优先级覆盖了所有实际部署场景测试环境显式注入、同类任务共享主 LLM、差异化模型按名管理。三、modelinheritSubAgent 继承主 Agent 的 LLM最简单的 LLM 复用方式SubAgent 不自己配置 LLM直接用主 Agent 的。配置文件agents/weather-checker/AGENT.md--- name: weather_checker description: 天气查询专员。专注查询城市天气信息当需要了解目的地天气时使用。 model: inherit tools: - get_weather max-iterations: 5 --- 你是天气查询专员专注于查询城市当前天气状况。 收到城市名称后调用 get_weather 工具返回简洁的天气报告。model: inherit加上tools: [get_weather]借用父 Agent 的get_weather工具。代码varmasterLlmChatAliyun.builder().model(qwen-plus).temperature(0f).build();SubAgentConfigconfigClasspathSubAgentConfigLoader.fromClasspath(agents/weather-checker);// modelinherit → 不在 builder 里调用 .llm()由主 Agent build() 时自动注入SubAgentweatherAgentSubAgent.from(config,chainActor).tools(buildTool(get_weather,查询城市天气,city: String,tools::getWeather)).onToolCall(tc-System.out.println([weather_checker] ToolCall: tc)).onObservation(obs-System.out.println([weather_checker] Observation: obs)).build();McpAgentExecutormasterMcpAgentExecutor.builder(chainActor).llm(masterLlm)// 这个 llm 会被自动注入到 modelinherit 的 SubAgent.subAgent(weatherAgent).systemPrompt(你是旅行助手天气查询任务请使用 weather_checker。).build();Stringresultmaster.invoke(成都现在天气怎么样).getText();主 Agentbuild()内部逻辑for(SubAgentsubAgent:subAgents){if(subAgent.isInheritModel()){subAgent.injectLlm(masterLlm);// 直接注入主 Agent 的 LLM 实例}...}适用场景子任务与主任务性质相同不需要差异化模型想减少配置重复。四、llmFactory按模型名动态构建 LLM当不同 SubAgent 需要使用不同模型时llmFactory提供了统一的 LLM 管理入口SubAgent 在配置里声明模型名主 Agent 提供一个按名构建的工厂函数。// SubAgent 配置声明模型名不传 llmSubAgentConfigconfigSubAgentConfig.builder().name(flight_checker).description(机票价格查询专员。当需要查询机票信息时使用。).model(qwen-turbo)// 由主 Agent 的 llmFactory 解析.systemPrompt(你是机票查询专员收到城市名后调用 get_flight_price返回机票价格。).build();SubAgentflightAgentSubAgent.from(config,chainActor)// 不调用 .llm()由 llmFactory 在 master build() 时解析.tools(buildTool(get_flight_price,查询机票价格,city: String,tools::getFlightPrice)).build();McpAgentExecutormasterMcpAgentExecutor.builder(chainActor).llm(ChatAliyun.builder().model(qwen-plus).temperature(0f).build()).llmFactory(modelName-ChatAliyun.builder().model(modelName).temperature(0f).build()).subAgent(flightAgent).systemPrompt(你是旅行助手机票查询任务请使用 flight_checker。).build();Stringresultmaster.invoke(帮我查一下上海到西安的机票).getText();主 Agentbuild()内部逻辑}elseif(llmFactory!null){subAgent.injectLlmFactory(llmFactory);// 注入工厂子代理按 model 名构建}resolveLlm()在首次invoke()时执行factory.apply(qwen-turbo)LLM 实例延迟创建。llmFactory 的价值llmFactory是集中的 LLM 注册表入口——新增模型只改工厂函数所有 SubAgent 受益SubAgentConfig里的model字段是字符串可以来自配置文件或数据库部署时无需改代码主 Agent llmFactory: modelName → ChatAliyun(modelName) ↓ flight_checker (modelqwen-turbo) → ChatAliyun(qwen-turbo) analyst (modelqwen-max) → ChatAliyun(qwen-max) summarizer (modelqwen-turbo) → ChatAliyun(qwen-turbo)五、allowedTools从主 Agent 借用部分工具SubAgent 不一定要自带所有工具。当工具已经在主 Agent 注册SubAgent 只需声明allowedTools白名单主 Agent 在build()时自动过滤并注入。ToolweatherToolbuildTool(get_weather,查询城市天气,city: String,tools::getWeather);ToolflightToolbuildTool(get_flight_price,查询机票价格,city: String,tools::getFlightPrice);ToolhotelToolbuildTool(get_hotel_price,查询酒店均价,city: String,tools::getHotelPrice);// SubAgent 声明只借 get_weather 和 get_hotel_price不需要 get_flight_priceSubAgentConfigconfigSubAgentConfig.builder().name(accommodation_advisor).description(住宿建议专员。查询天气和酒店价格给出住宿建议。当需要住宿信息时使用。).allowedTools(List.of(get_weather,get_hotel_price)).systemPrompt( 你是住宿建议专员。 收到城市名后依次调用 get_weather 和 get_hotel_price 结合天气和酒店价格给出住宿选择建议。 ).build();// SubAgent 自己没有 tools全部来自 allowedTools 注入SubAgentadvisorSubAgent.from(config,chainActor).llm(llm).onToolCall(tc-System.out.println([accommodation_advisor] ToolCall: tc)).onObservation(obs-System.out.println([accommodation_advisor] Observation: obs)).build();// 主 Agent 拥有全部 3 个工具SubAgent 只会得到白名单里的两个McpAgentExecutormasterMcpAgentExecutor.builder(chainActor).llm(ChatAliyun.builder().model(qwen-plus).temperature(0f).build()).tools(weatherTool,flightTool,hotelTool).subAgent(advisor).systemPrompt(你是旅行总助手住宿建议任务请使用 accommodation_advisor。).build();Stringresultmaster.invoke(我想去桂林帮我看看住哪里合适).getText();注入流程主 Agent 工具[get_weather, get_flight_price, get_hotel_price] ↓ allowedTools 白名单过滤 SubAgent 内部工具[get_weather, get_hotel_price] ← get_flight_price 被拦截最小权限原则SubAgent 只能访问它明确声明需要的工具。即使主 Agent 有 50 个工具SubAgent 也只会看到白名单里的那几个不会误调用不相关的工具也减少了 LLM 在选择工具时的噪声。执行过程[accommodation_advisor] ToolCall: get_weather {city:桂林} [accommodation_advisor] Observation: 桂林阵雨23~30°C [accommodation_advisor] ToolCall: get_hotel_price {city:桂林} [accommodation_advisor] Observation: 桂林三星¥200/晚四星¥380/晚 住宿建议 桂林近期天气多雨建议选择市区内的四星酒店¥380/晚出行更便利。 三星酒店¥200/晚性价比高适合预算有限的旅行者。 3晚住宿预算¥600三星~ ¥1140四星六、SKILL 内嵌 SubAgent两层嵌套Skill 的agents/子目录可以放置轻量的 SubAgent 配置这些 SubAgent 会被自动注册为 Skill 内部执行器的工具形成主 Agent → Skill → SubAgent的两层嵌套。目录结构skills/travel-planner/ SKILL.md agents/ budget-advisor.md ← 内嵌 SubAgent只能访问 Skill 自身工具集里的工具budget-advisor.md--- name: budget_advisor description: 旅行预算顾问。根据城市名称查询酒店均价计算3晚旅行的住宿预算。 当需要估算旅行预算时调用。 allowed-tools: - get_hotel_price --- 你是旅行预算顾问专注于住宿费用估算。 收到城市名称后 1. 调用 get_hotel_price 查询该城市酒店均价 2. 按3晚计算住宿总费用三星和四星两个档次 3. 输出简洁的预算建议内嵌 SubAgent 的allowed-tools引用的是Skill 自身工具集中的工具不是主 Agent 的工具借用范围严格限定在 Skill 内部。代码SkillConfigconfigClasspathSkillConfigLoader.fromClasspath(skills/travel-planner);System.out.println(内嵌 agents 数量: config.getAgents().size());config.getAgents().forEach(a-System.out.println( - a.getName() allowedToolsa.getAllowedTools()));SkilltravelSkillSkill.from(config,chainActor).llm(llm).tools(weatherTool,flightTool,hotelTool).verbose(true).build();McpAgentExecutormasterMcpAgentExecutor.builder(chainActor).llm(ChatAliyun.builder().model(qwen-plus).temperature(0f).build()).skill(travelSkill).systemPrompt(你是旅行总助手旅行规划任务请使用 travel_planner 技能。).build();Stringresultmaster.invoke(我想去三亚旅游3晚帮我估算一下住宿预算).getText();执行时日志verbose(true)开启二级前缀内嵌 agents 数量: 1 - budget_advisor allowedTools[get_hotel_price] [skill:travel_planner] ToolCall: budget_advisor {input:三亚住宿预算3晚} [skill:travel_plannerbudget_advisor] ToolCall: get_hotel_price {city:三亚} [skill:travel_plannerbudget_advisor] Observation: 三亚三星¥480/晚四星¥950/晚 SKILL 内嵌 SubAgent 结果 三亚3晚住宿预算 - 三星酒店¥480 × 3 ¥1440 - 四星酒店¥950 × 3 ¥2850 建议三亚旅游旺季酒店紧张建议提前预订四星酒店...二级日志前缀[skill:travel_plannerbudget_advisor]清楚展示了调用链的层级关系调试多层嵌套时一目了然。七、四个进阶场景汇总场景关键 API典型用途modelinheritAGENT.mdmodel: inherit子任务与主任务用同一模型减少配置冗余llmFactory.llmFactory(name - ...)多 SubAgent 使用不同模型统一工厂管理allowedToolsSubAgentConfig.allowedTools(...)SubAgent 借用父工具最小权限隔离SKILL 内嵌 SubAgentagents/*.md目录Skill 内部进一步分解子任务八、运行前置条件ALIYUN_KEY环境变量示例使用qwen-plus/qwen-turbomodelinherit和内嵌 SubAgent 模式需要对应的AGENT.md文件allowedTools和llmFactory模式可以用代码构造SubAgentConfig无文件依赖九、总结SubAgent 进阶能力让多 Agent 系统在模型选择和工具权限上更加灵活三级 LLM 优先链覆盖了所有部署场景显式注入用于测试inherit用于复用llmFactory用于差异化模型管理allowedTools白名单保证最小权限SubAgent 只能看到声明需要的工具LLM 不会误调用无关工具SKILL 内嵌 SubAgent让两层嵌套自然表达Skill 把复杂子任务进一步委托给专属小代理的意图verbose日志二级前缀让调用链透明可追踪 相关资源完整代码Article23SubAgent.java方法testInheritModel/testLlmFactory/testAllowedToolsFromParent/testSkillWithEmbeddedAgent内嵌子代理配置skills/travel-planner/agents/budget-advisor.md天气专员配置agents/weather-checker/AGENT.mdj-langchain GitHubhttps://github.com/flower-trees/j-langchain运行环境ALIYUN_KEYqwen-plus/qwen-turbo