{"record":{"id":"3f25d54174601b8b","repo":"alibaba/spring-ai-alibaba","slug":"type-requires-sub-agents-array","errorCode":null,"errorMessage":"${type} requires 'sub_agents' (array)","messagePattern":"(.+?) requires 'sub_agents' \\(array\\)","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":84,"sourceCode":"//\t\tif (handle == null) {\n//\t\t\tthrow new IllegalArgumentException(type() + \" requires 'handle' configuration\");\n//\t\t}\n\t\tif (handle == null) {\n\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) {","sourceCodeStart":66,"sourceCodeEnd":102,"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#L66-L102","documentation":"requireSubAgents() throws this when the DSL root has no \"sub_agents\" field or it is not a List. Multi-agent types (SequentialAgent, ParallelAgent, RoutingAgent, LoopAgent, etc.) are defined by composition, so an array of sub-agents is mandatory. The provider refuses to generate code without it.","triggerScenarios":"validateSpecific() of a multi-agent provider calls requireSubAgents(root, minCount) and root.get(\"sub_agents\") is null or an object/string instead of a List.","commonSituations":"Using a single-agent config template for a sequential/parallel agent type; YAML parsing turning sub_agents into a map; typo like \"subAgents\" or \"subagents\"; config missing after a schema version change.","solutions":["Add a \"sub_agents\" array to the agent configuration root","Verify the exact key spelling is \"sub_agents\" (snake_case)","Ensure sub_agents is a JSON/YAML array, not an object or comma string"],"exampleFix":"// before\n{\"type\": \"sequential_agent\", \"name\": \"pipeline\"}\n// after\n{\"type\": \"sequential_agent\", \"name\": \"pipeline\", \"sub_agents\": [{\"type\": \"react_agent\", \"name\": \"step1\", ...}]}","handlingStrategy":"validation","validationCode":"Object subs = config.get(\"sub_agents\");\nif (!(subs instanceof List) || ((List<?>) subs).isEmpty()) {\n    throw new IllegalArgumentException(\"multi-agent config requires a non-empty 'sub_agents' array\");\n}","typeGuard":"static boolean hasSubAgents(Map<String,Object> cfg) {\n    return cfg.get(\"sub_agents\") instanceof List<?> l && !l.isEmpty();\n}","tryCatchPattern":"try {\n    provider.validateDSL(root);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"requires 'sub_agents'\")) {\n        // report that the composition field is missing or the wrong shape\n    }\n}","preventionTips":["Use snake_case keys exactly as the DSL expects (sub_agents)","For any multi-agent type, define sub_agents before other fields","Lint DSL files against the agent-type schema in CI"],"tags":["validation","dsl","multi-agent"],"backgroundTag":"missing-required-argument","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"}