{"record":{"id":"ea9b00e4580fe4c3","repo":"alibaba/spring-ai-alibaba","slug":"only-supports-flowagent-and-baseagent-types","errorCode":null,"errorMessage":" only supports FlowAgent and BaseAgent types","messagePattern":" only supports FlowAgent and BaseAgent types","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/strategy/FlowGraphBuildingStrategy.java","lineNumber":152,"sourceCode":"\t * @param defaultStrategy the default strategy to use when none is specified\n\t */\n\tdefault void processOutputKey(String outputKey, KeyStrategy outputKeyStrategy, Map<String, KeyStrategy> keyStrategyMap, KeyStrategy defaultStrategy) {\n\t\tif (outputKey != null) {\n\t\t\tif (outputKeyStrategy != null) {\n\t\t\t\tkeyStrategyMap.put(outputKey, outputKeyStrategy);\n\t\t\t} else {\n\t\t\t\tkeyStrategyMap.put(outputKey, defaultStrategy);\n\t\t\t}\n\t\t}\n\t}\n\n\tstatic void addSubAgentNode(Agent subAgent, StateGraph newGraph) throws GraphStateException {\n\t\tif (subAgent instanceof FlowAgent flowAgent) {\n\t\t\tnewGraph.addNode(flowAgent.name(), new SubCompiledGraphNode(flowAgent.name(), flowAgent.getAndCompileGraph()));\n\t\t} else if (subAgent instanceof BaseAgent baseAgent) {\n\t\t\tnewGraph.addNode(baseAgent.name(), baseAgent.asNode(baseAgent.isIncludeContents(), baseAgent.isReturnReasoningContents()));\n\t\t} else {\n\t\t\tthrow new IllegalArgumentException(subAgent.getClass().getName() + \" only supports FlowAgent and BaseAgent types\");\n\t\t}\n\t}\n\n}\n","sourceCodeStart":134,"sourceCodeEnd":157,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/strategy/FlowGraphBuildingStrategy.java#L134-L157","documentation":"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.","triggerScenarios":"Passing a custom Agent implementation (neither FlowAgent nor BaseAgent) into a flow builder's agent list, often after implementing the Agent interface directly.","commonSituations":"Custom in-house agent classes written against an older framework API; third-party agent types; migration where BaseAgent/FlowAgent hierarchy changed.","solutions":["Extend BaseAgent (or FlowAgent) instead of implementing Agent directly, and override asNode(...) as needed","If the custom agent wraps another framework agent, expose it as a BaseAgent subclass","Check the class in the exception message and migrate it to the supported hierarchy"],"exampleFix":"// before\nclass MyAgent implements Agent { ... }\n// after\nclass MyAgent extends BaseAgent { ... } // gets asNode() support","handlingStrategy":"type-guard","validationCode":"if (!(a instanceof FlowAgent) && !(a instanceof BaseAgent)) throw new IllegalArgumentException(a.getClass().getName() + \" is not supported as a sub-agent\");","typeGuard":"static boolean isSupportedSubAgent(Agent a) { return a instanceof FlowAgent || a instanceof BaseAgent; }","tryCatchPattern":"try { return builder.build(); } catch (IllegalArgumentException e) { log.error(\"Unsupported sub-agent type: {}\", e.getMessage()); throw e; }","preventionTips":["Extend BaseAgent/FlowAgent instead of implementing Agent directly","Keep custom agents in sync with the framework hierarchy on upgrades","Filter or map unsupported agent types before adding to a flow"],"tags":["type-mismatch","agent-framework","unsupported-type"],"backgroundTag":"unsupported-operation","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}