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

AgentScopeRoutingGraphBuildingStrategy.buildCoreGraph() converts every configured sub-agent into a BaseAgent so the routing merge node can merge their outputs. If a sub-agent is not an instance of BaseAgent (e.g. a wrapper or custom Agent implementation), the merge machinery cannot handle it and an IllegalArgumentException is thrown while building the graph.

Source

Thrown at spring-boot-starters/spring-ai-alibaba-starter-agentscope/src/main/java/com/alibaba/cloud/ai/agent/agentscope/flow/AgentScopeRoutingGraphBuildingStrategy.java:80

		String routingNodeName = rootAgent.name() + "_routing";
		graph.addNode(routingNodeName, node_async((state) -> Map.of()));

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

		String routingExitNode = routingNodeName;
		if (!afterModelHooks.isEmpty()) {
			routingExitNode = connectAfterModelHookEdges(graph, routingNodeName, afterModelHooks);
		}

		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 AgentScopeRoutingMergeNode(model, baseAgentList)));

		Map<String, String> edgeRoutingMap = new HashMap<>();
		for (Agent subAgent : config.getSubAgents()) {
			com.alibaba.cloud.ai.graph.agent.flow.strategy.FlowGraphBuildingStrategy.addSubAgentNode(subAgent, graph);
			edgeRoutingMap.put(subAgent.name(), subAgent.name());
			graph.addEdge(subAgent.name(), mergeNodeName);
		}
		graph.addEdge(mergeNodeName, this.exitNode);

		AgentScopeRoutingNode routingNode = new AgentScopeRoutingNode(model, rootAgent, config.getSubAgents(), systemPrompt);
		graph.addParallelConditionalEdges(
				routingExitNode,
				AsyncMultiCommandAction.node_async(routingNode),
				edgeRoutingMap);

View on GitHub (pinned to f82da0b50f)

Solutions

1. Ensure all sub-agents passed to the routing flow extend BaseAgent (AgentScope agent hierarchy).
2. Wrap or replace foreign Agent implementations with BaseAgent-compatible equivalents.
3. If a custom agent type is required, extend BaseAgent so routing/merge works.
4. Log/inspect the sub-agents list before building to find the offending instance type.

Example fix

// before
List<Agent> subs = List.of(new MyCustomAgent()); // does not extend BaseAgent
builder.subAgents(subs);
// after
List<Agent> subs = List.of(new AgentScopeSubAgent()); // extends BaseAgent
builder.subAgents(subs);

// Java: verify all sub-agents extend BaseAgent before building
List<Agent> bad = subAgents.stream()
    .filter(a -> !(a instanceof BaseAgent))
    .toList();
if (!bad.isEmpty()) {
    throw new IllegalStateException("Non-BaseAgent sub-agents: " + bad.stream().map(a -> a.getClass().getName()).toList());
}

// Java
static boolean isMergeCompatible(Agent a) {
    return a instanceof BaseAgent;
}
// use: subAgents.stream().allMatch(FlowGuard::isMergeCompatible)

// Java
try {
    flow = AgentScopeRoutingFlow.builder()...build();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("must be BaseAgent")) {
        LOGGER.error("Sub-agent types: {}", subAgents.stream().map(Object::getClass).toList());
    }
    throw e;
}

When it happens

Trigger: Building a routing flow whose FlowGraphConfig.subAgents list contains an Agent implementation that does not extend BaseAgent.

Common situations: Mixing agents from different frameworks/wrappers into an AgentScope routing flow; using a custom Agent subclass that doesn't extend BaseAgent; passing placeholder/decorator agents; library upgrade changed the agent base class hierarchy.

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

• AgentScope routing flow requires at least one sub-agent
• AgentScope routing flow requires agentScopeModel in config c
• AgentScope routing flow requires root agent to be AgentScope
• Routing sub-agents must be BaseAgent for merge support
• Action must be either AsyncCommandAction or AsyncMultiComman

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