Optional slash-style aliases for gateways that cannot publish colon-style action paths
*
*
* The partner only needs to provide an {@link AgentExecutor} implementation as a
@@ -214,4 +215,17 @@ public A2AController a2aController(
RestHandler restHandler, RequestHandler requestHandler, AgentCard agentCard) {
return new A2AController(restHandler, requestHandler, agentCard);
}
+
+ /**
+ * Adds non-standard slash-style action aliases without changing the canonical A2A endpoints.
+ * This compatibility surface is disabled unless explicitly enabled for a constrained gateway.
+ */
+ @Bean
+ @ConditionalOnMissingBean(A2ASlashActionAliasController.class)
+ @ConditionalOnProperty(
+ name = "a2at.server.slash-action-aliases-enabled",
+ havingValue = "true")
+ A2ASlashActionAliasController a2aSlashActionAliasController(A2AController delegate) {
+ return new A2ASlashActionAliasController(delegate);
+ }
}
diff --git a/spring-boot-starter/src/main/java/dev/openan/workflow/engine/spring/A2AProperties.java b/spring-boot-starter/src/main/java/dev/openan/workflow/engine/spring/A2AProperties.java
index c6fa7e0..af986f1 100644
--- a/spring-boot-starter/src/main/java/dev/openan/workflow/engine/spring/A2AProperties.java
+++ b/spring-boot-starter/src/main/java/dev/openan/workflow/engine/spring/A2AProperties.java
@@ -39,6 +39,12 @@ public class A2AProperties {
/** URL path prefix for A2A endpoints; all controller mappings are anchored under it. */
private String pathPrefix = "/a2a/json";
+ /**
+ * Whether to expose slash-style aliases for A2A action endpoints for gateways that reject
+ * colons in published paths. Standard colon-style endpoints always remain available.
+ */
+ private boolean slashActionAliasesEnabled = false;
+
/** Timeout for blocking agent execution. */
private int agentTimeoutSeconds = 30;
@@ -89,6 +95,14 @@ public void setPathPrefix(String pathPrefix) {
this.pathPrefix = pathPrefix;
}
+ public boolean isSlashActionAliasesEnabled() {
+ return slashActionAliasesEnabled;
+ }
+
+ public void setSlashActionAliasesEnabled(boolean slashActionAliasesEnabled) {
+ this.slashActionAliasesEnabled = slashActionAliasesEnabled;
+ }
+
public int getAgentTimeoutSeconds() {
return agentTimeoutSeconds;
}
diff --git a/spring-boot-starter/src/main/java/dev/openan/workflow/engine/spring/A2ASlashActionAliasController.java b/spring-boot-starter/src/main/java/dev/openan/workflow/engine/spring/A2ASlashActionAliasController.java
new file mode 100644
index 0000000..51d8683
--- /dev/null
+++ b/spring-boot-starter/src/main/java/dev/openan/workflow/engine/spring/A2ASlashActionAliasController.java
@@ -0,0 +1,79 @@
+/*
+ * Copyright (c) 2026 OpenAN. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package dev.openan.workflow.engine.spring;
+
+import jakarta.servlet.http.HttpServletRequest;
+import org.a2aproject.sdk.spec.A2AError;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
+
+/**
+ * Optional slash-style aliases for A2A action endpoints.
+ *
+ *
Every operation delegates to {@link A2AController}; the aliases therefore retain the
+ * canonical endpoint's authentication, A2A error envelope, streaming, and cleanup behavior.
+ */
+@RestController
+@ConditionalOnProperty(
+ name = "a2at.server.slash-action-aliases-enabled",
+ havingValue = "true")
+final class A2ASlashActionAliasController {
+
+ private final A2AController delegate;
+
+ A2ASlashActionAliasController(A2AController delegate) {
+ this.delegate = delegate;
+ }
+
+ @PostMapping("${a2at.server.path-prefix}/message/send")
+ ResponseEntity sendMessage(HttpServletRequest request, @RequestBody String body) {
+ return delegate.sendMessage(request, body);
+ }
+
+ @PostMapping(
+ value = "${a2at.server.path-prefix}/message/stream",
+ produces = MediaType.TEXT_EVENT_STREAM_VALUE)
+ SseEmitter streamMessage(HttpServletRequest request, @RequestBody String body) {
+ return delegate.streamMessage(request, body);
+ }
+
+ @PostMapping("${a2at.server.path-prefix}/tasks/{id}/cancel")
+ ResponseEntity cancelTask(
+ HttpServletRequest request,
+ @PathVariable("id") String taskId,
+ @RequestBody(required = false) String body) {
+ return delegate.cancelTask(request, taskId, body);
+ }
+
+ @PostMapping(
+ value = "${a2at.server.path-prefix}/tasks/{id}/subscribe",
+ produces = MediaType.TEXT_EVENT_STREAM_VALUE)
+ SseEmitter subscribeToTask(HttpServletRequest request, @PathVariable("id") String taskId) {
+ return delegate.subscribeToTask(request, taskId);
+ }
+
+ @ExceptionHandler(A2AError.class)
+ ResponseEntity a2aError(A2AError error) {
+ return delegate.a2aError(error);
+ }
+}
diff --git a/spring-boot-starter/src/test/java/dev/openan/workflow/engine/spring/A2AAutoConfigurationTest.java b/spring-boot-starter/src/test/java/dev/openan/workflow/engine/spring/A2AAutoConfigurationTest.java
index aa030a4..3fbdb3c 100644
--- a/spring-boot-starter/src/test/java/dev/openan/workflow/engine/spring/A2AAutoConfigurationTest.java
+++ b/spring-boot-starter/src/test/java/dev/openan/workflow/engine/spring/A2AAutoConfigurationTest.java
@@ -26,6 +26,7 @@
import static org.mockito.ArgumentMatchers.eq;
import static org.mockito.Mockito.doThrow;
import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.verifyNoInteractions;
import static org.mockito.Mockito.when;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
@@ -41,6 +42,7 @@
import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.atomic.AtomicReference;
import org.a2aproject.sdk.server.ServerCallContext;
+import org.a2aproject.sdk.server.agentexecution.AgentExecutor;
import org.a2aproject.sdk.server.auth.TaskOperation;
import org.a2aproject.sdk.server.config.A2AConfigProvider;
import org.a2aproject.sdk.server.requesthandlers.RequestHandler;
@@ -311,6 +313,120 @@ void streamingCapabilityIsCheckedBeforeInvokingBusinessHandler() throws Exceptio
verifyNoInteractions(requestHandler);
}
+ @Test
+ void slashActionAliasesDelegateToTheCanonicalController() throws Exception {
+ RestHandler restHandler = mock(RestHandler.class);
+ when(restHandler.sendMessage(any(), eq(""), eq("{}")))
+ .thenReturn(new RestHandler.HTTPRestResponse(200, "application/json", "{}"));
+ RequestHandler requestHandler = mock(RequestHandler.class);
+ AgentCard agentCard = mock(AgentCard.class);
+ A2AController canonical = new A2AController(restHandler, requestHandler, agentCard);
+ var aliases = new A2ASlashActionAliasController(canonical);
+ MockMvc mockMvc =
+ MockMvcBuilders.standaloneSetup(aliases)
+ .addPlaceholderValue("a2at.server.path-prefix", "/a2a/json")
+ .build();
+
+ mockMvc
+ .perform(post("/a2a/json/message/send").content("{}"))
+ .andExpect(status().isOk())
+ .andExpect(content().contentTypeCompatibleWith("application/a2a+json"));
+
+ verify(restHandler).sendMessage(any(), eq(""), eq("{}"));
+ }
+
+ @Test
+ void everySlashActionAliasUsesTheConfiguredPrefix() throws Exception {
+ String placeholder = "${a2at.server.path-prefix}";
+ Class aliases = A2ASlashActionAliasController.class;
+
+ assertEquals(
+ placeholder + "/message/send",
+ aliases
+ .getDeclaredMethod(
+ "sendMessage", jakarta.servlet.http.HttpServletRequest.class, String.class)
+ .getAnnotation(PostMapping.class)
+ .value()[0]);
+ assertEquals(
+ placeholder + "/message/stream",
+ aliases
+ .getDeclaredMethod(
+ "streamMessage", jakarta.servlet.http.HttpServletRequest.class, String.class)
+ .getAnnotation(PostMapping.class)
+ .value()[0]);
+ assertEquals(
+ placeholder + "/tasks/{id}/cancel",
+ aliases
+ .getDeclaredMethod(
+ "cancelTask",
+ jakarta.servlet.http.HttpServletRequest.class,
+ String.class,
+ String.class)
+ .getAnnotation(PostMapping.class)
+ .value()[0]);
+ assertEquals(
+ placeholder + "/tasks/{id}/subscribe",
+ aliases
+ .getDeclaredMethod(
+ "subscribeToTask", jakarta.servlet.http.HttpServletRequest.class, String.class)
+ .getAnnotation(PostMapping.class)
+ .value()[0]);
+ }
+
+ @Test
+ void slashStreamingAliasUsesTheCanonicalA2aErrorEnvelope() throws Exception {
+ RestHandler restHandler = mock(RestHandler.class);
+ when(restHandler.createErrorResponse(any()))
+ .thenReturn(
+ new RestHandler.HTTPRestResponse(
+ 501,
+ "application/a2a+json",
+ "{\"error\":{\"code\":-32004,\"status\":\"UNIMPLEMENTED\"}}"));
+ RequestHandler requestHandler = mock(RequestHandler.class);
+ AgentCard agentCard = mock(AgentCard.class);
+ when(agentCard.capabilities()).thenReturn(AgentCapabilities.builder().streaming(false).build());
+ A2AController canonical = new A2AController(restHandler, requestHandler, agentCard);
+ var aliases = new A2ASlashActionAliasController(canonical);
+ MockMvc mockMvc =
+ MockMvcBuilders.standaloneSetup(aliases)
+ .addPlaceholderValue("a2at.server.path-prefix", "/a2a/json")
+ .build();
+
+ mockMvc
+ .perform(post("/a2a/json/message/stream").content("{}"))
+ .andExpect(status().is(501))
+ .andExpect(content().contentTypeCompatibleWith("application/a2a+json"));
+
+ verifyNoInteractions(requestHandler);
+ }
+
+ @Test
+ void slashActionAliasesAreOptIn() {
+ A2AController canonical = mock(A2AController.class);
+ WebApplicationContextRunner runner =
+ new WebApplicationContextRunner()
+ .withConfiguration(AutoConfigurations.of(A2AAutoConfiguration.class))
+ .withBean(AgentCard.class, () -> mock(AgentCard.class))
+ .withBean(AgentExecutor.class, () -> mock(AgentExecutor.class))
+ .withBean(RequestHandler.class, () -> mock(RequestHandler.class))
+ .withBean(RestHandler.class, () -> mock(RestHandler.class))
+ .withBean(A2AController.class, () -> canonical);
+
+ runner.run(
+ context -> assertFalse(context.containsBean("a2aSlashActionAliasController")));
+ runner
+ .withPropertyValues("a2at.server.slash-action-aliases-enabled=true")
+ .run(context -> assertTrue(context.containsBean("a2aSlashActionAliasController")));
+ }
+
+ @Test
+ void slashActionAliasPropertyDefaultsToDisabled() {
+ A2AProperties properties = new A2AProperties();
+ assertFalse(properties.isSlashActionAliasesEnabled());
+ properties.setSlashActionAliasesEnabled(true);
+ assertTrue(properties.isSlashActionAliasesEnabled());
+ }
+
@Test
void blockingTimeoutsComeFromProperties() {
A2AProperties properties = new A2AProperties();