{"record":{"id":"c6555a4f169eab41","repo":"alibaba/spring-ai-alibaba","slug":"type-requires-at-least-mincount-sub-agent-s","errorCode":null,"errorMessage":"${type} requires at least ${minCount} sub-agent(s), got: ${size}","messagePattern":"(.+?) requires at least (.+?) sub-agent\\(s\\), got: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-start/src/main/java/com/alibaba/cloud/ai/studio/admin/builder/generator/service/generator/agent/AbstractAgentTypeProvider.java","lineNumber":88,"sourceCode":"\t\t\thandle = new HashMap<>();\n\t\t}\n\t\treturn handle;\n\t}\n\n\t/**\n\t * 校验必须有子代理\n\t * @param root DSL 根对象\n\t * @param minCount 最小数量\n\t */\n\t@SuppressWarnings(\"unchecked\")\n\tprotected List<Map<String, Object>> requireSubAgents(Map<String, Object> root, int minCount) {\n\t\tObject subs = root.get(\"sub_agents\");\n\t\tif (!(subs instanceof List)) {\n\t\t\tthrow new IllegalArgumentException(type() + \" requires 'sub_agents' (array)\");\n\t\t}\n\t\tList<Map<String, Object>> subAgents = (List<Map<String, Object>>) subs;\n\t\tif (subAgents.size() < minCount) {\n\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\ttype() + \" requires at least \" + minCount + \" sub-agent(s), got: \" + subAgents.size());\n\t\t}\n\t\treturn subAgents;\n\t}\n\n\t/**\n\t * 校验数值字段\n\t * @param value 字段值\n\t * @param fieldName 字段名\n\t * @param minValue 最小值（包含）\n\t * @return 数值\n\t */\n\tprotected int requirePositiveNumber(Object value, String fieldName, int minValue) {\n\t\tif (value == null) {\n\t\t\tthrow new IllegalArgumentException(type() + \" requires '\" + fieldName + \"'\");\n\t\t}\n\t\tif (!(value instanceof Number)) {\n\t\t\tthrow new IllegalArgumentException(fieldName + \" must be a number\");","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-start/src/main/java/com/alibaba/cloud/ai/studio/admin/builder/generator/service/generator/agent/AbstractAgentTypeProvider.java#L70-L106","documentation":"requireSubAgents() throws this when \"sub_agents\" is an array but contains fewer entries than the agent type's required minimum (minCount). Each composition pattern has semantic minimums, e.g. RoutingAgent needs at least 2 sub-agents to route between. The actual size is included in the message.","triggerScenarios":"A provider calls requireSubAgents(root, minCount) and the sub_agents list is non-null and is a List but subAgents.size() < minCount, e.g. RoutingAgent with only 1 sub-agent when 2 are required.","commonSituations":"Removing an agent from a pipeline and forgetting the minimum; copy-pasting a single-agent example for a routing agent; a migration script that drops empty sub-agent entries.","solutions":["Add more sub-agent definitions to the \"sub_agents\" array until it meets the minimum for the agent type","If fewer agents are genuinely needed, switch to a single-agent type like react_agent","Read the message's 'got: N' count to see how many more are required"],"exampleFix":"// before\n{\"type\": \"routing_agent\", \"name\": \"router\", \"sub_agents\": [onlyOneAgent]}\n// after\n{\"type\": \"routing_agent\", \"name\": \"router\", \"sub_agents\": [agentA, agentB]}","handlingStrategy":"validation","validationCode":"int min = 2; // e.g. RoutingAgent minimum\nList<?> subs = (List<?>) config.get(\"sub_agents\");\nif (subs == null || subs.size() < min) {\n    throw new IllegalArgumentException(type + \" needs at least \" + min + \" sub_agents\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    provider.validateDSL(root);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"at least\") && e.getMessage().contains(\"sub-agent\")) {\n        // parse the required minimum from the message and prompt the user\n    }\n}","preventionTips":["Know each pattern's minimum: routing/parallel typically need >= 2 sub-agents","When deleting sub-agents from a config, re-check minimum counts","Fall back to a single-agent type if only one sub-agent remains"],"tags":["validation","dsl","multi-agent"],"backgroundTag":"value-out-of-range","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"}