alibaba/spring-ai-alibaba · error · IllegalArgumentException

ParallelAgent supports maximum 10 sub-agents for…

Error message

ParallelAgent supports maximum 10 sub-agents for performance reasons, but got: 10

What it means

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.

Solutions

1. Reduce the number of sub-agents to 10 or fewer, batching work inside agents if needed
2. Split the fan-out into multiple ParallelAgents or a loop/sequential stage
3. Patch the pipeline to chunk the agent list before building

Example fix

// before
ParallelAgent.builder().name("p").subAgents(allAgents).build(); // allAgents.size() > 10
// after
List<Agent> batch = allAgents.subList(0, 10);
ParallelAgent.builder().name("p").subAgents(batch).build();

if (subAgents != null && subAgents.size() > 10) subAgents = subAgents.subList(0, 10);

boolean withinParallelCap(java.util.List<Agent> a) { return a != null && a.size() <= 10; }

try { agent = builder.build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("maximum 10 sub-agents")) { /* chunk the fan-out */ } else throw e; }

When it happens

Trigger: ParallelAgent.builder().name("x").subAgents(moreThanTenAgents).build(), or dynamically collecting agents so the list exceeds 10.

Common situations: Auto-generating one sub-agent per data source or tool; scaling a fan-out pipeline and silently crossing the cap.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• AgentCard or AgentCardProvider must be provided
• AgentScope Model must be provided for AgentScope routing…
• AgentScope routing flow requires at least one sub-agent
• appName cannot be null or empty
• 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/ed74163cbca52352. Report an issue: GitHub.

Appendix: source

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

		 */
		@Override
		protected void validate() {
			// Validate name first (from parent)
			if (name == null || name.trim().isEmpty()) {
				throw new IllegalArgumentException("Name must be provided");
			}

			// Validate minimum sub-agent count for ParallelAgent (skip parent subAgents
			// check)
			if (subAgents == null || subAgents.size() < 2) {
				throw new IllegalArgumentException(
						"ParallelAgent requires at least 2 sub-agents for parallel execution, but got: "
								+ (subAgents != null ? subAgents.size() : 0));
			}

			// Validate maximum sub-agent count for performance reasons
			if (subAgents.size() > 10) {
				throw new IllegalArgumentException(
						"ParallelAgent supports maximum 10 sub-agents for performance reasons, but got: "
								+ subAgents.size());
			}

			// Validate that sub-agents have unique output keys to avoid conflicts during
			// result merging
			validateUniqueOutputKeys();

			// Validate input key compatibility
			validateInputKeyCompatibility();

			// Validate concurrency limit - allow maxConcurrency to be null (unlimited) or
			// within valid range
			if (maxConcurrency != null) {
				if (maxConcurrency < 1) {
					throw new IllegalArgumentException("maxConcurrency must be at least 1, but got: " + maxConcurrency);
				}
			}

View on GitHub (pinned to f82da0b50f)