alibaba/spring-ai-alibaba · error

Agent not found

Error message

Agent not found: {}

What it means

MultiAgentJsonRpcRouterProvider's card handler looks up a JsonRpcA2aRequestHandler for the agentName path variable; when no handler is registered, it returns HTTP 404 with body 'Agent not found: <name>'. This is an intentional 404 response, not a thrown exception.

Solutions

1. Verify the agent name matches a registered handler exactly (check router registration/Nacos registration)
2. Confirm the agent's handler bean was created and added to the MultiAgent router at startup
3. List registered agents (via router.getHandler keys or registry UI) and correct the URL
4. Check Nacos service discovery sync status if agents register remotely

Example fix

// before
GET /a2a/agent/ChatBot/card   // 404, registered as "chatbot"
// after
GET /a2a/agent/chatbot/card

boolean registered = router.getHandler(agentName) != null; if (!registered) { /* correct the agent name before calling */ }

try { ResponseEntity<String> r = rest.getForEntity(cardUrl, String.class); } catch (HttpStatusCodeException e) { if (e.getStatusCode() == HttpStatus.NOT_FOUND) { /* agent not registered - fix name/registration */ } }

When it happens

Trigger: Requesting the A2A agent card (or RPC route) with an agentName path segment that was never registered in the MultiAgent router.

Common situations: Agent registered under a different name than the URL; Nacos registry entry for the agent not yet synced; agent module not loaded at startup; client URL typos or case mismatches in the agent name.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Empty HTTP entity
• HTTP request failed, status:
• Thread found but belongs to a different app/user.
• Thread not found: appName=
• A2aRemoteAgent has not support schedule.

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

Appendix: source

Thrown at spring-boot-starters/spring-ai-alibaba-starter-a2a-nacos/src/main/java/com/alibaba/cloud/ai/a2a/core/route/MultiAgentJsonRpcRouterProvider.java:94

			.GET(this.wellKnownUrl, new MultiAgentCardHandler(router))
			.POST(this.messageUrl, new MultiAgentMessageHandler(router))
			.build();
	}

	private static class MultiAgentCardHandler implements HandlerFunction<ServerResponse> {

		private final MultiAgentRequestRouter router;

		public MultiAgentCardHandler(MultiAgentRequestRouter router) {
			this.router = router;
		}

		@Override
		public ServerResponse handle(ServerRequest request) throws Exception {
			String agentName = request.pathVariable("agentName");
			JsonRpcA2aRequestHandler handler = router.getHandler(agentName);
			if (handler == null) {
				log.warn("Agent not found: {}", agentName);
				return ServerResponse.status(HttpStatus.NOT_FOUND)
					.body("Agent not found: " + agentName);
			}
			try {
				return ServerResponse.ok().body(handler.getAgentCard());
			}
			catch (Exception e) {
				log.error("Failed to get Agent Card for {}: {}", agentName, e.getMessage());
				return ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
			}
		}

	}

	private static class MultiAgentMessageHandler implements HandlerFunction<ServerResponse> {

		private final MultiAgentRequestRouter router;

View on GitHub (pinned to f82da0b50f)