{"record":{"id":"e5e5c6367aef4c46","repo":"alibaba/spring-ai-alibaba","slug":"reactagent-requires-model-configuration-in-handle","errorCode":null,"errorMessage":"ReactAgent requires model configuration in handle","messagePattern":"ReactAgent requires model configuration in handle","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/generator/agent/impl/ReactAgentProvider.java","lineNumber":165,"sourceCode":"\t\t\t\t\"import com.alibaba.cloud.ai.graph.state.strategy.ReplaceStrategy;\",\n\t\t\t\t\"import org.springframework.ai.chat.model.ChatModel;\",\n\t\t\t\t\"import org.springframework.context.annotation.Bean;\",\n\t\t\t\t\"import org.springframework.stereotype.Component;\",\n\t\t\t\thasResolver ? \"import org.springframework.beans.factory.ObjectProvider;\" : null,\n\t\t\t\thasResolver ? \"import org.springframework.ai.tool.resolution.ToolCallbackResolver;\" : null,\n\t\t\t\t\"import java.util.*;\")\n\t\t\t.code(code.toString())\n\t\t\t.var(var)\n\t\t\t.resolver(hasResolver);\n\t}\n\n\t@Override\n\tprotected void validateSpecific(Map<String, Object> root) {\n\t\t// ReactAgent 必须有 model 配置\n\t\tMap<String, Object> handle = requireHandle(root);\n\n\t\tif (handle.get(\"model\") == null) {\n\t\t\tthrow new IllegalArgumentException(\"ReactAgent requires model configuration in handle\");\n\t\t}\n\n\t\t// 如果有 tools，检查相关配置\n\t\tif (handle.get(\"tools\") instanceof List<?> tools && !tools.isEmpty()) {\n\t\t\t// 检查 tools 是否为空字符串\n\t\t\tfor (Object tool : tools) {\n\t\t\t\tif (tool instanceof String s && s.trim().isEmpty()) {\n\t\t\t\t\tthrow new IllegalArgumentException(\"ReactAgent tool names cannot be empty\");\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// 检查 max_iterations 如果存在，必须是正数\n\t\tObject maxIterations = handle.get(\"max_iterations\");\n\t\tif (maxIterations != null) {\n\t\t\trequirePositiveNumber(maxIterations, \"max_iterations\", 1);\n\t\t}\n\t}","sourceCodeStart":147,"sourceCodeEnd":183,"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/generator/agent/impl/ReactAgentProvider.java#L147-L183","documentation":"ReactAgentProvider.validateSpecific() throws this when a react_agent's \"handle\" section has no \"model\" entry. A ReactAgent needs an LLM to run its reasoning loop, so the model configuration is mandatory. The DSL passes structural validation but is semantically incomplete for generation.","triggerScenarios":"validateDSL calls validateSpecific(root); requireHandle(root) succeeds but handle.get(\"model\") == null — the handle section omits the model key entirely.","commonSituations":"Copying a tool-only or workflow sub-agent config into a react_agent; a UI export that strips the model when no default model is selected; deleting a model reference that pointed to an unavailable model.","solutions":["Add a \"model\" entry inside the \"handle\" object of the react_agent config","Ensure the selected model is available in the target environment (e.g. a DashScope model name)","If the agent is meant to be model-less, use a non-React agent type (e.g. a plain workflow node)"],"exampleFix":"// before\n{\"type\": \"react_agent\", \"name\": \"assistant\", \"handle\": {\"tools\": [\"search\"]}}\n// after\n{\"type\": \"react_agent\", \"name\": \"assistant\", \"handle\": {\"model\": \"qwen-max\", \"tools\": [\"search\"]}}","handlingStrategy":"validation","validationCode":"Map<String,Object> handle = (Map<String,Object>) config.get(\"handle\");\nif (handle == null || handle.get(\"model\") == null) {\n    throw new IllegalArgumentException(\"react_agent handle requires a 'model' entry\");\n}","typeGuard":"static boolean hasModel(Map<String,Object> cfg) {\n    return cfg.get(\"handle\") instanceof Map<?,?> h && h.get(\"model\") != null;\n}","tryCatchPattern":"try {\n    provider.validateDSL(root);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"requires model configuration\")) {\n        // prompt user to pick a model for the react_agent\n    }\n}","preventionTips":["Always set handle.model for react_agent definitions","Validate model availability in the target environment (API keys, model names)","Configure a default model in your UI/exporter so the field is never dropped","Use a model-less agent type for pure tool/workflow nodes"],"tags":["validation","dsl","react-agent"],"backgroundTag":"missing-required-config-field","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}