alibaba/spring-ai-alibaba · error · IllegalArgumentException

Routing sub-agents must be BaseAgent for merge support

Error message

Routing sub-agents must be BaseAgent for merge support

What it means

RoutingGraphBuildingStrategy adds a merge node that needs BaseAgent instances (RoutingMergeNode operates on List<BaseAgent>). Throwing IllegalArgumentException when any sub-agent in the routing config is not a BaseAgent.

Source

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

		String firstBeforeModelNode = routingNodeName;
		if (!beforeModelHooks.isEmpty()) {
			firstBeforeModelNode = connectBeforeModelHookEdges(graph, routingNodeName, beforeModelHooks);
		}
		graph.addEdge(rootAgent.name(), firstBeforeModelNode);

		// Step 3: Connect afterModel hooks after routing node (if any)
		// The hook nodes are already added by parent class, we just need to connect edges
		String routingExitNode = routingNodeName;
		if (!afterModelHooks.isEmpty()) {
			routingExitNode = connectAfterModelHookEdges(graph, routingNodeName, afterModelHooks);
		}

		// Step 4: Add merge node for result synthesis
		String mergeNodeName = rootAgent.name() + "_merge";
		List<BaseAgent> baseAgentList = new ArrayList<>(config.getSubAgents().size());
		for (Agent subAgent : config.getSubAgents()) {
			if (!(subAgent instanceof BaseAgent)) {
				throw new IllegalArgumentException("Routing sub-agents must be BaseAgent for merge support");
			}
			baseAgentList.add((BaseAgent) subAgent);
		}
		graph.addNode(mergeNodeName, node_async(new RoutingMergeNode(config.getChatModel(), baseAgentList)));

		// Step 5: Process sub-agents for routing
		Map<String, String> edgeRoutingMap = new HashMap<>();
		for (Agent subAgent : config.getSubAgents()) {
			// Add the current sub-agent as a node
			FlowGraphBuildingStrategy.addSubAgentNode(subAgent, graph);
			edgeRoutingMap.put(subAgent.name(), subAgent.name());
			// Connect sub-agents to merge node (dedicated node for result merging)
			graph.addEdge(subAgent.name(), mergeNodeName);
		}
		graph.addEdge(mergeNodeName, this.exitNode);

		// Step 6: Add parallel conditional edges for routing
		// This allows routing to one or multiple sub-agents in parallel

View on GitHub (pinned to f82da0b50f)

Solutions

1. Ensure every routing sub-agent extends BaseAgent
2. Wrap non-BaseAgent logic in a BaseAgent implementation
3. Move composite/flow agents out of the routing branch list

Example fix

// before
List<Agent> branches = List.of(new MyCustomAgent("a"), someFlowAgent);
// after
List<BaseAgent> branches = List.of(new LlmAgent("a", model), new LlmAgent("b", model));

for (Agent a : config.getSubAgents()) {
    if (!(a instanceof BaseAgent)) {
        throw new IllegalArgumentException("Routing branch not BaseAgent: " + a.getClass().getName());
    }
}

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

When it happens

Trigger: Calling buildCoreGraph for a routing flow where one or more entries of config.getSubAgents() are Agent implementations that do not extend BaseAgent (e.g. wrapping composite or custom agents).

Common situations: Mixing flow/composite agents with leaf agents in a routing branch list; using a custom Agent implementation as a routing branch; API changes where subAgents accepts Agent but the strategy narrows to BaseAgent.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Routing flow requires at least one sub-agent
• Routing flow requires a ChatModel for decision making
• Routing flow requires root agent to be a FlowAgent
• No default output or error next node provided
• Sub-agents must be BaseAgent

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