{"record":{"id":"9d64e01b75b39cc3","repo":"alibaba/spring-ai-alibaba","slug":"agentscoperoutingagent-rootagent-name-failed-t","errorCode":null,"errorMessage":"AgentScopeRoutingAgent {rootAgent.name()} failed to get valid decision after retries. Invalid agents: {invalidAgents}.","messagePattern":"AgentScopeRoutingAgent (.+?) failed to get valid decision after retries\\. Invalid agents: (.+?)\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"spring-boot-starters/spring-ai-alibaba-starter-agentscope/src/main/java/com/alibaba/cloud/ai/agent/agentscope/flow/AgentScopeRoutingNode.java","lineNumber":118,"sourceCode":"\t\tList<String> decisionValues = decision.getAgentNames();\n\n\t\tList<String> invalidAgents = decisionValues.stream()\n\t\t\t\t.filter(agentName -> subAgents.stream().noneMatch(a -> a.name().equals(agentName)))\n\t\t\t\t.collect(Collectors.toList());\n\n\t\tif (invalidAgents.isEmpty() && !decisionValues.isEmpty()) {\n\t\t\tif (decisionValues.size() == 1) {\n\t\t\t\tlogger.info(\"AgentScopeRoutingAgent {} routed to single sub-agent {}.\", rootAgent.name(), decisionValues.get(0));\n\t\t\t} else {\n\t\t\t\tlogger.info(\"AgentScopeRoutingAgent {} routed to {} sub-agents in parallel: {}.\",\n\t\t\t\t\t\trootAgent.name(), decisionValues.size(), String.join(\", \", decisionValues));\n\t\t\t}\n\t\t\tMap<String, Object> stateUpdate = new HashMap<>();\n\t\t\tdecision.getAgentQueries().forEach((agentName, query) ->\n\t\t\t\t\tstateUpdate.put(agentName + \"_input\", query));\n\t\t\treturn new MultiCommand(decisionValues, stateUpdate);\n\t\t}\n\t\tthrow new IllegalStateException(\n\t\t\t\t\"AgentScopeRoutingAgent \" + rootAgent.name() + \" failed to get valid decision after retries. Invalid agents: \" + invalidAgents + \".\");\n\t}\n\n\tprivate List<Message> prepareMessagesWithInstruction(List<Message> messages) {\n\t\tList<Message> out = new ArrayList<>(messages);\n\t\tString instruction = getInstruction();\n\t\tif (StringUtils.hasLength(instruction)) {\n\t\t\tout.add(new UserMessage(instruction));\n\t\t} else {\n\t\t\tout.add(new UserMessage(\n\t\t\t\t\t\"Based on the chat history and current task progress, please decide the next agent to delegate the task to.\"));\n\t\t}\n\t\treturn out;\n\t}\n\n\tprivate String getInstruction() {\n\t\tif (rootAgent instanceof AgentScopeRoutingAgent scopeAgent) {\n\t\t\treturn scopeAgent.getInstruction();","sourceCodeStart":100,"sourceCodeEnd":136,"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/AgentScopeRoutingNode.java#L100-L136","documentation":"AgentScopeRoutingNode.apply throws this IllegalStateException when, after exhausting retries, the LLM's routing decision still references only invalid agent names (agents not among the routing root's sub-agents) so no valid MultiCommand can be produced. It names the root agent and the invalid agent names returned by the model.","triggerScenarios":"The routing model repeatedly returns agent names in its decision that do not match any registered sub-agent name, so decisionValues remains empty after maxRetries and apply cannot build a MultiCommand.","commonSituations":"Sub-agent names renamed or refactored while the routing instruction prompt still mentions old names; the model hallucinates agent names not in the roster; case/whitespace mismatches between model output and registered agent keys; weak model that ignores the structured routing schema.","solutions":["Ensure every name the model can output exactly matches a registered sub-agent name (check the instruction lists correct agent names)","Strengthen the routing instruction/schema to constrain the model to the exact agent name set","Increase retries or switch to a stronger model for the routing decision","Catch IllegalStateException around graph execution and fall back to a default route"],"exampleFix":"// before\n.subAgents(List.of(helperAgent)) // instruction mentions \"assistant\"\n// after\n.subAgents(List.of(assistantAgent)) // names align with instruction text","handlingStrategy":"try-catch","validationCode":"// before execution: confirm instruction lists exact sub-agent names\nsubAgents.forEach(a -> assert instruction.contains(a.name()));","typeGuard":null,"tryCatchPattern":"try {\n    result = runnable.invoke(state);\n} catch (IllegalStateException e) {\n    logger.warn(\"Routing failed: {}\", e.getMessage());\n    state.put(defaultRouteKey, defaultAgentName);\n}","preventionTips":["Keep sub-agent names stable and mirrored verbatim in the routing instruction","Use a model with reliable structured-output support for routing","Log rejected decisions to catch name drift early"],"tags":["agentscope","routing","llm-decision","invalid-state"],"backgroundTag":"unexpected-api-response-shape","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}