{"record":{"id":"92dd855d359cb401","repo":"alibaba/spring-ai-alibaba","slug":"loopagent-must-have-only-one-subagent-please-use","errorCode":null,"errorMessage":"LoopAgent must have only one subAgent, please use subAgent() method.","messagePattern":"LoopAgent must have only one subAgent, please use subAgent\\(\\) method\\.","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/agent/LoopAgent.java","lineNumber":95,"sourceCode":"    }\n\n    public static class LoopAgentBuilder extends FlowAgentBuilder<LoopAgent, LoopAgentBuilder> {\n\n        private LoopStrategy loopStrategy = null;\n\n        @Override\n        protected LoopAgentBuilder self() {\n            return this;\n        }\n\n        public LoopAgentBuilder subAgent(Agent subAgent) {\n            this.subAgents = List.of(subAgent);\n            return self();\n        }\n\n        @Override\n        public LoopAgentBuilder subAgents(List<Agent> subAgents) {\n            throw new UnsupportedOperationException(\"LoopAgent must have only one subAgent, please use subAgent() method.\");\n        }\n\n        public LoopAgentBuilder loopStrategy(LoopStrategy loopStrategy) {\n            this.loopStrategy = loopStrategy;\n            return self();\n        }\n\n        @Override\n        protected void validate() {\n            super.validate();\n            if (this.loopStrategy == null) {\n                throw new IllegalArgumentException(\"LoopAgent must have a loopStrategy.\");\n            }\n        }\n\n        @Override\n        public LoopAgent doBuild() {\n            validate();","sourceCodeStart":77,"sourceCodeEnd":113,"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/LoopAgent.java#L77-L113","documentation":"LoopAgent repeats a single sub-agent until its loop strategy terminates. Its builder deliberately overrides subAgents(List) to throw UnsupportedOperationException, because a loop over multiple sub-agents is not supported — use subAgent(Agent) to set the one agent to repeat. This is a design-time API misuse error, not a runtime failure.","triggerScenarios":"Calling LoopAgent.builder().subAgents(List.of(a, b)) or any subAgents(list) call on LoopAgentBuilder.","commonSituations":"Copy-pasting a SequentialAgent or ParallelAgent builder that uses subAgents(list); generic builder code that constructs agents from a list without special-casing LoopAgent; attempting to loop a pipeline of steps.","solutions":["Replace subAgents(list) with a single subAgent(agent) call.","If you need a multi-step body inside the loop, wrap the steps in one SequentialAgent and pass that as the single subAgent.","If you need multiple independent agents run once each, use ParallelAgent or SequentialAgent instead of LoopAgent."],"exampleFix":"// before\nLoopAgent agent = LoopAgent.builder()\n    .subAgents(List.of(stepA, stepB)) // throws UnsupportedOperationException\n    .build();\n// after\nAgent body = SequentialAgent.builder().subAgents(List.of(stepA, stepB)).build();\nLoopAgent agent = LoopAgent.builder()\n    .subAgent(body)\n    .loopStrategy(LoopStrategy.maxIterations(3))\n    .build();","handlingStrategy":"type-guard","validationCode":"if (agents.size() != 1) {\n    throw new IllegalArgumentException(\"LoopAgent accepts exactly one subAgent; use subAgent(), not subAgents()\");\n}","typeGuard":"static boolean supportsMultiSubAgents(Class<? extends Agent.Builder> builderClass) {\n    return !LoopAgentBuilder.class.isAssignableFrom(builderClass);\n}","tryCatchPattern":"try {\n    loopBuilder.subAgents(agents);\n} catch (UnsupportedOperationException e) {\n    loopBuilder.subAgent(agents.get(0));\n}","preventionTips":["Use subAgent(Agent) for LoopAgent; reserve subAgents(List) for Sequential/Parallel agents.","Wrap multi-step loop bodies in a SequentialAgent.","Avoid generic builder code that treats all agent builders identically."],"tags":["java","loop-agent","unsupported-operation","builder"],"backgroundTag":"unsupported-operation","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"}