{"record":{"id":"ce282ea0b3753d48","repo":"alibaba/nacos","slug":"501","errorCode":"501","errorMessage":"Agent discovery is not implemented by this AiService.","messagePattern":"Agent discovery is not implemented by this AiService\\.","errorType":"exception","errorClass":"NacosException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/com/alibaba/nacos/api/ai/AgentDiscoveryService.java","lineNumber":52,"sourceCode":" * <p>Default implementations preserve binary compatibility for third-party\n * {@link AiService} implementations compiled before this interface was introduced. Official\n * Nacos clients override the complete surface.</p>\n *\n * @author Nacos\n */\npublic interface AgentDiscoveryService {\n    \n    /**\n     * Search visible Agent catalog entries.\n     *\n     * @param request search request\n     * @return Agent catalog page\n     * @throws NacosException when validation or the remote request fails\n     */\n    @Since(\"3.3.0\")\n    default Page<AgentCatalogEntry> searchAgents(AgentSearchRequest request)\n        throws NacosException {\n        throw new NacosException(NacosException.SERVER_NOT_IMPLEMENTED,\n            \"Agent discovery is not implemented by this AiService.\");\n    }\n    \n    /**\n     * Discover the latest, exact-version, or labeled Agent referenced by {@code reference}.\n     *\n     * @param reference Agent reference\n     * @return complete discovery snapshot\n     * @throws NacosException when validation or the remote request fails\n     */\n    @Since(\"3.3.0\")\n    default AgentDiscoveryResult discoverAgent(AgentReference reference) throws NacosException {\n        return discoverAgent(reference, null);\n    }\n    \n    /**\n     * Discover one Agent and filter its call interfaces and Endpoint sets.\n     *","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/api/src/main/java/com/alibaba/nacos/api/ai/AgentDiscoveryService.java#L34-L70","documentation":"Thrown by the default AgentDiscoveryService.searchAgents() implementation (HTTP 501 SERVER_NOT_IMPLEMENTED). This default exists for binary compatibility with third-party AiService implementations compiled before the Agent discovery surface (added in 3.3.0). The official Nacos client overrides it; a custom or stub AiService that does not override it will hit this default and reject the call.","triggerScenarios":"Calling aiService.searchAgents(request) on an AiService instance whose concrete class does not override searchAgents — e.g., a third-party/stub AiService implementation, a mock in tests, or an older client version predating 3.3.0 that only implements the legacy MCP/prompt methods.","commonSituations":"Using a custom AiService SPI implementation that was written against an older API and never added the Agent discovery methods; a test mock that implements the interface but leaves defaults; a client SDK version older than 3.3.0; downgrading from a newer client to an older one.","solutions":["Use the official Nacos client (NacosAiService) which overrides all Agent discovery methods.","Upgrade your client SDK to >= 3.3.0 where the Agent discovery surface is fully implemented.","If you maintain a custom AiService, override searchAgents to delegate to the real discovery backend.","Guard capability by checking the SDK version or feature flag before calling Agent methods."],"exampleFix":"// before (custom/stub AiService)\nAiService service = MyCustomAiServiceFactory.create();\nservice.searchAgents(req); // -> 501\n\n// after (official client)\nNacosAiService service = NacosAiServiceFactory.create(props);\nservice.searchAgents(req); // implemented","handlingStrategy":"try-catch","validationCode":"public boolean supportsAgentDiscovery(AiService service) {\n    try {\n        // probe a no-op-capable method or check version metadata\n        return service.getClass().getMethod(\"searchAgents\", AgentSearchRequest.class)\n            .getDeclaringClass() != AgentDiscoveryService.class;\n    } catch (NoSuchMethodException e) {\n        return false;\n    }\n}","typeGuard":"boolean isOfficialAiService(AiService service) {\n    return service instanceof NacosAiService;\n}","tryCatchPattern":"try {\n    Page<AgentCatalogEntry> page = aiService.searchAgents(req);\n} catch (NacosException e) {\n    if (e.getErrCode() == NacosException.SERVER_NOT_IMPLEMENTED) {\n        // fall back: use legacy discovery or upgrade the client\n        log.warn(\"Agent discovery unsupported by this AiService; upgrade to >= 3.3.0\");\n    } else {\n        throw e;\n    }\n}","preventionTips":["Use the official NacosAiService client (>= 3.3.0) for the full Agent discovery surface.","Before calling Agent methods on an injected AiService, check it is not the default stub.","In custom SPI implementations, override all Agent discovery methods rather than relying on defaults."],"tags":["agent-discovery","ai-service","not-implemented","version","sdk"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}