alibaba/spring-ai-alibaba · error · UnsupportedOperationException

LoopAgent must have only one subAgent, please use subAgent()

Error message

LoopAgent must have only one subAgent, please use subAgent() method.

What it means

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.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/agent/LoopAgent.java:95

    }

    public static class LoopAgentBuilder extends FlowAgentBuilder<LoopAgent, LoopAgentBuilder> {

        private LoopStrategy loopStrategy = null;

        @Override
        protected LoopAgentBuilder self() {
            return this;
        }

        public LoopAgentBuilder subAgent(Agent subAgent) {
            this.subAgents = List.of(subAgent);
            return self();
        }

        @Override
        public LoopAgentBuilder subAgents(List<Agent> subAgents) {
            throw new UnsupportedOperationException("LoopAgent must have only one subAgent, please use subAgent() method.");
        }

        public LoopAgentBuilder loopStrategy(LoopStrategy loopStrategy) {
            this.loopStrategy = loopStrategy;
            return self();
        }

        @Override
        protected void validate() {
            super.validate();
            if (this.loopStrategy == null) {
                throw new IllegalArgumentException("LoopAgent must have a loopStrategy.");
            }
        }

        @Override
        public LoopAgent doBuild() {
            validate();

View on GitHub (pinned to f82da0b50f)

Solutions

1. Replace subAgents(list) with a single subAgent(agent) call.
2. If you need a multi-step body inside the loop, wrap the steps in one SequentialAgent and pass that as the single subAgent.
3. If you need multiple independent agents run once each, use ParallelAgent or SequentialAgent instead of LoopAgent.

Example fix

// before
LoopAgent agent = LoopAgent.builder()
    .subAgents(List.of(stepA, stepB)) // throws UnsupportedOperationException
    .build();
// after
Agent body = SequentialAgent.builder().subAgents(List.of(stepA, stepB)).build();
LoopAgent agent = LoopAgent.builder()
    .subAgent(body)
    .loopStrategy(LoopStrategy.maxIterations(3))
    .build();

if (agents.size() != 1) {
    throw new IllegalArgumentException("LoopAgent accepts exactly one subAgent; use subAgent(), not subAgents()");
}

static boolean supportsMultiSubAgents(Class<? extends Agent.Builder> builderClass) {
    return !LoopAgentBuilder.class.isAssignableFrom(builderClass);
}

try {
    loopBuilder.subAgents(agents);
} catch (UnsupportedOperationException e) {
    loopBuilder.subAgent(agents.get(0));
}

When it happens

Trigger: Calling LoopAgent.builder().subAgents(List.of(a, b)) or any subAgents(list) call on LoopAgentBuilder.

Common situations: 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.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• LoopAgent must have a loopStrategy.
• Sub-agents must be BaseAgent
• Loop flow requires a valid LoopStrategy. Got: null
• Loop flow requires exactly one sub-agent. Got: 0
• At least one fallback model must be specified

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/92dd855d359cb401. Report an issue: GitHub.