{"record":{"id":"ed74163cbca52352","repo":"alibaba/spring-ai-alibaba","slug":"parallelagent-supports-maximum-10-sub-agents-for-p","errorCode":null,"errorMessage":"ParallelAgent supports maximum 10 sub-agents for performance reasons, but got: 10","messagePattern":"ParallelAgent supports maximum 10 sub-agents for performance reasons, but got: 10","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/agent/ParallelAgent.java","lineNumber":251,"sourceCode":"\t\t */\n\t\t@Override\n\t\tprotected void validate() {\n\t\t\t// Validate name first (from parent)\n\t\t\tif (name == null || name.trim().isEmpty()) {\n\t\t\t\tthrow new IllegalArgumentException(\"Name must be provided\");\n\t\t\t}\n\n\t\t\t// Validate minimum sub-agent count for ParallelAgent (skip parent subAgents\n\t\t\t// check)\n\t\t\tif (subAgents == null || subAgents.size() < 2) {\n\t\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\t\"ParallelAgent requires at least 2 sub-agents for parallel execution, but got: \"\n\t\t\t\t\t\t\t\t+ (subAgents != null ? subAgents.size() : 0));\n\t\t\t}\n\n\t\t\t// Validate maximum sub-agent count for performance reasons\n\t\t\tif (subAgents.size() > 10) {\n\t\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\t\"ParallelAgent supports maximum 10 sub-agents for performance reasons, but got: \"\n\t\t\t\t\t\t\t\t+ subAgents.size());\n\t\t\t}\n\n\t\t\t// Validate that sub-agents have unique output keys to avoid conflicts during\n\t\t\t// result merging\n\t\t\tvalidateUniqueOutputKeys();\n\n\t\t\t// Validate input key compatibility\n\t\t\tvalidateInputKeyCompatibility();\n\n\t\t\t// Validate concurrency limit - allow maxConcurrency to be null (unlimited) or\n\t\t\t// within valid range\n\t\t\tif (maxConcurrency != null) {\n\t\t\t\tif (maxConcurrency < 1) {\n\t\t\t\t\tthrow new IllegalArgumentException(\"maxConcurrency must be at least 1, but got: \" + maxConcurrency);\n\t\t\t\t}\n\t\t\t}","sourceCodeStart":233,"sourceCodeEnd":269,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/agent/ParallelAgent.java#L233-L269","documentation":"ParallelAgent caps sub-agents at 10 for performance reasons; validate() throws when more than 10 are registered. Very large fan-outs blow up parallel model calls and state merging, so the library enforces a hard maximum.","triggerScenarios":"ParallelAgent.builder().name(\"x\").subAgents(moreThanTenAgents).build(), or dynamically collecting agents so the list exceeds 10.","commonSituations":"Auto-generating one sub-agent per data source or tool; scaling a fan-out pipeline and silently crossing the cap.","solutions":["Reduce the number of sub-agents to 10 or fewer, batching work inside agents if needed","Split the fan-out into multiple ParallelAgents or a loop/sequential stage","Patch the pipeline to chunk the agent list before building"],"exampleFix":"// before\nParallelAgent.builder().name(\"p\").subAgents(allAgents).build(); // allAgents.size() > 10\n// after\nList<Agent> batch = allAgents.subList(0, 10);\nParallelAgent.builder().name(\"p\").subAgents(batch).build();","handlingStrategy":"validation","validationCode":"if (subAgents != null && subAgents.size() > 10) subAgents = subAgents.subList(0, 10);","typeGuard":"boolean withinParallelCap(java.util.List<Agent> a) { return a != null && a.size() <= 10; }","tryCatchPattern":"try { agent = builder.build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"maximum 10 sub-agents\")) { /* chunk the fan-out */ } else throw e; }","preventionTips":["Cap fan-out generation code at 10","Chunk large fan-outs into grouped parallel stages","Review limits when auto-generating agents per data source"],"tags":["validation","limits","fan-out"],"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"}