alibaba/spring-ai-alibaba · error · IllegalArgumentException

App spec is not Agent

Error message

App spec is not Agent

What it means

Thrown by AgentDSLAdapter.exportDSL when the App's spec is not an Agent instance. This adapter serializes only Agent specs; being handed an App with a Workflow or ChatBot spec is an argument-type violation.

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:56

@Component("agentDSLAdapter")
public class AgentDSLAdapter implements DSLAdapter {

	private final Serializer serializer;

	private final ObjectMapper objectMapper;

	private final AgentTypeProviderRegistry providerRegistry;

	public AgentDSLAdapter(@Qualifier("yaml") Serializer serializer, AgentTypeProviderRegistry providerRegistry) {
		this.serializer = serializer;
		this.objectMapper = new ObjectMapper();
		this.providerRegistry = providerRegistry;
	}

	@Override
	public String exportDSL(App app) {
		if (!(app.getSpec() instanceof Agent agent)) {
			throw new IllegalArgumentException("App spec is not Agent");
		}
		Map<String, Object> body = dumpAgent(agent);
		body.put("name", app.getMetadata().getName());
		body.put("description", app.getMetadata().getDescription());
		body.put("mode", "agent");
		return serializer.dump(body);
	}

	@Override
	public App importDSL(String dsl) {
		Map<String, Object> data = serializer.load(dsl);
		validateDSLData(data);
		Map<String, Object> root = getAgentRoot(data);
		if (root == null)
			root = data;

		// 仅解析壳层字段，handle 原样透传
		AppMetadata metadata = mapToMetadata(data);

View on GitHub (pinned to f82da0b50f)

Solutions

1. Confirm app.getSpec() instanceof Agent before invoking the agent adapter
2. Use AbstractDSLAdapter.exportDSL for workflow/chatbot apps
3. Check that the app's metadata mode ('agent') matches its spec type

Example fix

// before
agentDslAdapter.exportDSL(new App(metadata, new Workflow(...)));
// after
if (app.getSpec() instanceof Agent) {
    agentDslAdapter.exportDSL(app);
}

if (!(app.getSpec() instanceof Agent)) { throw new IllegalArgumentException("use the matching adapter for " + app.getMetadata().getMode()); }

boolean isAgentApp(App app) { return app != null && app.getSpec() instanceof Agent; }

try { agentDslAdapter.exportDSL(app); } catch (IllegalArgumentException e) { /* fall back to AbstractDSLAdapter.exportDSL */ }

When it happens

Trigger: Calling AgentDSLAdapter.exportDSL with an App whose spec is a Workflow/ChatBot object, or an App built with a null spec.

Common situations: Routing all apps through the agent adapter in shared export code, apps created with mismatched metadata mode and spec, tests constructing App with arbitrary specs.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• unknown component type: + componentType.getValue()
• extra tool param should be map
• INVALID_PARAMS
• WORKFLOW_CONFIG_INVALID
• Unknown agent status code:

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