|
| 1 | +--- |
| 2 | +layout: post |
| 3 | +title: 'A2A Java SDK 1.3.0.Final Released' |
| 4 | +date: 2026-08-27 |
| 5 | +tags: ai a2a |
| 6 | +synopsis: 'A2A Java SDK 1.3.0.Final is now available -- with multi-tenancy support, fail-closed authorization, comprehensive security hardening, and protocol compliance improvements.' |
| 7 | +author: ehsavoie |
| 8 | +image: announce.png |
| 9 | +--- |
| 10 | +image::announce.png[A2A Java SDK 1.3.0.Final announcement] |
| 11 | + |
| 12 | +I am happy to announce the release of link:https://github.com/a2aproject/a2a-java/releases/tag/v1.3.0.Final[A2A Java SDK 1.3.0.Final]. This release introduces multi-tenancy support, switches the authorization model to fail-closed by default, delivers a wave of security hardening, and improves protocol compliance across all transports. |
| 13 | + |
| 14 | +NOTE: This release contains **breaking changes**. See the <<migration>> section for details. |
| 15 | + |
| 16 | +== What's New |
| 17 | + |
| 18 | +=== Multi-Tenancy Support |
| 19 | + |
| 20 | +The headline feature of 1.3.0 is **multi-tenancy** (link:https://github.com/a2aproject/a2a-java/pull/1084[\#1084]), which lets a single A2A server provide different agent behavior per tenant. Each tenant can have its own `AgentExecutor` (business logic) and `AgentCard` (capabilities, skills, metadata). Requests without a recognized tenant automatically fall back to the default beans. |
| 21 | + |
| 22 | +Two new SPIs in `server-common` define the routing contract: |
| 23 | + |
| 24 | +* `AgentExecutorRouter` -- resolves an `AgentExecutor` for each request based on the tenant identifier. |
| 25 | +* `AgentCardRouter` -- resolves the appropriate `AgentCard` for tenant-specific `getExtendedAgentCard` and public card endpoints. |
| 26 | + |
| 27 | +A CDI-based implementation is provided in the new `a2a-java-extras-multitenancy` module. Use the `@Tenant` qualifier on CDI producer methods to wire tenant-specific beans: |
| 28 | + |
| 29 | +[source,java] |
| 30 | +---- |
| 31 | +@Produces |
| 32 | +@Tenant("acme") |
| 33 | +public AgentExecutor acmeExecutor() { |
| 34 | + return new AcmeAgentExecutor(); |
| 35 | +} |
| 36 | +
|
| 37 | +@Produces |
| 38 | +@Tenant("acme") |
| 39 | +@ExtendedAgentCard |
| 40 | +public AgentCard acmeCard() { |
| 41 | + return AgentCard.builder().name("Acme Agent")...build(); |
| 42 | +} |
| 43 | +---- |
| 44 | + |
| 45 | +The resolved tenant is available in `RequestContext.getTenant()` during execution. Tenant-specific public cards are served at `/.well-known/{tenant}/agent-card.json`. Tenant identifiers are restricted to `a-zA-Z0-9_-.` characters. |
| 46 | + |
| 47 | +When `a2a-java-extras-multitenancy` is not on the classpath, the server behaves as a single-tenant deployment and no code changes are required. |
| 48 | + |
| 49 | +This is a **breaking change** -- see <<multitenancy-migration>> below. |
| 50 | + |
| 51 | +=== Fail-Closed Authorization Default |
| 52 | + |
| 53 | +The authorization model now defaults to **fail-closed** (link:https://github.com/a2aproject/a2a-java/pull/1095[\#1095], link:https://github.com/a2aproject/a2a-java/security/advisories/GHSA-qw47-mcm5-934w[GHSA-qw47-mcm5-934w]). Authorization enforcement has been moved from the CDI-only `AuthorizationRequestHandlerDecorator` directly into `DefaultRequestHandler`, so it is enforced on both the CDI and builder paths. When no `TaskAuthorizationProvider` is configured, all task operations are now denied by default. |
| 54 | + |
| 55 | +To restore the previous open behavior for single-user deployments or testing: |
| 56 | + |
| 57 | +[source,properties] |
| 58 | +---- |
| 59 | +a2a.authorization.required=false |
| 60 | +---- |
| 61 | + |
| 62 | +This is a **breaking change** -- see <<auth-migration>> below. |
| 63 | + |
| 64 | +=== Security Hardening |
| 65 | + |
| 66 | +This release includes a comprehensive set of security fixes addressing multiple vulnerability classes: |
| 67 | + |
| 68 | +==== Credential leakage prevention |
| 69 | + |
| 70 | +The SDK now validates API key header names against a safe allowlist and disables automatic HTTP redirect following in all HTTP clients (JDK, Vert.x, Android). This prevents credential leakage via header injection and cross-origin redirects (link:https://github.com/a2aproject/a2a-java/pull/1097[\#1097], link:https://github.com/a2aproject/a2a-java/security/advisories/GHSA-9rhm-2h4x-jwmx[GHSA-9rhm-2h4x-jwmx]). |
| 71 | + |
| 72 | +==== SSRF protection for push notifications |
| 73 | + |
| 74 | +Push notification URLs are now validated against an SSRF-safe policy: only allowed schemes, with private-network blocking including IPv4-mapped IPv6. HTTP redirect following is also disabled on push notification POST requests. A new `a2a.push-notifications.enabled` property gates push config storage (link:https://github.com/a2aproject/a2a-java/pull/1096[\#1096], link:https://github.com/a2aproject/a2a-java/security/advisories/GHSA-q78c-5jjq-57g8[GHSA-q78c-5jjq-57g8]). |
| 75 | + |
| 76 | +==== Additional hardening |
| 77 | + |
| 78 | +* **Authorization for listTasks** -- the `onListTasks` handler now performs a list-scoped read check before delegation (link:https://github.com/a2aproject/a2a-java/pull/1038[\#1038]) |
| 79 | +* **Error message sanitization** -- internal error messages are now sanitized to prevent information disclosure (link:https://github.com/a2aproject/a2a-java/security/advisories/GHSA-x32g-jvvm-4725[GHSA-x32g-jvvm-4725]) |
| 80 | +* **CR/LF injection prevention** -- push notification headers are validated to reject CR/LF characters (CWE-113) (link:https://github.com/a2aproject/a2a-java/pull/1053[\#1053]) |
| 81 | + |
| 82 | +==== Threat model |
| 83 | + |
| 84 | +A threat model has been added to link:https://github.com/a2aproject/a2a-java/blob/main/SECURITY.md[SECURITY.md] (link:https://github.com/a2aproject/a2a-java/pull/1090[\#1090]) to document the SDK's attack surface and security assumptions. |
| 85 | + |
| 86 | +==== Security reporting |
| 87 | + |
| 88 | +We would like to thank the community members who responsibly reported security issues. If you discover a security vulnerability, please follow the process described in our link:https://github.com/a2aproject/a2a-java/blob/main/SECURITY.md[SECURITY.md] -- your reports help us keep the SDK safe for everyone. |
| 89 | + |
| 90 | +=== AgentExecutor as Functional Interface |
| 91 | + |
| 92 | +`AgentExecutor` is now a `@FunctionalInterface` with a default no-op `cancel` method (link:https://github.com/a2aproject/a2a-java/pull/1028[\#1028]). Simple agents that don't need cancellation support can be implemented as lambdas: |
| 93 | + |
| 94 | +[source,java] |
| 95 | +---- |
| 96 | +AgentExecutor executor = (context, emitter) -> { |
| 97 | + emitter.text("Hello!"); |
| 98 | + emitter.done(); |
| 99 | +}; |
| 100 | +---- |
| 101 | + |
| 102 | +Existing implementations with an explicit `cancel` override are unaffected. |
| 103 | + |
| 104 | +=== CDI HTTP Client Provider |
| 105 | + |
| 106 | +The new `a2a-java-extras-http-client-cdi` module (link:https://github.com/a2aproject/a2a-java/pull/1071[\#1071]) adds a `CdiA2AHttpClientProvider` that resolves a user-provided `A2AHttpClient` bean from CDI at priority 200. The `A2AHttpClientFactory` now sorts providers by priority at class init and iterates in order, catching exceptions per-provider for graceful fallback. |
| 107 | + |
| 108 | +=== Protocol Compliance |
| 109 | + |
| 110 | +Several protocol compliance issues have been addressed: |
| 111 | + |
| 112 | +* **Version and extension validation on all operations** -- previously only enforced on message send paths, now checked on all nine JSON-RPC and REST operations per specification section 3.6.2 (link:https://github.com/a2aproject/a2a-java/pull/1066[\#1066]), and on all gRPC handler methods (link:https://github.com/a2aproject/a2a-java/pull/1042[\#1042]) |
| 113 | +* **Part content key validation** -- the JSON-RPC transport now rejects `Part` objects with multiple populated content keys (link:https://github.com/a2aproject/a2a-java/pull/1065[\#1065]) and prefers a populated content key when decoding (link:https://github.com/a2aproject/a2a-java/pull/1061[\#1061]) |
| 114 | +* **UnsupportedOperationError** -- streaming endpoints now return `-32004` when the agent card does not advertise streaming support, with a consistent error message across all transports (link:https://github.com/a2aproject/a2a-java/pull/1041[\#1041]) |
| 115 | +* **FilePart name field** -- `FilePart` now supports an optional `name` field as mentioned in the spec text (link:https://github.com/a2aproject/a2a-java/pull/1091[\#1091]) |
| 116 | + |
| 117 | +=== Interoperability Test Kit |
| 118 | + |
| 119 | +The ITK now uses shared scenarios from the upstream A2A specification (link:https://github.com/a2aproject/a2a-java/pull/1094[\#1094]) and has been upgraded to the v2 ITK launcher (link:https://github.com/a2aproject/a2a-java/pull/1063[\#1063]). |
| 120 | + |
| 121 | +== Bug Fixes |
| 122 | + |
| 123 | +* **Enforce task state-machine transitions** -- tasks now follow strict state-machine transition rules, preventing invalid state changes. Cancel operations are serialized to avoid races (link:https://github.com/a2aproject/a2a-java/pull/1045[\#1045]) |
| 124 | +* **Per-task push notification config limit** -- the `PushNotificationConfigStore` now enforces a per-task limit on push notification configurations (link:https://github.com/a2aproject/a2a-java/pull/1044[\#1044]) |
| 125 | +* **Hardened event consumer and queue** -- event processing is now more resilient to concurrent access patterns (link:https://github.com/a2aproject/a2a-java/pull/1040[\#1040]) |
| 126 | +* **Guard limitTaskHistory against negative values** -- `limitTaskHistory` no longer accepts negative `historyLength` values (link:https://github.com/a2aproject/a2a-java/pull/1039[\#1039]) |
| 127 | +* **Thread-safe InMemoryPushNotificationConfigStore** -- replaced `synchronizedMap` with `ConcurrentHashMap` using atomic per-key operations and immutable snapshot storage (link:https://github.com/a2aproject/a2a-java/pull/1057[\#1057]) |
| 128 | +* **Deferred AgentCard resolution** -- all transport handlers now resolve `AgentCard` lazily to prevent startup failures when the card producer depends on the HTTP server's bound address (link:https://github.com/a2aproject/a2a-java/pull/1058[\#1058]) |
| 129 | +* **gRPC transport validation** -- improved validation and error messages in the gRPC transport layer (link:https://github.com/a2aproject/a2a-java/pull/1026[\#1026]) |
| 130 | + |
| 131 | +[[migration]] |
| 132 | +== Migration from 1.2.0.Final |
| 133 | + |
| 134 | +Update your BOM version: |
| 135 | + |
| 136 | +[source,xml] |
| 137 | +---- |
| 138 | +<dependencyManagement> |
| 139 | + <dependencies> |
| 140 | + <dependency> |
| 141 | + <groupId>org.a2aproject.sdk</groupId> |
| 142 | + <artifactId>a2a-java-sdk-bom</artifactId> |
| 143 | + <version>1.3.0.Final</version> |
| 144 | + <type>pom</type> |
| 145 | + <scope>import</scope> |
| 146 | + </dependency> |
| 147 | + </dependencies> |
| 148 | +</dependencyManagement> |
| 149 | +---- |
| 150 | + |
| 151 | +This release has two breaking changes: |
| 152 | + |
| 153 | +[[multitenancy-migration]] |
| 154 | +=== 1. Multi-tenancy routing changes DefaultRequestHandler |
| 155 | + |
| 156 | +The introduction of `AgentExecutorRouter` and `AgentCardRouter` changes the `DefaultRequestHandler` constructor and builder. If you wire `DefaultRequestHandler` programmatically, update to the new API: |
| 157 | + |
| 158 | +[source,java] |
| 159 | +---- |
| 160 | +// Single-tenant: unchanged usage |
| 161 | +DefaultRequestHandler handler = DefaultRequestHandler.builder() |
| 162 | + .agentExecutor(agentExecutor) |
| 163 | + .taskStore(taskStore) |
| 164 | + .queueManager(queueManager) |
| 165 | + // ... |
| 166 | + .build(); |
| 167 | +---- |
| 168 | + |
| 169 | +For multi-tenant deployments without CDI, supply an `AgentExecutorRouter` directly on the builder: |
| 170 | + |
| 171 | +[source,java] |
| 172 | +---- |
| 173 | +Map<String, AgentExecutor> executors = Map.of( |
| 174 | + "acme", new AcmeAgentExecutor(), |
| 175 | + "beta", new BetaAgentExecutor() |
| 176 | +); |
| 177 | +AgentExecutor defaultExecutor = new DefaultAgentExecutor(); |
| 178 | +
|
| 179 | +AgentExecutorRouter router = tenant -> |
| 180 | + executors.getOrDefault(tenant, defaultExecutor); |
| 181 | +
|
| 182 | +DefaultRequestHandler handler = DefaultRequestHandler.builder() |
| 183 | + .agentExecutorRouter(router) // replaces .agentExecutor() for multi-tenant |
| 184 | + .taskStore(taskStore) |
| 185 | + .queueManager(queueManager) |
| 186 | + // ... |
| 187 | + .build(); |
| 188 | +---- |
| 189 | + |
| 190 | +CDI-based deployments pick up the routers automatically when `a2a-java-extras-multitenancy` is on the classpath. |
| 191 | + |
| 192 | +`GetExtendedAgentCardRequest` now carries `GetExtendedAgentCardParams` to support tenant-specific card resolution. |
| 193 | + |
| 194 | +[[auth-migration]] |
| 195 | +=== 2. Fail-closed authorization default |
| 196 | + |
| 197 | +Applications without a `TaskAuthorizationProvider` will now reject all task operations by default. Either: |
| 198 | + |
| 199 | +* Provide a `TaskAuthorizationProvider` implementation, or |
| 200 | +* Set `a2a.authorization.required=false` to restore the previous open behavior |
| 201 | + |
| 202 | +[source,properties] |
| 203 | +---- |
| 204 | +# For development/testing or single-user deployments |
| 205 | +a2a.authorization.required=false |
| 206 | +---- |
| 207 | + |
| 208 | +== Contributors |
| 209 | + |
| 210 | +Thank you to the contributors of this release! |
| 211 | + |
| 212 | +link:https://github.com/ehsavoie[@ehsavoie], link:https://github.com/kabir[@kabir], link:https://github.com/ez-lbz[@ez-lbz], link:https://github.com/JakubWorek[@JakubWorek], link:https://github.com/malladinagarjuna2[@malladinagarjuna2], link:https://github.com/omatheusmesmo[@omatheusmesmo], link:https://github.com/ruilopes[@ruilopes], link:https://github.com/KXH[@KXH] |
| 213 | + |
| 214 | +== Resources |
| 215 | + |
| 216 | +* link:https://github.com/a2aproject/a2a-java/releases/tag/v1.3.0.Final[Release Notes on GitHub] |
| 217 | +* link:https://central.sonatype.com/artifact/org.a2aproject.sdk/a2a-java-sdk-parent/1.3.0.Final[Maven Central] |
| 218 | +* link:https://javadoc.io/doc/org.a2aproject.sdk/[JavaDoc] |
| 219 | +* link:https://a2a-protocol.org/v1.0.0/specification/[A2A Specification] |
| 220 | +* link:https://a2aproject.github.io/a2a-java/[Project Website] |
| 221 | +* link:https://github.com/a2aproject/a2a-java/tree/main/examples[Examples] |
| 222 | + |
| 223 | +== Come Join Us |
| 224 | + |
| 225 | +We value your feedback a lot so please report bugs, ask for improvements etc. Let's build something great together! |
| 226 | + |
| 227 | +If you are an A2A Java SDK user or just curious, don't be shy and join our welcoming community: |
| 228 | + |
| 229 | +* provide feedback on link:https://github.com/a2aproject/a2a-java/issues[GitHub]; |
| 230 | +* craft some code and link:https://github.com/a2aproject/a2a-java/pulls[push a PR]; |
| 231 | +* discuss with us in the `#a2a-java` channel on link:https://discord.gg/jTtSkJB74Q[Discord]; |
0 commit comments