{"record":{"id":"0bcdeb3df3cc74ee","repo":"alibaba/spring-ai-alibaba","slug":"agentcard-or-agentcardprovider-must-be-provided","errorCode":null,"errorMessage":"AgentCard or AgentCardProvider must be provided","messagePattern":"AgentCard or AgentCardProvider must be provided","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/a2a/A2aRemoteAgent.java","lineNumber":224,"sourceCode":"\t\t\treturn this;\n\t\t}\n\n\t\tpublic Builder shareState(boolean shareState) {\n\t\t\tthis.shareState = shareState;\n\t\t\treturn this;\n\t\t}\n\n\t\tpublic A2aRemoteAgent build() {\n\t\t\t// Validation\n\t\t\tif (name == null || name.trim().isEmpty()) {\n\t\t\t\tthrow new IllegalArgumentException(\"Name must be provided\");\n\t\t\t}\n\t\t\tif (description == null || description.trim().isEmpty()) {\n\t\t\t\tthrow new IllegalArgumentException(\"Description must be provided\");\n\t\t\t}\n\t\t\tif (agentCard == null) {\n\t\t\t\tif (null == agentCardProvider) {\n\t\t\t\t\tthrow new IllegalArgumentException(\"AgentCard or AgentCardProvider must be provided\");\n\t\t\t\t}\n\t\t\t\tif (agentCardProvider.supportGetAgentCardByName()) {\n\t\t\t\t\tagentCard = agentCardProvider.getAgentCard(name);\n\t\t\t\t}\n\t\t\t\telse {\n\t\t\t\t\tagentCard = agentCardProvider.getAgentCard();\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tthis.streaming = agentCard.capabilities().streaming();\n\n\t\t\treturn new A2aRemoteAgent(this);\n\t\t}\n\n\t}\n}\n","sourceCodeStart":206,"sourceCodeEnd":241,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/a2a/A2aRemoteAgent.java#L206-L241","documentation":"To construct an A2aRemoteAgent the builder needs the target agent's A2A AgentCard, either given directly via .agentCard(...) or obtained lazily via .agentCardProvider(...). If both are absent, build() throws IllegalArgumentException because the agent cannot know which remote agent to invoke.","triggerScenarios":"A2aRemoteAgent.builder().name(\"a\").description(\"b\").build() with neither .agentCard() nor .agentCardProvider() set; agentCardProvider is null when agentCard is null.","commonSituations":"Forgetting to wire the Nacos-backed AgentCardProvider in environments relying on registry discovery; hand-rolled builders that skip card configuration; refactors that removed the card line accidentally.","solutions":["Provide an AgentCard explicitly: .agentCard(existingCard).","Provide a provider, e.g. .agentCardProvider(new RemoteAgentCardProvider(baseUrl)) or a Nacos-backed implementation.","If using a by-name provider, ensure supportGetAgentCardByName() is true so the card is resolved in build().","Verify the provider bean is injected (not left null) in Spring configs."],"exampleFix":"// before\nA2aRemoteAgent.builder().name(\"a\").description(\"b\").build();\n\n// after\nA2aRemoteAgent.builder()\n    .name(\"a\").description(\"b\")\n    .agentCardProvider(new RemoteAgentCardProvider(\"http://localhost:8080\"))\n    .build();","handlingStrategy":"validation","validationCode":"if (agentCard == null && agentCardProvider == null) {\n    throw new IllegalArgumentException(\"Provide agentCard or agentCardProvider\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    A2aRemoteAgent a = builder.build();\n} catch (IllegalArgumentException e) {\n    log.error(\"Agent card configuration missing: {}\", e.getMessage());\n}","preventionTips":["Wire the AgentCardProvider bean (e.g. Nacos-backed) before building agents.","Prefer explicit .agentCard(...) in tests to avoid provider wiring issues.","Verify card resolution happens in build() when relying on by-name providers."],"tags":["builder","a2a","agent-card","validation"],"backgroundTag":"missing-required-argument","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}