alibaba/spring-ai-alibaba · error · IllegalArgumentException

AgentScope Model must be provided for AgentScope routing age

Error message

AgentScope Model must be provided for AgentScope routing agent

What it means

AgentScopeRoutingAgent.Builder.validate() enforces that a routing agent has a Model configured. The routing agent must call an LLM to select which sub-agent to execute, so building without a model is invalid and throws IllegalArgumentException during build().

Source

Thrown at spring-boot-starters/spring-ai-alibaba-starter-agentscope/src/main/java/com/alibaba/cloud/ai/agent/agentscope/flow/AgentScopeRoutingAgent.java:110

			this.systemPrompt = systemPrompt;
			return this;
		}

		public AgentScopeRoutingAgentBuilder instruction(String instruction) {
			this.instruction = instruction;
			return this;
		}

		@Override
		protected AgentScopeRoutingAgentBuilder self() {
			return this;
		}

		@Override
		protected void validate() {
			super.validate();
			if (model == null) {
				throw new IllegalArgumentException("AgentScope Model must be provided for AgentScope routing agent");
			}
		}

		@Override
		public AgentScopeRoutingAgent doBuild() {
			validate();
			return new AgentScopeRoutingAgent(this);
		}
	}
}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Call .model(...) on the AgentScopeRoutingAgent builder with a configured Model instance (e.g. DashScope/OpenAI chat model).
2. Ensure the model bean exists: check API key configuration for the model provider.
3. If constructing via FlowGraphBuilder config, set the "agentScopeModel" custom property so the model is propagated.

Example fix

// before
AgentScopeRoutingAgent agent = AgentScopeRoutingAgent.builder()
    .name("router")
    .subAgents(subAgents)
    .build(); // IllegalArgumentException
// after
AgentScopeRoutingAgent agent = AgentScopeRoutingAgent.builder()
    .name("router")
    .model(chatModel)
    .subAgents(subAgents)
    .build();

// Java: validate builder inputs before building
if (model == null) {
    throw new IllegalStateException("Provide a Model via AgentScopeRoutingAgent.builder().model(...) before build()");
}
if (subAgents == null || subAgents.isEmpty()) {
    throw new IllegalStateException("Routing agent requires at least one sub-agent");
}

// Java
boolean hasModel(AgentScopeRoutingAgent.Builder b, Model m) {
    return m != null; // check the model instance before passing to the builder
}

When it happens

Trigger: Building an AgentScopeRoutingAgent via its builder without calling the model(...) setter (or passing null), then invoking build()/doBuild() which triggers validate().

Common situations: Forgot to set the model on the builder; model bean is null due to failed conditional auto-configuration (no model API key); refactoring removed the model assignment; copying a builder from another agent type that doesn't require a model.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• AgentScope routing flow requires at least one sub-agent
• Version ID cannot be null
• 模型配置不能为空
• maxDelay must be greater than or equal to 0.
• maxCachedThreads must be greater than or equal to 0

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