alibaba/spring-ai-alibaba · error · IllegalArgumentException

invalid agent dsl: missing 'agent' object or flat agent fiel

Error message

invalid agent dsl: missing 'agent' object or flat agent fields

What it means

Thrown by AgentDSLAdapter.validateDSLData when an imported DSL document contains neither a nested 'agent' object nor flat agent fields at the top level. The adapter uses getAgentRoot(dslData) to locate the agent payload; when it returns null there is no recognizable agent structure to validate or import. This is a structural guard ensuring the DSL matches one of the accepted shapes before any conversion happens.

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/dsl/adapters/AgentDSLAdapter.java:129

					if (childRoot.get("handle") instanceof Map<?, ?> ch) {
						child.setHandle((Map<String, Object>) ch);
					}
					subs.add(child);
				}
			}
			agent.setSubAgents(subs);
		}

		return new App(metadata, agent);
	}

	private void validateDSLData(Map<String, Object> dslData) {
		if (dslData == null) {
			throw new IllegalArgumentException("invalid agent dsl: data is null");
		}
		Map<String, Object> root = getAgentRoot(dslData);
		if (root == null) {
			throw new IllegalArgumentException("invalid agent dsl: missing 'agent' object or flat agent fields");
		}
		String type = firstNonBlank((String) root.get("type"), (String) root.get("agent_class"));
		String name = (String) root.get("name");
		if (isBlank(type) || isBlank(name)) {
			throw new IllegalArgumentException("invalid agent dsl: 'type/agent_class' and 'name' are required");
		}
		// 针对不同 Agent 类型的校验
		validateAgentTypeSpecificConstraints(type, root);
	}

	private void validateAgentTypeSpecificConstraints(String type, Map<String, Object> root) {
		if (type == null || root == null) {
			return;
		}

		// 使用 AgentTypeProvider 进行校验
		AgentTypeProvider provider = providerRegistry.get(type);
		if (provider != null) {

View on GitHub (pinned to f82da0b50f)

Solutions

1. Inspect the imported map and ensure it contains an 'agent' object: {"agent": {"type": ..., "name": ..., ...}}
2. Alternatively use the flat form with type/agent_class and name directly at the top level of the DSL map
3. Re-export the DSL from the platform version that produced it instead of hand-editing
4. Verify you are calling the correct adapter's importDSL (Agent vs Dify vs Studio) for your document format

Example fix

// before
dslImporter.importDSL(Map.of("name", "my-agent"));

// after
dslImporter.importDSL(Map.of("agent", Map.of("type", "SimpleAgent", "name", "my-agent")));

boolean valid = dslData != null && (dslData.get("agent") instanceof Map || dslData.containsKey("type") || dslData.containsKey("agent_class"));
if (!valid) throw new IllegalArgumentException("DSL must contain an 'agent' object or flat agent fields");

boolean hasAgentRoot(Map<String,Object> dsl) { return dsl != null && (dsl.get("agent") instanceof Map || dsl.get("type") instanceof String || dsl.get("agent_class") instanceof String); }

try { adapter.importDSL(dslData); } catch (IllegalArgumentException e) { log.error("DSL structure invalid: {}", e.getMessage()); throw new BadRequestException("Unrecognized agent DSL format"); }

When it happens

Trigger: Calling importDSL with a map that lacks both dslData["agent"] (a Map) and flat top-level agent fields; importing an empty map; importing a DSL exported by a different tool whose root keys do not include 'agent'; JSON that was parsed into a shape where 'agent' is nested under an unexpected key.

Common situations: Hand-editing a DSL JSON file and accidentally deleting or renaming the 'agent' key; importing a Dify/Studio-style DSL into an agent DSL endpoint that expects the native format; pasting partial config snippets instead of a full exported DSL; version drift where a newer export format renamed the root key.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Param Not Support Object
• Param Not Support Array<Object>
• RequestBody Only Support object Type
• ResponseBody Only Support object or array Type
• invalid agent dsl: 'type/agent_class' and 'name' are require

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