alibaba/spring-ai-alibaba · error · IllegalArgumentException

The root agent must be an instance of ReactAgent or A2aRemot

Error message

The root agent must be an instance of ReactAgent or A2aRemoteAgent, other type will be supported later.

What it means

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.

Source

Thrown at spring-boot-starters/spring-ai-alibaba-starter-a2a-nacos/src/main/java/com/alibaba/cloud/ai/a2a/autoconfigure/server/A2aServerHandlerAutoConfiguration.java:76

 */
@AutoConfiguration(after = { A2aServerAgentCardAutoConfiguration.class, A2aServerMultiAgentAutoConfiguration.class })
@EnableConfigurationProperties({ A2aServerProperties.class })
@ConditionalOnBean({ AgentCard.class, Agent.class })
@ConditionalOnMissingBean(MultiAgentRequestRouter.class)
public class A2aServerHandlerAutoConfiguration {

	@Bean
	@ConditionalOnMissingBean
	public A2aServerExecutorProvider a2aServerExecutorProvider() {
		return new DefaultA2aServerExecutorProvider();
	}

	@Bean
	@ConditionalOnMissingBean
	public AgentExecutor agentExecutor(Agent rootAgent) {
		// FIXME: currently only ReactAgent and A2aRemoteAgent are supported as the root
		if (!(rootAgent instanceof ReactAgent) && !(rootAgent instanceof A2aRemoteAgent)) {
			throw new IllegalArgumentException(
					"The root agent must be an instance of ReactAgent or A2aRemoteAgent, other type will be supported later.");
		}
		return new GraphAgentExecutor(rootAgent);
	}

	@Bean
	@ConditionalOnMissingBean
	public TaskStore taskStore() {
		return new InMemoryTaskStore();
	}

	@Bean
	@ConditionalOnMissingBean
	public QueueManager queueManager() {
		return new InMemoryQueueManager();
	}

	@Bean

View on GitHub (pinned to f82da0b50f)

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').

Example fix

// before
@Bean
public Agent myAgent() { return new SequentialAgent(...); } // startup fails
// after
@Bean
public Agent myAgent() { return ReactAgent.builder().name("my-agent").subAgents(...).build(); }

Defensive patterns

Strategy: type-guard

Validate before calling

if (!(agent instanceof ReactAgent) && !(agent instanceof A2aRemoteAgent)) {
    throw new IllegalArgumentException("A2A root agent must be ReactAgent or A2aRemoteAgent: " + agent.getClass());
}

Type guard

boolean isA2aSupportedRoot(Agent a) { return a instanceof ReactAgent || a instanceof A2aRemoteAgent; }

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

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

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