{"record":{"id":"134948b1db321634","repo":"alibaba/spring-ai-alibaba","slug":"agentscope-routing-flow-requires-root-agent-to-be","errorCode":null,"errorMessage":"AgentScope routing flow requires root agent to be AgentScopeRoutingAgent","messagePattern":"AgentScope routing flow requires root agent to be AgentScopeRoutingAgent","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":138,"sourceCode":"\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":120,"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#L120-L142","documentation":"AgentScopeRoutingGraphBuildingStrategy.validateAgentScopeRoutingConfig throws this IllegalArgumentException when a routing-flow config declares a root agent that is not an instance of AgentScopeRoutingAgent. The routing graph-building strategy can only wire the special routing root (which produces MultiCommand branch decisions), so any other root agent type is rejected before graph construction.","triggerScenarios":"Calling the AgentScope routing flow builder (buildCoreGraph / validateConfig) with a config whose getRootAgent() returns a plain agent, a SequentialAgent, or any agent other than AgentScopeRoutingAgent, even when sub-agents and agentScopeModel are correctly set.","commonSituations":"Developers reuse a graph-config builder shared with other flow types and forget to swap the root agent for AgentScopeRoutingAgent; custom agent subclasses fail an instanceof check because they extend a base agent class instead of AgentScopeRoutingAgent; config deserialization creates a generic agent type.","solutions":["Set config.setRootAgent(...) to an actual AgentScopeRoutingAgent instance (or its builder) before building the graph","Verify the root agent's concrete class extends AgentScopeRoutingAgent, not a similarly named base class","If the flow should not be a routing flow, use the graph-building strategy that matches the root agent type you provided"],"exampleFix":"// before\nconfig.setRootAgent(new AgentScopeAgent(\"router\"));\n// after\nconfig.setRootAgent(AgentScopeRoutingAgent.builder()\n    .name(\"router\")\n    .subAgents(subAgents)\n    .model(model)\n    .build());","handlingStrategy":"validation","validationCode":"if (!(config.getRootAgent() instanceof AgentScopeRoutingAgent)) {\n    throw new IllegalArgumentException(\"routing flow requires AgentScopeRoutingAgent as root\");\n}","typeGuard":"static boolean isRoutingRoot(AgentConfig c) {\n    return c != null && c.getRootAgent() instanceof AgentScopeRoutingAgent;\n}","tryCatchPattern":"try {\n    graph = strategy.build(config);\n} catch (IllegalArgumentException e) {\n    logger.error(\"Invalid routing config: {}\", e.getMessage());\n    throw new ConfigException(e);\n}","preventionTips":["Always build the root with AgentScopeRoutingAgent.builder() for routing flows","Validate root agent type in a unit test for each flow definition","Centralize flow config creation in one factory so the right strategy/agent pairing is guaranteed"],"tags":["agentscope","routing","config-validation","illegal-argument"],"backgroundTag":"invalid-argument-value","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"}