alibaba/spring-ai-alibaba · error · IllegalArgumentException

only supports FlowAgent and BaseAgent types

Error message

 only supports FlowAgent and BaseAgent types

What it means

addSubAgentNode can only register sub-agents that are FlowAgent (compiled sub-graph) or BaseAgent (wrapped via asNode). Any other Agent implementation is rejected with an IllegalArgumentException prefixed by the offending class name, because the strategy has no way to compile it into a graph node.

Solutions

1. Extend BaseAgent (or FlowAgent) instead of implementing Agent directly, and override asNode(...) as needed
2. If the custom agent wraps another framework agent, expose it as a BaseAgent subclass
3. Check the class in the exception message and migrate it to the supported hierarchy

Example fix

// before
class MyAgent implements Agent { ... }
// after
class MyAgent extends BaseAgent { ... } // gets asNode() support

if (!(a instanceof FlowAgent) && !(a instanceof BaseAgent)) throw new IllegalArgumentException(a.getClass().getName() + " is not supported as a sub-agent");

static boolean isSupportedSubAgent(Agent a) { return a instanceof FlowAgent || a instanceof BaseAgent; }

try { return builder.build(); } catch (IllegalArgumentException e) { log.error("Unsupported sub-agent type: {}", e.getMessage()); throw e; }

When it happens

Trigger: Passing a custom Agent implementation (neither FlowAgent nor BaseAgent) into a flow builder's agent list, often after implementing the Agent interface directly.

Common situations: Custom in-house agent classes written against an older framework API; third-party agent types; migration where BaseAgent/FlowAgent hierarchy changed.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Routing sub-agents must be BaseAgent for merge support
• Action must be either AsyncCommandAction or…
• App spec is not Agent
• Cannot append to non-list value for key
• Cannot merge incompatible types

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

Appendix: source

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

	 * @param defaultStrategy the default strategy to use when none is specified
	 */
	default void processOutputKey(String outputKey, KeyStrategy outputKeyStrategy, Map<String, KeyStrategy> keyStrategyMap, KeyStrategy defaultStrategy) {
		if (outputKey != null) {
			if (outputKeyStrategy != null) {
				keyStrategyMap.put(outputKey, outputKeyStrategy);
			} else {
				keyStrategyMap.put(outputKey, defaultStrategy);
			}
		}
	}

	static void addSubAgentNode(Agent subAgent, StateGraph newGraph) throws GraphStateException {
		if (subAgent instanceof FlowAgent flowAgent) {
			newGraph.addNode(flowAgent.name(), new SubCompiledGraphNode(flowAgent.name(), flowAgent.getAndCompileGraph()));
		} else if (subAgent instanceof BaseAgent baseAgent) {
			newGraph.addNode(baseAgent.name(), baseAgent.asNode(baseAgent.isIncludeContents(), baseAgent.isReturnReasoningContents()));
		} else {
			throw new IllegalArgumentException(subAgent.getClass().getName() + " only supports FlowAgent and BaseAgent types");
		}
	}

}

View on GitHub (pinned to f82da0b50f)