{"record":{"id":"366d717de7614ba0","repo":"alibaba/nacos","slug":"501-366d71","errorCode":"501","errorMessage":"Agent publication is not implemented by this AiService.","messagePattern":"Agent publication is not implemented by this AiService\\.","errorType":"exception","errorClass":"NacosException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/com/alibaba/nacos/api/ai/AiService.java","lineNumber":55,"sourceCode":" *\n * @author xiweng.yy\n */\npublic interface AiService extends AgentDiscoveryService, A2aService {\n    \n    /**\n     * Publish one exact Agent Version from application code.\n     *\n     * <p>The AiService namespace is used automatically. By default this creates a draft;\n     * {@link AgentPublishRequest#isAutoSubmit()} requests the ordinary submit pipeline and never\n     * force-publishes a Version.</p>\n     *\n     * @param request Agent definition publication request\n     * @return resulting exact Version detail\n     * @throws NacosException when validation, publication, or submit fails\n     */\n    @Since(\"3.3.0\")\n    default AgentVersionDetail publishAgent(AgentPublishRequest request) throws NacosException {\n        throw new NacosException(NacosException.SERVER_NOT_IMPLEMENTED,\n            \"Agent publication is not implemented by this AiService.\");\n    }\n    \n    /**\n     * Get mcp server detail info for the latest published version.\n     *\n     * @param mcpName name of mcp server\n     * @return detail information of MCP server\n     * @throws NacosException if request parameter is invalid or mcp server not found or handle error\n     */\n    @Since(\"3.0.3\")\n    default McpServerDetailInfo getMcpServer(String mcpName) throws NacosException {\n        return getMcpServer(mcpName, null);\n    }\n    \n    /**\n     * Get mcp server detail info.\n     *","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/api/src/main/java/com/alibaba/nacos/api/ai/AiService.java#L37-L73","documentation":"The publishAgent default method on AiService (Nacos 3.3.0) throws NacosException with code SERVER_NOT_IMPLEMENTED (501) when the concrete AiService implementation does not override it. This means the SDK/server combination does not support publishing Agent Versions from application code through this interface.","triggerScenarios":"Invoking aiService.publishAgent(request) where the AiService instance inherits the default stub. Common when the Nacos client SDK version supports the method signature but the connected server does not implement the publication pipeline.","commonSituations":"Client SDK upgraded to 3.3.0 but server is older. Using a mock AiService in unit tests without stubbing publishAgent. The server-side AI agent publication module is disabled or not deployed.","solutions":["Ensure the Nacos server is 3.3.0+ with the AI agent publication module enabled.","Override publishAgent in a custom AiService subclass to route to the correct server API.","Use the admin/ console HTTP API for agent publication if the SDK path is not yet wired on the server.","Verify the AiService factory (e.g. NacosFactory.createAiService) returns a full implementation, not a partial one."],"exampleFix":"// before\nAgentVersionDetail detail = aiService.publishAgent(request);\n\n// after -- check capability or use admin API\nif (!agentPublicationSupported(aiService)) {\n    // POST /v3/admin/ai/agent/publish with the same request body\n} else {\n    aiService.publishAgent(request);\n}","handlingStrategy":"try-catch","validationCode":"boolean supported;\ntry {\n    java.lang.reflect.Method m = aiService.getClass().getMethod(\"publishAgent\",\n        com.alibaba.nacos.api.ai.model.agent.AgentPublishRequest.class);\n    supported = !m.getDeclaringClass().equals(com.alibaba.nacos.api.ai.AiService.class);\n} catch (NoSuchMethodException e) {\n    supported = false;\n}","typeGuard":"public static boolean supportsAgentPublication(AiService svc) {\n    try {\n        Method m = svc.getClass().getMethod(\"publishAgent\", AgentPublishRequest.class);\n        return !m.getDeclaringClass().equals(AiService.class);\n    } catch (NoSuchMethodException e) {\n        return false;\n    }\n}","tryCatchPattern":"try {\n    aiService.publishAgent(request);\n} catch (NacosException e) {\n    if (e.getErrCode() == NacosException.SERVER_NOT_IMPLEMENTED) {\n        // fall back to admin HTTP API for agent publication\n    } else throw e;\n}","preventionTips":["Verify server version supports agent publication before calling publishAgent.","Prefer the admin/ console HTTP API when SDK feature parity is uncertain.","Test against the actual server version in your integration environment."],"tags":["ai-service","agent-publication","not-implemented","version-mismatch"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}