alibaba/spring-ai-alibaba · error · IllegalArgumentException

Sub-agents must be BaseAgent

Error message

Sub-agents must be BaseAgent

What it means

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.

Source

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

		 * @return this builder instance for method chaining
		 */
		public ParallelAgentBuilder mergeStrategy(MergeStrategy mergeStrategy) {
			this.mergeStrategy = mergeStrategy;
			return this;
		}

		public ParallelAgentBuilder mergeOutputKey(String mergeOutputKey) {
			this.mergeOutputKey = mergeOutputKey;
			return this;
		}

		@Override
		public ParallelAgentBuilder subAgents(List<Agent> subAgents) {
			if (subAgents == null || subAgents.isEmpty()) {
				throw new IllegalArgumentException("Sub-agents must be provided");
			}
			if (subAgents.stream().anyMatch(agent -> !(agent instanceof BaseAgent))) {
				throw new IllegalArgumentException("Sub-agents must be BaseAgent");
			}
			return super.subAgents(subAgents);
		}

		/**
		 * Sets the maximum number of sub-agents that can execute concurrently.
		 * @param maxConcurrency the maximum concurrency limit
		 * @return this builder instance for method chaining
		 */
		public ParallelAgentBuilder maxConcurrency(Integer maxConcurrency) {
			this.maxConcurrency = maxConcurrency;
			return this;
		}

		/**
		 * Returns the concrete builder instance for fluent interface support.
		 * @return this builder instance
		 */

View on GitHub (pinned to f82da0b50f)

Solutions

1. Make all list elements extend BaseAgent (or replace them with built-in agents like SequentialAgent/LoopAgent which do).
2. For tests, mock or subclass BaseAgent rather than the Agent interface.
3. Pre-validate the list with instanceof BaseAgent checks and log/exclude incompatible entries before calling subAgents().

Example fix

// before
Agent custom = new MyLightweightAgent(); // implements Agent only
parallelBuilder.subAgents(List.of(baseAgent1, custom)); // throws: Sub-agents must be BaseAgent
// after
BaseAgent custom = new MyLightweightAgent(); // now extends BaseAgent
parallelBuilder.subAgents(List.of(baseAgent1, custom));

for (Agent a : subAgents) {
    if (!(a instanceof BaseAgent)) {
        throw new IllegalArgumentException("Sub-agent " + a + " must extend BaseAgent");
    }
}

static boolean allBaseAgents(List<Agent> l) {
    return l.stream().allMatch(a -> a instanceof BaseAgent);
}

try {
    parallelBuilder.subAgents(agents);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("BaseAgent")) {
        log.error("Non-BaseAgent in sub-agent list: {}", e.getMessage());
    }
}

When it happens

Trigger: 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(...).

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

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• LoopAgent must have only one subAgent, please use subAgent()
• Sub-agents must be provided
• Loop flow requires a valid LoopStrategy. Got: null
• Parallel flow requires at least one sub-agent
• Parallel flow requires at least 2 sub-agents for meaningful

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