{"record":{"id":"a6268553b2d157df","repo":"alibaba/spring-ai-alibaba","slug":"invalid-agent-dsl-missing-agent-object-or-flat","errorCode":null,"errorMessage":"invalid agent dsl: missing 'agent' object or flat agent fields","messagePattern":"invalid agent dsl: missing 'agent' object or flat agent fields","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"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","lineNumber":129,"sourceCode":"\t\t\t\t\tif (childRoot.get(\"handle\") instanceof Map<?, ?> ch) {\n\t\t\t\t\t\tchild.setHandle((Map<String, Object>) ch);\n\t\t\t\t\t}\n\t\t\t\t\tsubs.add(child);\n\t\t\t\t}\n\t\t\t}\n\t\t\tagent.setSubAgents(subs);\n\t\t}\n\n\t\treturn new App(metadata, agent);\n\t}\n\n\tprivate void validateDSLData(Map<String, Object> dslData) {\n\t\tif (dslData == null) {\n\t\t\tthrow new IllegalArgumentException(\"invalid agent dsl: data is null\");\n\t\t}\n\t\tMap<String, Object> root = getAgentRoot(dslData);\n\t\tif (root == null) {\n\t\t\tthrow new IllegalArgumentException(\"invalid agent dsl: missing 'agent' object or flat agent fields\");\n\t\t}\n\t\tString type = firstNonBlank((String) root.get(\"type\"), (String) root.get(\"agent_class\"));\n\t\tString name = (String) root.get(\"name\");\n\t\tif (isBlank(type) || isBlank(name)) {\n\t\t\tthrow new IllegalArgumentException(\"invalid agent dsl: 'type/agent_class' and 'name' are required\");\n\t\t}\n\t\t// 针对不同 Agent 类型的校验\n\t\tvalidateAgentTypeSpecificConstraints(type, root);\n\t}\n\n\tprivate void validateAgentTypeSpecificConstraints(String type, Map<String, Object> root) {\n\t\tif (type == null || root == null) {\n\t\t\treturn;\n\t\t}\n\n\t\t// 使用 AgentTypeProvider 进行校验\n\t\tAgentTypeProvider provider = providerRegistry.get(type);\n\t\tif (provider != null) {","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/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#L111-L147","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the imported map and ensure it contains an 'agent' object: {\"agent\": {\"type\": ..., \"name\": ..., ...}}","Alternatively use the flat form with type/agent_class and name directly at the top level of the DSL map","Re-export the DSL from the platform version that produced it instead of hand-editing","Verify you are calling the correct adapter's importDSL (Agent vs Dify vs Studio) for your document format"],"exampleFix":"// before\ndslImporter.importDSL(Map.of(\"name\", \"my-agent\"));\n\n// after\ndslImporter.importDSL(Map.of(\"agent\", Map.of(\"type\", \"SimpleAgent\", \"name\", \"my-agent\")));","handlingStrategy":"validation","validationCode":"boolean valid = dslData != null && (dslData.get(\"agent\") instanceof Map || dslData.containsKey(\"type\") || dslData.containsKey(\"agent_class\"));\nif (!valid) throw new IllegalArgumentException(\"DSL must contain an 'agent' object or flat agent fields\");","typeGuard":"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); }","tryCatchPattern":"try { adapter.importDSL(dslData); } catch (IllegalArgumentException e) { log.error(\"DSL structure invalid: {}\", e.getMessage()); throw new BadRequestException(\"Unrecognized agent DSL format\"); }","preventionTips":["Always import DSLs produced by a full export, not hand-built fragments","Keep the 'agent' wrapper object intact when editing DSL files","Route each DSL format to its matching adapter before calling importDSL"],"tags":["dsl","validation","import"],"backgroundTag":"schema-validation-failed","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}