alibaba/spring-ai-alibaba · error · IllegalArgumentException

SubAgent description is required

Error message

SubAgent description is required

What it means

SubAgentSpec's builder validates that the sub-agent has a non-blank description in build(). The description is exposed to the parent (e.g., LLM routing) agent so it can decide when to delegate to this sub-agent; a missing description would make delegation impossible. The check throws IllegalArgumentException when description is null or whitespace-only.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/extension/interceptor/SubAgentSpec.java:156

		 * Set custom interceptors for this subagent.
		 * These will be applied after the default interceptors from SubAgentInterceptor.
		 */
		public Builder interceptors(List<ModelInterceptor> interceptors) {
			this.interceptors = interceptors;
			return this;
		}

		public Builder enableLoopingLog(boolean enableLoopingLog) {
			this.enableLoopingLog = enableLoopingLog;
			return this;
		}

		public SubAgentSpec build() {
			if (name == null || name.trim().isEmpty()) {
				throw new IllegalArgumentException("SubAgent name is required");
			}
			if (description == null || description.trim().isEmpty()) {
				throw new IllegalArgumentException("SubAgent description is required");
			}
			if (systemPrompt == null || systemPrompt.trim().isEmpty()) {
				throw new IllegalArgumentException("SubAgent system prompt is required");
			}
			return new SubAgentSpec(this);
		}
	}
}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Add a meaningful description(...) call before build() so the parent agent can route to this sub-agent.
2. If the description originates from config/annotations, validate non-blank upstream and surface a clear config error.
3. Order the builder calls name() -> description() -> systemPrompt() as a habit so none are missed.

Example fix

// before
SubAgentSpec spec = SubAgentSpec.builder()
    .name("billing-agent")
    .systemPrompt("You are a billing agent")
    .build();
// after
SubAgentSpec spec = SubAgentSpec.builder()
    .name("billing-agent")
    .description("Handles billing and invoice questions")
    .systemPrompt("You are a billing agent")
    .build();

if (description == null || description.trim().isEmpty()) {
    throw new IllegalArgumentException("Cannot build SubAgentSpec: description is required for routing");
}

static boolean hasText(String s) { return s != null && !s.trim().isEmpty(); }

try {
    spec = SubAgentSpec.builder()...build();
} catch (IllegalArgumentException e) {
    log.error("SubAgentSpec missing field: {}", e.getMessage());
}

When it happens

Trigger: Calling SubAgentSpec.builder()...build() without calling description(String), or passing null/""/blank text to description().

Common situations: Writing a minimal test spec and skipping the description; converting legacy agent configs that only carried a name; assuming description is optional because name and systemPrompt are set.

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

• SubAgent name is required
• SubAgent system prompt is required
• ChatModel must be provided for LLM routing agent
• LoopAgent must have a loopStrategy.
• Sub-agents must be provided

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