{"record":{"id":"012a4e795b62375c","repo":"alibaba/spring-ai-alibaba","slug":"sequential-flow-requires-root-agent-to-be-a-flowag","errorCode":null,"errorMessage":"Sequential flow requires root agent to be a FlowAgent","messagePattern":"Sequential flow requires root agent to be a FlowAgent","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/strategy/SequentialGraphBuildingStrategy.java","lineNumber":107,"sourceCode":"\t@Override\n\tpublic void validateConfig(FlowGraphBuilder.FlowGraphConfig config) {\n\t\tsuper.validateConfig(config);\n\t\tvalidateSequentialConfig(config);\n\t}\n\n\t/**\n\t * Validates sequential-specific configuration requirements.\n\t * @param config the configuration to validate\n\t * @throws IllegalArgumentException if validation fails\n\t */\n\tprivate void validateSequentialConfig(FlowGraphBuilder.FlowGraphConfig config) {\n\t\tif (config.getSubAgents() == null || config.getSubAgents().isEmpty()) {\n\t\t\tthrow new IllegalArgumentException(\"Sequential flow requires at least one sub-agent\");\n\t\t}\n\n\t\t// Ensure root agent is a FlowAgent for input key access\n\t\tif (!(config.getRootAgent() instanceof FlowAgent)) {\n\t\t\tthrow new IllegalArgumentException(\"Sequential flow requires root agent to be a FlowAgent\");\n\t\t}\n\t}\n\n}\n","sourceCodeStart":89,"sourceCodeEnd":112,"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/SequentialGraphBuildingStrategy.java#L89-L112","documentation":"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.","triggerScenarios":"Building a sequential flow whose config root is a plain BaseAgent or other non-FlowAgent implementation; validated in validateSequentialConfig during buildCoreGraph/validateConfig.","commonSituations":"Manually constructing FlowGraphConfig with a custom root; using a leaf LlmAgent as the root of a sequential pipeline; class hierarchy changes after refactoring.","solutions":["Make the root a FlowAgent subclass (e.g. SequentialAgent)","Update the builder/factory so the root is created as a FlowAgent","Extend FlowAgent for custom roots needing input-key access"],"exampleFix":"// before\nFlowGraphConfig cfg = FlowGraphConfig.builder().rootAgent(plainAgent)...build();\n// after\nSequentialAgent root = SequentialAgent.builder().subAgents(a, b).build();","handlingStrategy":"validation","validationCode":"if (!(rootAgent instanceof FlowAgent)) {\n    throw new IllegalStateException(\"Sequential root must be a FlowAgent\");\n}","typeGuard":"static boolean isValidSequentialRoot(Agent a) { return a instanceof FlowAgent; }","tryCatchPattern":null,"preventionTips":["Use SequentialAgent.builder() so the root is a FlowAgent","Do not use leaf LlmAgents as pipeline roots","Verify root type when building FlowGraphConfig manually"],"tags":["java","agent-framework","sequential","validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}