alibaba/spring-ai-alibaba · error · IllegalArgumentException

requires 'sub_agents' (array)

Error message

${type} requires 'sub_agents' (array)

What it means

requireSubAgents() throws this when the DSL root has no "sub_agents" field or it is not a List. Multi-agent types (SequentialAgent, ParallelAgent, RoutingAgent, LoopAgent, etc.) are defined by composition, so an array of sub-agents is mandatory. The provider refuses to generate code without it.

Solutions

1. Add a "sub_agents" array to the agent configuration root
2. Verify the exact key spelling is "sub_agents" (snake_case)
3. Ensure sub_agents is a JSON/YAML array, not an object or comma string

Example fix

// before
{"type": "sequential_agent", "name": "pipeline"}
// after
{"type": "sequential_agent", "name": "pipeline", "sub_agents": [{"type": "react_agent", "name": "step1", ...}]}

Object subs = config.get("sub_agents");
if (!(subs instanceof List) || ((List<?>) subs).isEmpty()) {
    throw new IllegalArgumentException("multi-agent config requires a non-empty 'sub_agents' array");
}

static boolean hasSubAgents(Map<String,Object> cfg) {
    return cfg.get("sub_agents") instanceof List<?> l && !l.isEmpty();
}

try {
    provider.validateDSL(root);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("requires 'sub_agents'")) {
        // report that the composition field is missing or the wrong shape
    }
}

When it happens

Trigger: validateSpecific() of a multi-agent provider calls requireSubAgents(root, minCount) and root.get("sub_agents") is null or an object/string instead of a List.

Common situations: Using a single-agent config template for a sequential/parallel agent type; YAML parsing turning sub_agents into a map; typo like "subAgents" or "subagents"; config missing after a schema version change.

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

• requires at least sub-agent(s), got
• must be a number
• invalid agent dsl: missing 'agent' object or flat agent…
• invalid agent dsl: 'type/agent_class' and 'name' are…
• invalid dify dsl

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

Appendix: source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-start/src/main/java/com/alibaba/cloud/ai/studio/admin/builder/generator/service/generator/agent/AbstractAgentTypeProvider.java:84

//		if (handle == null) {
//			throw new IllegalArgumentException(type() + " requires 'handle' configuration");
//		}
		if (handle == null) {
			handle = new HashMap<>();
		}
		return handle;
	}

	/**
	 * 校验必须有子代理
	 * @param root DSL 根对象
	 * @param minCount 最小数量
	 */
	@SuppressWarnings("unchecked")
	protected List<Map<String, Object>> requireSubAgents(Map<String, Object> root, int minCount) {
		Object subs = root.get("sub_agents");
		if (!(subs instanceof List)) {
			throw new IllegalArgumentException(type() + " requires 'sub_agents' (array)");
		}
		List<Map<String, Object>> subAgents = (List<Map<String, Object>>) subs;
		if (subAgents.size() < minCount) {
			throw new IllegalArgumentException(
					type() + " requires at least " + minCount + " sub-agent(s), got: " + subAgents.size());
		}
		return subAgents;
	}

	/**
	 * 校验数值字段
	 * @param value 字段值
	 * @param fieldName 字段名
	 * @param minValue 最小值（包含）
	 * @return 数值
	 */
	protected int requirePositiveNumber(Object value, String fieldName, int minValue) {
		if (value == null) {

View on GitHub (pinned to f82da0b50f)