{"record":{"id":"6a8f516fccf13e88","repo":"alibaba/spring-ai-alibaba","slug":"agentscope-routing-flow-requires-at-least-one-sub","errorCode":null,"errorMessage":"AgentScope routing flow requires at least one sub-agent","messagePattern":"AgentScope routing flow requires at least one sub-agent","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-boot-starters/spring-ai-alibaba-starter-agentscope/src/main/java/com/alibaba/cloud/ai/agent/agentscope/flow/AgentScopeRoutingGraphBuildingStrategy.java","lineNumber":132,"sourceCode":"\t@Override\n\tpublic KeyStrategyFactory generateKeyStrategyFactory(FlowGraphBuilder.FlowGraphConfig config) {\n\t\tKeyStrategyFactory parent = super.generateKeyStrategyFactory(config);\n\t\treturn () -> {\n\t\t\tMap<String, com.alibaba.cloud.ai.graph.KeyStrategy> strategies = new HashMap<>(parent.apply());\n\t\t\tstrategies.put(RoutingMergeNode.DEFAULT_MERGED_OUTPUT_KEY, new ReplaceStrategy());\n\t\t\treturn strategies;\n\t\t};\n\t}\n\n\t@Override\n\tpublic void validateConfig(FlowGraphBuilder.FlowGraphConfig config) {\n\t\tsuper.validateConfig(config);\n\t\tvalidateAgentScopeRoutingConfig(config);\n\t}\n\n\tprivate void validateAgentScopeRoutingConfig(FlowGraphBuilder.FlowGraphConfig config) {\n\t\tif (config.getSubAgents() == null || config.getSubAgents().isEmpty()) {\n\t\t\tthrow new IllegalArgumentException(\"AgentScope routing flow requires at least one sub-agent\");\n\t\t}\n\t\tif (config.getCustomProperty(\"agentScopeModel\") == null) {\n\t\t\tthrow new IllegalArgumentException(\"AgentScope routing flow requires agentScopeModel in config custom properties\");\n\t\t}\n\t\tif (!(config.getRootAgent() instanceof AgentScopeRoutingAgent)) {\n\t\t\tthrow new IllegalArgumentException(\"AgentScope routing flow requires root agent to be AgentScopeRoutingAgent\");\n\t\t}\n\t}\n}\n","sourceCodeStart":114,"sourceCodeEnd":142,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-boot-starters/spring-ai-alibaba-starter-agentscope/src/main/java/com/alibaba/cloud/ai/agent/agentscope/flow/AgentScopeRoutingGraphBuildingStrategy.java#L114-L142","documentation":"AgentScopeRoutingGraphBuildingStrategy.validateAgentScopeRoutingConfig() (called from buildCoreGraph and validateConfig) requires a routing flow to declare at least one sub-agent. A routing agent routes among sub-agents, so an empty or null sub-agents list makes the flow meaningless and an IllegalArgumentException is thrown during graph building/config validation.","triggerScenarios":"Building an AgentScope routing flow where FlowGraphConfig.getSubAgents() is null or empty — e.g. no .subAgents(...) calls on the builder, or sub-agents were filtered out before build.","commonSituations":"Forgot to register sub-agents on the routing builder; conditional code that adds sub-agents never executed; sub-agents list built dynamically and ended up empty; copying a routing example but omitting the sub-agent wiring.","solutions":["Add at least one sub-agent via builder/config before building the routing flow.","Check the code path that populates sub-agents — it may be conditional and skipped at runtime.","If dynamic, guard construction: only build the routing flow when subAgents is non-empty."],"exampleFix":"// before\nAgentScopeRoutingFlow.builder()\n    .name(\"router\")\n    .model(model)\n    .build(); // no sub-agents -> IllegalArgumentException\n// after\nAgentScopeRoutingFlow.builder()\n    .name(\"router\")\n    .model(model)\n    .subAgents(List.of(agentA, agentB))\n    .build();","handlingStrategy":"validation","validationCode":"// Java: validate before building\nif (subAgents == null || subAgents.isEmpty()) {\n    throw new IllegalStateException(\"Routing flow requires at least one sub-agent before build()\");\n}","typeGuard":"// Java\nboolean hasSubAgents(java.util.Collection<?> subAgents) {\n    return subAgents != null && !subAgents.isEmpty();\n}","tryCatchPattern":null,"preventionTips":["Register sub-agents immediately after naming the routing agent in builder code.","When sub-agents are dynamic, log the list size before building.","Write a smoke test that builds the routing flow with representative sub-agents."],"tags":["agentscope","routing","validation","empty-sub-agents","illegal-argument"],"backgroundTag":"empty-required-field","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}