alibaba/spring-ai-alibaba · error · IllegalArgumentException

AgentCard or AgentCardProvider must be provided

Error message

AgentCard or AgentCardProvider must be provided

What it means

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.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/a2a/A2aRemoteAgent.java:224

			return this;
		}

		public Builder shareState(boolean shareState) {
			this.shareState = shareState;
			return this;
		}

		public A2aRemoteAgent build() {
			// Validation
			if (name == null || name.trim().isEmpty()) {
				throw new IllegalArgumentException("Name must be provided");
			}
			if (description == null || description.trim().isEmpty()) {
				throw new IllegalArgumentException("Description must be provided");
			}
			if (agentCard == null) {
				if (null == agentCardProvider) {
					throw new IllegalArgumentException("AgentCard or AgentCardProvider must be provided");
				}
				if (agentCardProvider.supportGetAgentCardByName()) {
					agentCard = agentCardProvider.getAgentCard(name);
				}
				else {
					agentCard = agentCardProvider.getAgentCard();
				}
			}

			this.streaming = agentCard.capabilities().streaming();

			return new A2aRemoteAgent(this);
		}

	}
}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Provide an AgentCard explicitly: .agentCard(existingCard).
2. Provide a provider, e.g. .agentCardProvider(new RemoteAgentCardProvider(baseUrl)) or a Nacos-backed implementation.
3. If using a by-name provider, ensure supportGetAgentCardByName() is true so the card is resolved in build().
4. Verify the provider bean is injected (not left null) in Spring configs.

Example fix

// before
A2aRemoteAgent.builder().name("a").description("b").build();

// after
A2aRemoteAgent.builder()
    .name("a").description("b")
    .agentCardProvider(new RemoteAgentCardProvider("http://localhost:8080"))
    .build();

if (agentCard == null && agentCardProvider == null) {
    throw new IllegalArgumentException("Provide agentCard or agentCardProvider");
}

try {
    A2aRemoteAgent a = builder.build();
} catch (IllegalArgumentException e) {
    log.error("Agent card configuration missing: {}", e.getMessage());
}

When it happens

Trigger: A2aRemoteAgent.builder().name("a").description("b").build() with neither .agentCard() nor .agentCardProvider() set; agentCardProvider is null when agentCard is null.

Common situations: 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.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Name must be provided
• Description must be provided
• AgentCard.url is empty
• Name must be provided
• ParallelAgent requires at least 2 sub-agents for parallel ex

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