Skip to content

Commit 9032f08

Browse files
authored
feat(server): make @PublicAgentCard optional with fallback to @ExtendedAgentCard (a2aproject#1124)
* test(multitenancy): add gRPC tests and extract shared test infrastructure - Add gRPC multitenancy integration tests verifying tenant-based executor routing - Extract shared CDI producers into test-common module, reuse across jsonrpc and gRPC - Config-driven TestAuthorizationController with CDI alternative verification test This fixes a2aproject#1102 Signed-off-by: Emmanuel Hugonnet <ehugonne@redhat.com> * feat(server): make @PublicAgentCard optional with fallback to @ExtendedAgentCard - Remove @DefaultBean AgentCard from DefaultProducers; bean absence is the signal - Return 404 from /.well-known/agent-card.json when no @PublicAgentCard - Fall back to @ExtendedAgentCard for internal capability checks across all transports Fixes a2aproject#1120 Signed-off-by: Emmanuel Hugonnet <ehugonne@redhat.com> --------- Signed-off-by: Emmanuel Hugonnet <ehugonne@redhat.com>
1 parent 0b52bf2 commit 9032f08

29 files changed

Lines changed: 823 additions & 82 deletions

File tree

‎compat-0.3/reference/jsonrpc/src/main/java/org/a2aproject/sdk/compat03/server/apps/quarkus/A2AServerRoutes_v0_3.java‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -100,9 +100,7 @@ void setupRoutes(@Observes Router router) {
100100
}
101101
}, false);
102102

