Skip to content

Commit 8043cdd

Browse files
committed
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>
1 parent 52b1d8e commit 8043cdd

13 files changed

Lines changed: 196 additions & 40 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 v1.0 @PublicAgentCard producer 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 v1.0 @PublicAgentCard producer 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: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,8 @@ You can add more than one transport dependency to support multiple protocols sim
5151

5252
## 2. Define an Agent Card
5353

54+
The `@PublicAgentCard` bean defines the publicly discoverable agent card served at `/.well-known/agent-card.json`. This bean is optional — if omitted, the public endpoint returns 404 and the server uses the `@ExtendedAgentCard` (if provided) for internal capability checks. At least one of `@PublicAgentCard` or `@ExtendedAgentCard` must be provided.
55+
5456
```java
5557
@ApplicationScoped
5658
public class WeatherAgentCardProducer {

‎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: 23 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,11 @@ void setupRoutes(@Observes Router router) {
231232
.handler(ctx -> {
232233
try {
233234
String agentCard = getAgentCard(ctx);
235+
if (agentCard == null) {
236+
ctx.response().setStatusCode(404).putHeader(CONTENT_TYPE, "text/plain")
237+
.end("Public agent card not configured");
238+
return;
239+
}
234240
ctx.response()
235241
.setStatusCode(200)
236242
.putHeader(CONTENT_TYPE, APPLICATION_JSON)
@@ -246,6 +252,11 @@ void setupRoutes(@Observes Router router) {
246252
.handler(ctx -> {
247253
try {
248254
String agentCard = getTenantAgentCard(ctx);
255+
if (agentCard == null) {
256+
ctx.response().setStatusCode(404).putHeader(CONTENT_TYPE, "text/plain")
257+
.end("Public agent card not configured");
258+
return;
259+
}
249260
ctx.response()
250261
.setStatusCode(200)
251262
.putHeader(CONTENT_TYPE, APPLICATION_JSON)
@@ -432,10 +443,14 @@ public void invokeJSONRPCHandler(String body, RoutingContext rc) {
432443
* @throws JsonProcessingException if serialization fails
433444
* @see JSONRPCHandler#getAgentCard()
434445
*/
435-
public String getAgentCard(RoutingContext rc) throws JsonProcessingException {
446+
public @Nullable String getAgentCard(RoutingContext rc) throws JsonProcessingException {
447+
AgentCard card = jsonRpcHandler.getAgentCard();
448+
if (card == null) {
449+
return null;
450+
}
436451
// Add caching headers per A2A specification section 8.6
437452
cacheMetadata.getHttpHeadersMap().forEach((k, v) -> rc.response().putHeader(k, v));
438-
return JsonUtil.toJson(jsonRpcHandler.getAgentCard());
453+
return JsonUtil.toJson(card);
439454
}
440455

441456
/**
@@ -446,14 +461,18 @@ public String getAgentCard(RoutingContext rc) throws JsonProcessingException {
446461
* @throws IllegalArgumentException if the tenant contains invalid characters
447462
* @throws JsonProcessingException if serialization fails
448463
*/
449-
public String getTenantAgentCard(RoutingContext rc) throws JsonProcessingException {
464+
public @Nullable String getTenantAgentCard(RoutingContext rc) throws JsonProcessingException {
450465
String tenant = rc.pathParam("tenant");
451466
if (tenant == null) {
452467
throw new IllegalArgumentException("Missing tenant path parameter");
453468
}
454469
Utils.validateTenant(tenant);
470+
AgentCard card = jsonRpcHandler.getAgentCard(tenant);
471+
if (card == null) {
472+
return null;
473+
}
455474
cacheMetadata.getHttpHeadersMap().forEach((k, v) -> rc.response().putHeader(k, v));
456-
return JsonUtil.toJson(jsonRpcHandler.getAgentCard(tenant));
475+
return JsonUtil.toJson(card);
457476
}
458477

459478
/**

‎transport/grpc/src/main/java/org/a2aproject/sdk/transport/grpc/handler/GrpcHandler.java‎

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -848,8 +848,18 @@ private <V> void handleInternalError(StreamObserver<V> responseObserver, Throwab
848848

849849

850850
private AgentCard resolveAgentCard() {
851-
return AgentCardValidator.resolveAndValidateOnce(
852-
this::getAgentCard, transportValidated, this::validateTransportConfigurationWithCorrectClassLoader);
851+
return AgentCardValidator.resolveAndValidateOnce(() -> {
852+
AgentCard card = getAgentCard();
853+
if (card != null) {
854+
return card;
855+
}
856+
AgentCard extended = getExtendedAgentCard();
857+
if (extended != null) {
858+
return extended;
859+
}
860+
throw new IllegalStateException(
861+
"No agent card configured. Provide either a @PublicAgentCard or @ExtendedAgentCard bean.");
862+
}, transportValidated, this::validateTransportConfigurationWithCorrectClassLoader);
853863
}
854864

855865
private void validateTransportConfigurationWithCorrectClassLoader(AgentCard agentCard) {
@@ -902,11 +912,12 @@ public static void setStreamingSubscribedRunnable(Runnable runnable) {
902912
protected abstract RequestHandler getRequestHandler();
903913

904914
/**
905-
* Returns the public agent card defining the agent's capabilities and metadata.
915+
* Returns the public agent card defining the agent's capabilities and metadata,
916+
* or {@code null} if no public agent card is configured.
906917
*
907-
* @return the agent card
918+
* @return the agent card, or {@code null} if not configured
908919
*/
909-
protected abstract AgentCard getAgentCard();
920+
protected abstract @Nullable AgentCard getAgentCard();
910921

911922
/**
912923
* Returns the extended agent card with additional capabilities, or null if not configured.

‎transport/grpc/src/test/java/org/a2aproject/sdk/transport/grpc/handler/GrpcHandlerTest.java‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1380,6 +1380,55 @@ private <V> void assertGrpcError(StreamRecorder<V> streamRecorder, Status.Code e
13801380
}
13811381
}
13821382

1383+
@Test
1384+
public void testGetAgentCardReturnsNullFallsBackToExtendedCard() throws Exception {
1385+
AgentCard extendedCard = AgentCard.builder(AbstractA2ARequestHandlerTest.CARD)
1386+
.capabilities(AgentCapabilities.builder().streaming(true).pushNotifications(true).build()).build();
1387+
GrpcHandler handler = new TestGrpcHandler(null, requestHandler, internalExecutor) {
1388+
@Override
1389+
protected AgentCard getExtendedAgentCard() {
1390+
return extendedCard;
1391+
}
1392+
};
1393+
taskStore.save(AbstractA2ARequestHandlerTest.MINIMAL_TASK, false);
1394+
agentExecutorExecute = (context, agentEmitter) -> {
1395+
agentEmitter.sendMessage(context.getMessage());
1396+
};
1397+
1398+
StreamRecorder<SendMessageResponse> streamRecorder = StreamRecorder.create();
1399+
SendMessageRequest request = SendMessageRequest.newBuilder()
1400+
.setMessage(GRPC_MESSAGE)
1401+
.build();
1402+
handler.sendMessage(request, streamRecorder);
1403+
streamRecorder.awaitCompletion(5, TimeUnit.SECONDS);
1404+
1405+
Assertions.assertNull(streamRecorder.getError());
1406+
Assertions.assertFalse(streamRecorder.getValues().isEmpty());
1407+
}
1408+
1409+
@Test
1410+
public void testNoCardAtAllThrowsError() throws Exception {
1411+
GrpcHandler handler = new TestGrpcHandler(null, requestHandler, internalExecutor) {
1412+
@Override
1413+
protected AgentCard getExtendedAgentCard() {
1414+
return null;
1415+
}
1416+
};
1417+
taskStore.save(AbstractA2ARequestHandlerTest.MINIMAL_TASK, false);
1418+
agentExecutorExecute = (context, agentEmitter) -> {
1419+
agentEmitter.sendMessage(context.getMessage());
1420+
};
1421+
1422+
StreamRecorder<SendMessageResponse> streamRecorder = StreamRecorder.create();
1423+
SendMessageRequest request = SendMessageRequest.newBuilder()
1424+
.setMessage(GRPC_MESSAGE)
1425+
.build();
1426+
handler.sendMessage(request, streamRecorder);
1427+
streamRecorder.awaitCompletion(5, TimeUnit.SECONDS);
1428+
1429+
assertGrpcError(streamRecorder, Status.Code.INTERNAL);
1430+
}
1431+
13831432
@Test
13841433
public void testListTasksNegativeTimestampReturnsInvalidArgument() {
13851434
TestGrpcHandler handler = new TestGrpcHandler(CARD, requestHandler, internalExecutor);

‎transport/jsonrpc/src/main/java/org/a2aproject/sdk/transport/jsonrpc/handler/JSONRPCHandler.java‎

Lines changed: 21 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -191,12 +191,13 @@ public JSONRPCHandler(@PublicAgentCard Instance<AgentCard> agentCardInstance,
191191
/**
192192
* Creates a JSON-RPC handler with basic dependencies.
193193
*
194-
* @param agentCard the agent card containing agent capabilities
194+
* @param agentCard the agent card containing agent capabilities, or {@code null} if no public card
195195
* @param requestHandler the handler for processing A2A requests
196196
* @param executor the executor for asynchronous operations
197197
*/
198-
public JSONRPCHandler(@PublicAgentCard AgentCard agentCard, RequestHandler requestHandler, Executor executor) {
199-
this(new FixedInstance<>(agentCard), null, requestHandler, executor, null);
198+
public JSONRPCHandler(@Nullable AgentCard agentCard, RequestHandler requestHandler, Executor executor) {
199+
this(agentCard != null ? new FixedInstance<>(agentCard) : FixedInstance.empty(),
200+
null, requestHandler, executor, null);
200201
}
201202

202203
/**
@@ -731,16 +732,16 @@ private void validateVersionAndExtensions(ServerCallContext context) throws A2AE
731732
}
732733

733734
/**
734-
* Returns the public agent card.
735+
* Returns the public agent card, or {@code null} if no {@code @PublicAgentCard} bean is configured.
735736
*
736737
* <p>The agent card is a self-describing manifest that provides essential metadata about
737738
* the agent, including its capabilities, supported skills, communication methods, and
738739
* security requirements.
739740
*
740-
* @return the public agent card
741+
* @return the public agent card, or {@code null} if not configured
741742
* @see AgentCard
742743
*/
743-
public AgentCard getAgentCard() {
744+
public @Nullable AgentCard getAgentCard() {
744745
return getAgentCard(null);
745746
}
746747

@@ -755,10 +756,10 @@ public AgentCard getAgentCard() {
755756
* is returned (single-tenant server, tenant segment is ignored).
756757
*
757758
* @param tenant the tenant identifier, may be {@code null}
758-
* @return the public agent card
759+
* @return the public agent card, or {@code null} if no {@code @PublicAgentCard} bean is configured
759760
* @throws TenantNotFoundException if a router is configured but the tenant is not registered
760761
*/
761-
public AgentCard getAgentCard(@Nullable String tenant) {
762+
public @Nullable AgentCard getAgentCard(@Nullable String tenant) {
762763
Utils.validateTenant(tenant);
763764
if (tenant != null && !tenant.isBlank()) {
764765
if (agentCardRouter != null) {
@@ -771,11 +772,21 @@ public AgentCard getAgentCard(@Nullable String tenant) {
771772
}
772773
LOGGER.fine(() -> "No AgentCardRouter configured; serving default public card for tenant '" + tenant + "'");
773774
}
774-
return resolveAgentCard();
775+
if (!agentCardInstance.isResolvable()) {
776+
return null;
777+
}
778+
return AgentCardValidator.resolveAndValidateOnce(agentCardInstance, transportValidated);
775779
}
776780

777781
private AgentCard resolveAgentCard() {
778-
return AgentCardValidator.resolveAndValidateOnce(agentCardInstance, transportValidated);
782+
if (agentCardInstance.isResolvable()) {
783+
return AgentCardValidator.resolveAndValidateOnce(agentCardInstance, transportValidated);
784+
}
785+
if (extendedAgentCard != null && extendedAgentCard.isResolvable()) {
786+
return AgentCardValidator.resolveAndValidateOnce(extendedAgentCard, transportValidated);
787+
}
788+
throw new IllegalStateException(
789+
"No agent card configured. Provide either a @PublicAgentCard or @ExtendedAgentCard bean.");
779790
}
780791

781792
private Flow.Publisher<SendStreamingMessageResponse> convertToSendStreamingMessageResponse(

0 commit comments

Comments
 (0)