[Bug]: A2aAgent throws an SDK NullPointerException when AgentCardResolver cannot find the agent #3596

问题描述

A2aAgent 每次调用前，会用自己的 name 去 AgentCardResolver 取 AgentCard，然后把结果直接交给 SDK 的 Client.builder(...)。resolver 找不到这个名字时会返回 null，例如 NacosAgentCardResolver 在 Nacos 里查不到该 agent，或者 A2aAgent 的 name 和服务端注册名写得不一致（NacosAgentCardResolverTest#testGetAgentCardHandlesNullResult 也认为返回 null 是可以接受的）。A2aAgent 没有检查这个 null，最后在 SDK 内部抛出空指针。报错里既没有 agent 名，也看不出是「没找到卡片」，很容易被误判成 SDK 或传输层的问题。

build() 阶段不会暴露问题：getDescriptionFromAgentCard() 对 null 做了兜底，agent 能正常构建，直到第一次 call() 才失败。

复现步骤

AgentCardResolver resolver = agentName -> null; // 相当于 Nacos 里没有这个 agent
A2aAgent agent = A2aAgent.builder()
        .name("remote-agent")
        .agentCardResolver(resolver)
        .build(); // 正常构建
agent.call(Msg.builder().textContent("hi").build()).block(); // 抛出 NPE

用 Nacos 时：服务端以名称 A 注册，客户端写成 A2aAgent.builder().name("B").agentCardResolver(new NacosAgentCardResolver(aiService))，一调用就是同样的报错。

期望行为

resolver 返回 null 时，A2aAgent 直接抛出明确的异常，写清楚找不到哪个 agent、用的是哪个 resolver，例如：

java.lang.IllegalStateException: No AgentCard found for A2A agent 'remote-agent' via NacosAgentCardResolver. Check that the agent name matches the name registered on the server.

SDK 内部的空指针不再暴露给用户。

报错信息

main（c416c378e，a2a-java-sdk 0.3.3.Final）：

java.lang.NullPointerException: Cannot invoke "io.a2a.spec.AgentCard.preferredTransport()" because "this.agentCard" is null
    at io.a2a.client.ClientBuilder.getServerPreferredTransports(ClientBuilder.java:113)
    at io.a2a.client.ClientBuilder.findBestClientTransport(ClientBuilder.java:136)
    at io.a2a.client.ClientBuilder.buildClientTransport(ClientBuilder.java:92)
    at io.a2a.client.ClientBuilder.build(ClientBuilder.java:84)
    at io.agentscope.core.a2a.agent.A2aAgent.buildA2aClient(A2aAgent.java:196)
    at io.agentscope.core.a2a.agent.A2aAgent$A2aClientLifecycleHook.onEvent(A2aAgent.java:255)

升级到 a2a-java-sdk 1.4.0.Final（#3590）后问题仍在，只是报错变成 Cannot invoke "AgentCard.supportedInterfaces()" because "this.agentCard" is null（位于 ClientBuilder.getServerInterfacesMap）。我在 #3590 上用真实 Nacos 3.2.1 验证时遇到的就是这个。

环境

• AgentScope-Java Version: 2.1.0-SNAPSHOT（main c416c37）
• Java Version: 21
• OS: macOS

补充说明

建议的改法：在 A2aAgent 里只解析一次卡片，拿到 null 就抛出上面那种明确的异常；A2aClientLifecycleHook 的 debug 日志复用这张卡，不再重新调用 resolver（WellKnownAgentCardResolver 不做缓存，现在每次调用都会多拉一次卡片）。另外在 AgentCardResolver#getAgentCard 的 Javadoc 里写明「找不到时返回 null」。