103-
// Only register v0.3 agent card if no real v1.0 agent card producer exists.
104-
// DefaultProducers provides a @DefaultBean AgentCard fallback that is always
105-
// present, so we must exclude it and only check for non-default beans.
103+
// Only register v0.3 agent card if no user-provided v1.0 @PublicAgentCard bean exists.
106104
if (!hasNonDefaultV10AgentCard()) {
107105
router.get("/.well-known/agent-card.json")
108106
.produces(APPLICATION_JSON)

‎compat-0.3/reference/rest/src/main/java/org/a2aproject/sdk/compat03/server/rest/quarkus/A2AServerRoutes_v0_3.java‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -123,9 +123,7 @@ void setupRouter(@Observes @Priority(10) Router router) {
123123
.order(1)
124124
.blockingHandler(authenticated(this::deleteTaskPushNotificationConfiguration), false);
125125

126-
// Only register v0.3 agent card if no real v1.0 agent card producer exists.
127-
// DefaultProducers provides a @DefaultBean AgentCard fallback that is always
128-
// present, so we must exclude it and only check for non-default beans.
126+
// Only register v0.3 agent card if no user-provided v1.0 @PublicAgentCard bean exists.
129127
if (!hasNonDefaultV10AgentCard()) {
130128
router.get("/.well-known/agent-card.json")
131129
.order(1)

‎compat-0.3/tck/src/multi-version/java/org/a2aproject/sdk/compat03/tck/server/DerivedAgentCardProducer.java‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,6 @@
1818
/**
1919
* Produces a v1.0 {@link AgentCard} derived from the v0.3 {@link AgentCard_v0_3}
2020
* when the multi-version profile adds v1.0 reference dependencies to the classpath.
21-
* Overrides the {@code @DefaultBean} in {@code DefaultProducers}.
2221
*/
2322
@ApplicationScoped
2423
public class DerivedAgentCardProducer {

‎docs/content/dev/server.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,13 @@ You can add more than one transport dependency to support multiple protocols sim
5151

5252
## 2. Define an Agent Card
5353

54+
The agent card tells clients what the agent can do. Two qualifiers control how the card is exposed:
55+
56+
- **`@PublicAgentCard`** — served at `/.well-known/agent-card.json` for public discovery. Use this when external clients need to find your agent.
57+
- **`@ExtendedAgentCard`** — used for internal capability checks (transport validation, feature gates) and served via the `GetExtendedAgentCard` JSON-RPC method. Use this when you need to advertise additional capabilities that are not publicly visible.
58+
59+
`@PublicAgentCard` is optional — if omitted, the public endpoint returns HTTP 404 and the server falls back to `@ExtendedAgentCard` for internal capability checks. At least one of the two must be provided, or the server will fail to start with an error.
60+
5461
```java
5562
@ApplicationScoped
5663
public class WeatherAgentCardProducer {

‎pom.xml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -389,6 +389,12 @@
389389
<scope>test</scope>
390390
<version>${project.version}</version>
391391
</dependency>
392+
<dependency>
393+
<groupId>${project.groupId}</groupId>
394+
<artifactId>a2a-java-sdk-tests-multitenancy-test-common</artifactId>
395+
<scope>test</scope>
396+
<version>${project.version}</version>
397+
</dependency>
392398
<dependency>
393399
<groupId>org.jspecify</groupId>
394400
<artifactId>jspecify</artifactId>
@@ -632,9 +638,15 @@
632638
<!-- Multitenancy test module (Weld SE unit tests, no Quarkus) -->
633639
<module>tests/multitenancy</module>
634640

641+
<!-- Multitenancy common test infrastructure (shared CDI producers) -->
642+
<module>tests/multitenancy/test-common</module>
643+
635644
<!-- Multitenancy JSON-RPC integration tests (no REST transport on classpath) -->
636645
<module>tests/multitenancy/jsonrpc</module>
637646

647+
<!-- Multitenancy gRPC integration tests (executor routing via gRPC) -->
648+
<module>tests/multitenancy/grpc</module>
649+
638650
<!-- Multi-version test modules -->
639651
<module>tests/multiversion/jsonrpc</module>
640652
<module>tests/multiversion/rest</module>

‎reference/common/src/main/java/org/a2aproject/sdk/server/common/quarkus/DefaultProducers.java‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,7 @@
33
import jakarta.enterprise.context.ApplicationScoped;
44
import jakarta.enterprise.inject.Produces;
55

6-
import org.a2aproject.sdk.server.PublicAgentCard;
76
import org.a2aproject.sdk.server.agentexecution.AgentExecutor;
8-
import org.a2aproject.sdk.spec.AgentCard;
97
import io.quarkus.arc.DefaultBean;
108

119
/**
@@ -18,12 +16,6 @@
1816
*/
1917
@ApplicationScoped
2018
public class DefaultProducers {
21-
@Produces
22-
@PublicAgentCard
23-
@DefaultBean
24-
public AgentCard createDefaultAgentCard() {
25-
throw new IllegalStateException(wrap("Please provide your own AgentCard implementation"));
26-
}
2719

2820
@Produces
2921
@DefaultBean

‎reference/grpc/src/main/java/org/a2aproject/sdk/server/grpc/quarkus/QuarkusGrpcHandler.java‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -133,7 +133,10 @@ protected RequestHandler getRequestHandler() {
133133
}
134134

135135
@Override
136-
protected AgentCard getAgentCard() {
136+
protected @Nullable AgentCard getAgentCard() {
137+
if (!agentCard.isResolvable()) {
138+
return null;
139+
}
137140
return agentCard.get();
138141
}
139142

‎reference/jsonrpc/src/main/java/org/a2aproject/sdk/server/apps/quarkus/A2AServerRoutes.java‎

Lines changed: 26 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,7 @@
7474
import org.a2aproject.sdk.server.util.sse.SseFormatter;
7575
import org.a2aproject.sdk.server.multitenancy.TenantNotFoundException;
7676
import org.a2aproject.sdk.spec.A2AError;
77+
import org.a2aproject.sdk.spec.AgentCard;
7778
import org.a2aproject.sdk.spec.InternalError;
7879
import org.a2aproject.sdk.spec.JSONParseError;
7980
import org.a2aproject.sdk.spec.TransportProtocol;
@@ -231,6 +232,10 @@ void setupRoutes(@Observes Router router) {
231232
.handler(ctx -> {
232233
try {
233234
String agentCard = getAgentCard(ctx);
235+
if (agentCard == null) {
236+
sendAgentCardNotConfigured(ctx);
237+
return;
238+
}
234239
ctx.response()
235240
.setStatusCode(200)
236241
.putHeader(CONTENT_TYPE, APPLICATION_JSON)
@@ -246,6 +251,10 @@ void setupRoutes(@Observes Router router) {
246251
.handler(ctx -> {
247252
try {
248253
String agentCard = getTenantAgentCard(ctx);
254+
if (agentCard == null) {
255+
sendAgentCardNotConfigured(ctx);
256+
return;
257+
}
249258
ctx.response()
250259
.setStatusCode(200)
251260
.putHeader(CONTENT_TYPE, APPLICATION_JSON)
@@ -432,10 +441,14 @@ public void invokeJSONRPCHandler(String body, RoutingContext rc) {
432441
* @throws JsonProcessingException if serialization fails
433442
* @see JSONRPCHandler#getAgentCard()
434443
*/
435-
public String getAgentCard(RoutingContext rc) throws JsonProcessingException {
444+
public @Nullable String getAgentCard(RoutingContext rc) throws JsonProcessingException {
445+
AgentCard card = jsonRpcHandler.getAgentCard();
446+
if (card == null) {
447+
return null;
448+
}
436449
// Add caching headers per A2A specification section 8.6
437450
cacheMetadata.getHttpHeadersMap().forEach((k, v) -> rc.response().putHeader(k, v));
438-
return JsonUtil.toJson(jsonRpcHandler.getAgentCard());
451+
return JsonUtil.toJson(card);
439452
}
440453

441454
/**
@@ -446,14 +459,23 @@ public String getAgentCard(RoutingContext rc) throws JsonProcessingException {
446459
* @throws IllegalArgumentException if the tenant contains invalid characters
447460
* @throws JsonProcessingException if serialization fails
448461
*/
449-
public String getTenantAgentCard(RoutingContext rc) throws JsonProcessingException {
462+
public @Nullable String getTenantAgentCard(RoutingContext rc) throws JsonProcessingException {
450463
String tenant = rc.pathParam("tenant");
451464
if (tenant == null) {
452465
throw new IllegalArgumentException("Missing tenant path parameter");
453466
}
454467
Utils.validateTenant(tenant);
468+
AgentCard card = jsonRpcHandler.getAgentCard(tenant);
469+
if (card == null) {
470+
return null;
471+
}
455472
cacheMetadata.getHttpHeadersMap().forEach((k, v) -> rc.response().putHeader(k, v));
456-
return JsonUtil.toJson(jsonRpcHandler.getAgentCard(tenant));
473+
return JsonUtil.toJson(card);
474+
}
475+
476+
private static void sendAgentCardNotConfigured(RoutingContext ctx) {
477+
ctx.response().setStatusCode(404).putHeader(CONTENT_TYPE, "text/plain")
478+
.end("Public agent card not configured");
457479
}
458480

459481
/**

‎reference/jsonrpc/src/test/java/org/a2aproject/sdk/server/apps/quarkus/A2AServerRoutesTest.java‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;
1818
import static org.junit.jupiter.api.Assertions.assertEquals;
1919
import static org.junit.jupiter.api.Assertions.assertNotNull;
20+
import static org.junit.jupiter.api.Assertions.assertNull;
2021
import static org.mockito.ArgumentMatchers.any;
2122
import static org.mockito.ArgumentMatchers.anyString;
2223
import static org.mockito.Mockito.mock;
@@ -49,6 +50,7 @@
4950
import org.a2aproject.sdk.jsonrpc.common.wrappers.CreateTaskPushNotificationConfigRequest;
5051
import org.a2aproject.sdk.jsonrpc.common.wrappers.CreateTaskPushNotificationConfigResponse;
5152
import org.a2aproject.sdk.jsonrpc.common.wrappers.SubscribeToTaskRequest;
53+
import org.a2aproject.sdk.server.AgentCardCacheMetadata;
5254
import org.a2aproject.sdk.server.ServerCallContext;
5355
import org.a2aproject.sdk.spec.AgentCapabilities;
5456
import org.a2aproject.sdk.spec.AgentCard;
@@ -101,6 +103,7 @@ public void setUp() {
101103
setField(routes, "jsonRpcHandler", mockJsonRpcHandler);
102104
setField(routes, "executor", mockExecutor);
103105
setField(routes, "callContextFactory", mockCallContextFactory);
106+
setField(routes, "cacheMetadata", mock(AgentCardCacheMetadata.class));
104107

105108
// Setup common mock behavior
106109
when(mockCallContextFactory.isUnsatisfied()).thenReturn(true);
@@ -725,6 +728,23 @@ public void testMethodNotFound_ContentTypeIsApplicationJson() {
725728
verify(mockHttpResponse).putHeader(CONTENT_TYPE, APPLICATION_JSON);
726729
}
727730

731+
@Test
732+
public void testGetAgentCardReturnsNullWhenNoPublicCard() throws Exception {
733+
when(mockJsonRpcHandler.getAgentCard()).thenReturn(null);
734+
String result = routes.getAgentCard(mockRoutingContext);
735+
assertNull(result);
736+
verify(mockHttpResponse, never()).putHeader(any(CharSequence.class), any(CharSequence.class));
737+
}
738+
739+
@Test
740+
public void testGetTenantAgentCardReturnsNullWhenNoPublicCard() throws Exception {
741+
when(mockRoutingContext.pathParam("tenant")).thenReturn("acme");
742+
when(mockJsonRpcHandler.getAgentCard("acme")).thenReturn(null);
743+
String result = routes.getTenantAgentCard(mockRoutingContext);
744+
assertNull(result);
745+
verify(mockHttpResponse, never()).putHeader(any(CharSequence.class), any(CharSequence.class));
746+
}
747+
728748
/**
729749
* Helper method to set a field via reflection for testing purposes.
730750
*/

‎server-common/src/main/java/org/a2aproject/sdk/server/AgentCardValidator.java‎

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,16 +14,20 @@
1414
import jakarta.enterprise.inject.Instance;
1515

1616
import org.a2aproject.sdk.spec.AgentCard;
17+
import org.jspecify.annotations.Nullable;
1718
import org.a2aproject.sdk.spec.AgentInterface;
1819
import org.a2aproject.sdk.spec.TransportProtocol;
1920

2021
/**
2122
* Validates AgentCard transport configuration against available transport endpoints.
2223
*/
2324
public class AgentCardValidator {
24-
25+
2526
private static final Logger LOGGER = Logger.getLogger(AgentCardValidator.class.getName());
2627

28+
static final String NO_AGENT_CARD_MESSAGE =
29+
"No agent card configured. Provide either a @PublicAgentCard or @ExtendedAgentCard bean.";
30+
2731
// Properties to turn off validation globally, or per known transport
2832
public static final String SKIP_PROPERTY = "org.a2aproject.sdk.transport.skipValidation";
2933
public static final String SKIP_JSONRPC_PROPERTY = "org.a2aproject.sdk.transport.jsonrpc.skipValidation";
@@ -71,6 +75,47 @@ public static AgentCard resolveAndValidateOnce(Supplier<AgentCard> agentCardSupp
7175
return card;
7276
}
7377

78+
/**
79+
* Resolves an agent card from the public instance, falling back to the extended instance
80+
* if the public one is absent. Throws if neither is available.
81+
*
82+
* @param publicCard the CDI instance for the {@code @PublicAgentCard}
83+
* @param extendedCard the CDI instance for the {@code @ExtendedAgentCard}, may be {@code null}
84+
* @param transportValidated atomic guard ensuring validation runs once
85+
* @return the resolved agent card
86+
* @throws IllegalStateException if neither card is available
87+
*/
88+
public static AgentCard resolveWithFallback(Instance<AgentCard> publicCard,
89+
@Nullable Instance<AgentCard> extendedCard,
90+
AtomicBoolean transportValidated) {
91+
if (publicCard.isResolvable()) {
92+
return resolveAndValidateOnce(publicCard, transportValidated);
93+
}
94+
if (extendedCard != null && extendedCard.isResolvable()) {
95+
return resolveAndValidateOnce(extendedCard, transportValidated);
96+
}
97+
throw new IllegalStateException(NO_AGENT_CARD_MESSAGE);
98+
}
99+
100+
/**
101+
* Returns the first non-null agent card, preferring the public card.
102+
* Throws if both are {@code null}.
103+
*
104+
* @param publicCard the public agent card, may be {@code null}
105+
* @param extendedCard the extended agent card, may be {@code null}
106+
* @return the first non-null card
107+
* @throws IllegalStateException if both cards are {@code null}
108+
*/
109+
public static AgentCard requireFirst(@Nullable AgentCard publicCard, @Nullable AgentCard extendedCard) {
110+
if (publicCard != null) {
111+
return publicCard;
112+
}
113+
if (extendedCard != null) {
114+
return extendedCard;
115+
}
116+
throw new IllegalStateException(NO_AGENT_CARD_MESSAGE);
117+
}
118+
74119
/**
75120
* Validates the transport configuration of an AgentCard against available transports found on the classpath.
76121
* Logs warnings for missing transports and errors for unsupported transports.

0 commit comments

Comments
 (0)