{"record":{"id":"947aeb4593d2c09f","repo":"alibaba/spring-ai-alibaba","slug":"the-root-agent-must-be-an-instance-of-reactagent-o","errorCode":null,"errorMessage":"The root agent must be an instance of ReactAgent or A2aRemoteAgent, other type will be supported later.","messagePattern":"The root agent must be an instance of ReactAgent or A2aRemoteAgent, other type will be supported later\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-boot-starters/spring-ai-alibaba-starter-a2a-nacos/src/main/java/com/alibaba/cloud/ai/a2a/autoconfigure/server/A2aServerHandlerAutoConfiguration.java","lineNumber":76,"sourceCode":" */\n@AutoConfiguration(after = { A2aServerAgentCardAutoConfiguration.class, A2aServerMultiAgentAutoConfiguration.class })\n@EnableConfigurationProperties({ A2aServerProperties.class })\n@ConditionalOnBean({ AgentCard.class, Agent.class })\n@ConditionalOnMissingBean(MultiAgentRequestRouter.class)\npublic class A2aServerHandlerAutoConfiguration {\n\n\t@Bean\n\t@ConditionalOnMissingBean\n\tpublic A2aServerExecutorProvider a2aServerExecutorProvider() {\n\t\treturn new DefaultA2aServerExecutorProvider();\n\t}\n\n\t@Bean\n\t@ConditionalOnMissingBean\n\tpublic AgentExecutor agentExecutor(Agent rootAgent) {\n\t\t// FIXME: currently only ReactAgent and A2aRemoteAgent are supported as the root\n\t\tif (!(rootAgent instanceof ReactAgent) && !(rootAgent instanceof A2aRemoteAgent)) {\n\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\"The root agent must be an instance of ReactAgent or A2aRemoteAgent, other type will be supported later.\");\n\t\t}\n\t\treturn new GraphAgentExecutor(rootAgent);\n\t}\n\n\t@Bean\n\t@ConditionalOnMissingBean\n\tpublic TaskStore taskStore() {\n\t\treturn new InMemoryTaskStore();\n\t}\n\n\t@Bean\n\t@ConditionalOnMissingBean\n\tpublic QueueManager queueManager() {\n\t\treturn new InMemoryQueueManager();\n\t}\n\n\t@Bean","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-boot-starters/spring-ai-alibaba-starter-a2a-nacos/src/main/java/com/alibaba/cloud/ai/a2a/autoconfigure/server/A2aServerHandlerAutoConfiguration.java#L58-L94","documentation":"A2aServerHandlerAutoConfiguration.agentExecutor creates the AgentExecutor bean used to serve A2A requests, but the current implementation only knows how to execute a root agent that is a ReactAgent or an A2aRemoteAgent (GraphAgentExecutor). If the published root Agent bean is any other Agent implementation, the configuration throws IllegalArgumentException at bean creation, failing application startup with a clear FIXME note that other types will be supported later.","triggerScenarios":"Publishing an A2A server via the spring-ai-alibaba-starter-a2a-nacos auto-configuration while the primary/root Agent bean is not a ReactAgent or A2aRemoteAgent — e.g., it is a plain GraphAgent, a SequentialAgent/ParallelAgent/LoopAgent, or a custom Agent implementation.","commonSituations":"Users wrap workflow agents (SequentialAgent, LoopAgent, custom agents) as the A2A root; upgrading from a version where another agent type was accepted; defining multiple Agent beans so the auto-configured root resolves to an unsupported one.","solutions":["Make the root agent a ReactAgent (or A2aRemoteAgent for remote agents) — e.g., use ReactAgent.builder()...build() and mark it @Primary.","Define your own AgentExecutor bean; the auto-config is @ConditionalOnMissingBean, so providing a custom AgentExecutor that supports your agent type bypasses this check.","Compose unsupported agents inside a ReactAgent (wrap the workflow as a tool/sub-graph) so the exported root is a ReactAgent.","Track framework updates — other root agent types are planned ('will be supported later')."],"exampleFix":"// before\n@Bean\npublic Agent myAgent() { return new SequentialAgent(...); } // startup fails\n// after\n@Bean\npublic Agent myAgent() { return ReactAgent.builder().name(\"my-agent\").subAgents(...).build(); }","handlingStrategy":"type-guard","validationCode":"if (!(agent instanceof ReactAgent) && !(agent instanceof A2aRemoteAgent)) {\n    throw new IllegalArgumentException(\"A2A root agent must be ReactAgent or A2aRemoteAgent: \" + agent.getClass());\n}","typeGuard":"boolean isA2aSupportedRoot(Agent a) { return a instanceof ReactAgent || a instanceof A2aRemoteAgent; }","tryCatchPattern":null,"preventionTips":["Expose only ReactAgent or A2aRemoteAgent as the root/primary Agent bean for A2A publishing","Wrap workflow agents (Sequential/Parallel/Loop) inside a ReactAgent before publishing","Provide a custom AgentExecutor bean if you need other root types","Mark the intended root agent bean @Primary when multiple Agent beans exist"],"tags":["a2a","spring-boot","startup-failure","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-14T05:17:10.506Z"}