alibaba/spring-ai-alibaba · error · IllegalArgumentException

Sequential flow requires root agent to be a FlowAgent

Error message

Sequential flow requires root agent to be a FlowAgent

What it means

validateSequentialConfig in SequentialGraphBuildingStrategy throws when the root agent is not a FlowAgent — sequential wiring relies on FlowAgent's input-key contracts, so other root types are rejected.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/strategy/SequentialGraphBuildingStrategy.java:107

	@Override
	public void validateConfig(FlowGraphBuilder.FlowGraphConfig config) {
		super.validateConfig(config);
		validateSequentialConfig(config);
	}

	/**
	 * Validates sequential-specific configuration requirements.
	 * @param config the configuration to validate
	 * @throws IllegalArgumentException if validation fails
	 */
	private void validateSequentialConfig(FlowGraphBuilder.FlowGraphConfig config) {
		if (config.getSubAgents() == null || config.getSubAgents().isEmpty()) {
			throw new IllegalArgumentException("Sequential flow requires at least one sub-agent");
		}

		// Ensure root agent is a FlowAgent for input key access
		if (!(config.getRootAgent() instanceof FlowAgent)) {
			throw new IllegalArgumentException("Sequential flow requires root agent to be a FlowAgent");
		}
	}

}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Make the root a FlowAgent subclass (e.g. SequentialAgent)
2. Update the builder/factory so the root is created as a FlowAgent
3. Extend FlowAgent for custom roots needing input-key access

Example fix

// before
FlowGraphConfig cfg = FlowGraphConfig.builder().rootAgent(plainAgent)...build();
// after
SequentialAgent root = SequentialAgent.builder().subAgents(a, b).build();

if (!(rootAgent instanceof FlowAgent)) {
    throw new IllegalStateException("Sequential root must be a FlowAgent");
}

static boolean isValidSequentialRoot(Agent a) { return a instanceof FlowAgent; }

When it happens

Trigger: Building a sequential flow whose config root is a plain BaseAgent or other non-FlowAgent implementation; validated in validateSequentialConfig during buildCoreGraph/validateConfig.

Common situations: Manually constructing FlowGraphConfig with a custom root; using a leaf LlmAgent as the root of a sequential pipeline; class hierarchy changes after refactoring.

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

• Sequential flow requires at least one sub-agent
• Parallel flow requires root agent to be a FlowAgent
• maxConcurrency must be at least 1, but got:
• Routing flow requires at least one sub-agent
• Routing flow requires root agent to be a FlowAgent

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