{"record":{"id":"9119e5e201a910c2","repo":"alibaba/spring-ai-alibaba","slug":"sub-agents-must-be-baseagent","errorCode":null,"errorMessage":"Sub-agents must be BaseAgent","messagePattern":"Sub-agents must be BaseAgent","errorType":"validation","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":206,"sourceCode":"\t\t * @return this builder instance for method chaining\n\t\t */\n\t\tpublic ParallelAgentBuilder mergeStrategy(MergeStrategy mergeStrategy) {\n\t\t\tthis.mergeStrategy = mergeStrategy;\n\t\t\treturn this;\n\t\t}\n\n\t\tpublic ParallelAgentBuilder mergeOutputKey(String mergeOutputKey) {\n\t\t\tthis.mergeOutputKey = mergeOutputKey;\n\t\t\treturn this;\n\t\t}\n\n\t\t@Override\n\t\tpublic ParallelAgentBuilder subAgents(List<Agent> subAgents) {\n\t\t\tif (subAgents == null || subAgents.isEmpty()) {\n\t\t\t\tthrow new IllegalArgumentException(\"Sub-agents must be provided\");\n\t\t\t}\n\t\t\tif (subAgents.stream().anyMatch(agent -> !(agent instanceof BaseAgent))) {\n\t\t\t\tthrow new IllegalArgumentException(\"Sub-agents must be BaseAgent\");\n\t\t\t}\n\t\t\treturn super.subAgents(subAgents);\n\t\t}\n\n\t\t/**\n\t\t * Sets the maximum number of sub-agents that can execute concurrently.\n\t\t * @param maxConcurrency the maximum concurrency limit\n\t\t * @return this builder instance for method chaining\n\t\t */\n\t\tpublic ParallelAgentBuilder maxConcurrency(Integer maxConcurrency) {\n\t\t\tthis.maxConcurrency = maxConcurrency;\n\t\t\treturn this;\n\t\t}\n\n\t\t/**\n\t\t * Returns the concrete builder instance for fluent interface support.\n\t\t * @return this builder instance\n\t\t */","sourceCodeStart":188,"sourceCodeEnd":224,"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#L188-L224","documentation":"ParallelAgent requires every entry in the subAgents list to be a BaseAgent instance; its builder's subAgents(List) throws IllegalArgumentException if any element is not. This guards the execution engine, which casts/uses BaseAgent-specific parallel execution semantics.","triggerScenarios":"Passing a list containing objects implementing the Agent interface but not extending BaseAgent (e.g., custom Agent implementations, mocks, or wrappers) to ParallelAgent.builder().subAgents(...).","commonSituations":"Mixing agents from different modules/API versions where one type implements Agent but not BaseAgent; test doubles (Mockito mocks of the Agent interface) injected into a real builder; refactoring a custom agent that no longer extends BaseAgent.","solutions":["Make all list elements extend BaseAgent (or replace them with built-in agents like SequentialAgent/LoopAgent which do).","For tests, mock or subclass BaseAgent rather than the Agent interface.","Pre-validate the list with instanceof BaseAgent checks and log/exclude incompatible entries before calling subAgents()."],"exampleFix":"// before\nAgent custom = new MyLightweightAgent(); // implements Agent only\nparallelBuilder.subAgents(List.of(baseAgent1, custom)); // throws: Sub-agents must be BaseAgent\n// after\nBaseAgent custom = new MyLightweightAgent(); // now extends BaseAgent\nparallelBuilder.subAgents(List.of(baseAgent1, custom));","handlingStrategy":"validation","validationCode":"for (Agent a : subAgents) {\n    if (!(a instanceof BaseAgent)) {\n        throw new IllegalArgumentException(\"Sub-agent \" + a + \" must extend BaseAgent\");\n    }\n}","typeGuard":"static boolean allBaseAgents(List<Agent> l) {\n    return l.stream().allMatch(a -> a instanceof BaseAgent);\n}","tryCatchPattern":"try {\n    parallelBuilder.subAgents(agents);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"BaseAgent\")) {\n        log.error(\"Non-BaseAgent in sub-agent list: {}\", e.getMessage());\n    }\n}","preventionTips":["Type lists as List<BaseAgent> where possible so the compiler enforces it.","In tests, use BaseAgent subclasses or mocks typed to BaseAgent, not the Agent interface.","Ensure custom agents extend BaseAgent when intended for parallel execution."],"tags":["java","parallel-agent","type-mismatch","builder"],"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"}