Skip to content

Commit bdcdd46

Browse files
authored
docs(site): extract standalone pages and complete doc structure (a2aproject#977)
* Overrides the default Roq page layout to use `link: /:raw-path`, which prevents URL slugification of directory names (e.g., keeps `1.0.0.Final` instead of `1-0-0-final`). Required for the versioned documentation site restructure described in the plan at docs/superpowers/plans/2026-06-25-versioned-doc-site-plan.md. * docs(site): extract standalone pages and complete doc structure Extract configuration, authorization, and backward compatibility into standalone pages. Add BOMs, examples, and getting-started pages. Update navigation menu and add compatibility matrix tolanding page.
1 parent 529228a commit bdcdd46

14 files changed

Lines changed: 751 additions & 591 deletions

File tree

‎docs/content/about.md‎

Lines changed: 0 additions & 19 deletions
This file was deleted.

‎docs/content/authorization.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: Task Authorization
3+
description: Per-user access control for A2A tasks — ownership, read/write checks, and user identity across transports.
4+
layout: page
5+
---
6+
7+
# Task Authorization
8+
9+
> **Security note:** For multi-user deployments, a `TaskAuthorizationProvider` **must** be configured. Without one, all operations are permitted regardless of authentication — any authenticated user can read, modify, or cancel any task. Production deployments should use a fail-closed ownership policy (deny access when ownership is unknown).
10+
11+
## Implementing TaskAuthorizationProvider
12+
13+
Implement `TaskAuthorizationProvider` to control per-user access:
14+
15+
```java
16+
@ApplicationScoped
17+
public class MyTaskAuthorizationProvider implements TaskAuthorizationProvider {
18+
19+
@Override
20+
public boolean checkRead(ServerCallContext context, String taskId, TaskOperation op) {
21+
return isOwner(context.getUser(), taskId);
22+
}
23+
24+
@Override
25+
public boolean checkWrite(ServerCallContext context, String taskId, TaskOperation op) {
26+
return isOwner(context.getUser(), taskId);
27+
}
28+
29+
@Override
30+
public boolean checkCreate(ServerCallContext context, TaskOperation op) {
31+
return context.getUser() != null && context.getUser().isAuthenticated();
32+
}
33+
34+
@Override
35+
public boolean isTaskRecorded(String taskId) {
36+
return ownershipStore.contains(taskId);
37+
}
38+
39+
@Override
40+
public void recordOwnership(ServerCallContext context, String taskId, TaskOperation op) {
41+
if (context.getUser() != null) {
42+
ownershipStore.put(taskId, context.getUser().getUsername());
43+
}
44+
}
45+
}
46+
```
47+
48+
The SDK discovers the bean via CDI automatically — no additional wiring needed.
49+
50+
> **Note:** When task authorization is required, always obtain `RequestHandler` through CDI injection. Manual instantiation via `DefaultRequestHandler.create()` bypasses the `AuthorizationRequestHandlerDecorator` and all authorization checks.
51+
52+
## User Identity in ServerCallContext
53+
54+
Authorization decisions rely on `context.getUser()` returning the authenticated user. How the user is populated depends on the transport:
55+
56+
- **JSON-RPC and REST**: The Quarkus route handler extracts the user from the Vert.x routing context (`rc.userContext()`) and sets it on `ServerCallContext` directly.
57+
- **gRPC**: The reference server includes a `QuarkusCallContextFactory` CDI bean that injects the Quarkus `SecurityIdentity` and maps it to the `ServerCallContext` `User`. This happens automatically when using the reference gRPC module. If you provide your own `CallContextFactory`, you are responsible for populating the user.
58+
59+
## Authorization Checks
60+
61+
| Operation | Authorization check |
62+
|-----------|---------------------|
63+
| `getTask`, `subscribeToTask`, `getTaskPushNotificationConfig`, `listTaskPushNotificationConfigs` | `checkRead` |
64+
| `cancelTask`, `createTaskPushNotificationConfig`, `deleteTaskPushNotificationConfig` | `checkWrite` |
65+
| `messageSend` / `messageSendStream` (existing task) | `checkWrite` |
66+
| `messageSend` / `messageSendStream` (new task) | `checkCreate`, then `recordOwnership` |
67+
| `listTasks` | `checkRead` per task |

‎docs/content/boms.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
title: Bill of Materials (BOM)
3+
description: Dependency management BOMs for the A2A Java SDK — SDK, Extras, and Reference BOMs.
4+
layout: page
5+
---
6+
7+
# Bill of Materials (BOM)
8+
9+
The A2A Java SDK provides three BOMs for different use cases, so you can manage dependency versions in one place.
10+
11+
## BOM Modules
12+
13+
### SDK BOM
14+
15+
**Artifact:** `org.a2aproject.sdk:a2a-java-sdk-bom`
16+
17+
Includes all A2A SDK core modules (spec, server, client, transport), core third-party dependencies, Jakarta APIs, and test utilities.
18+
19+
**Use this BOM when:** Building A2A agents with any framework (Quarkus, Spring Boot, vanilla Java, etc.)
20+
21+
### Extras BOM
22+
23+
**Artifact:** `org.a2aproject.sdk:a2a-java-sdk-extras-bom`
24+
25+
Includes everything from the SDK BOM plus server-side enhancement modules (database persistence, distributed queue management, etc.).
26+
27+
**Use this BOM when:** Building production A2A servers needing advanced server-side features beyond the core SDK.
28+
29+
### Reference BOM
30+
31+
**Artifact:** `org.a2aproject.sdk:a2a-java-sdk-reference-bom`
32+
33+
Includes everything from the SDK BOM plus the Quarkus BOM (complete Quarkus platform), A2A reference implementation modules, and the TCK module for testing.
34+
35+
**Use this BOM when:** Building Quarkus-based A2A agents or reference implementations.
36+
37+
## Usage
38+
39+
### SDK BOM (Any Framework)
40+
41+
```xml
42+
<dependencyManagement>
43+
<dependencies>
44+
<dependency>
45+
<groupId>org.a2aproject.sdk</groupId>
46+
<artifactId>a2a-java-sdk-bom</artifactId>
47+
<version>$\{org.a2aproject.sdk.version}</version>
48+
<type>pom</type>
49+
<scope>import</scope>
50+
</dependency>
51+
</dependencies>
52+
</dependencyManagement>
53+
54+
<dependencies>
55+
<!-- No version needed - managed by BOM -->
56+
<dependency>
57+
<groupId>org.a2aproject.sdk</groupId>
58+
<artifactId>a2a-java-sdk-server-common</artifactId>
59+
</dependency>
60+
<dependency>
61+
<groupId>org.a2aproject.sdk</groupId>
62+
<artifactId>a2a-java-sdk-transport-jsonrpc</artifactId>
63+
</dependency>
64+
</dependencies>
65+
```
66+
67+
### Extras BOM (Database Persistence, Distributed Deployments)
68+
69+
```xml
70+
<dependencyManagement>
71+
<dependencies>
72+
<dependency>
73+
<groupId>org.a2aproject.sdk</groupId>
74+
<artifactId>a2a-java-sdk-extras-bom</artifactId>
75+
<version>$\{org.a2aproject.sdk.version}</version>
76+
<type>pom</type>
77+
<scope>import</scope>
78+
</dependency>
79+
</dependencies>
80+
</dependencyManagement>
81+
82+
<dependencies>
83+
<dependency>
84+
<groupId>org.a2aproject.sdk</groupId>
85+
<artifactId>a2a-java-sdk-server-common</artifactId>
86+
</dependency>
87+
<dependency>
88+
<groupId>org.a2aproject.sdk</groupId>
89+
<artifactId>a2a-java-extras-task-store-database-jpa</artifactId>
90+
</dependency>
91+
</dependencies>
92+
```
93+
94+
### Reference BOM (Quarkus)
95+
96+
```xml
97+
<dependencyManagement>
98+
<dependencies>
99+
<dependency>
100+
<groupId>org.a2aproject.sdk</groupId>
101+
<artifactId>a2a-java-sdk-reference-bom</artifactId>
102+
<version>$\{org.a2aproject.sdk.version}</version>
103+
<type>pom</type>
104+
<scope>import</scope>
105+
</dependency>
106+
</dependencies>
107+
</dependencyManagement>
108+
109+
<dependencies>
110+
<!-- A2A SDK and Quarkus versions both managed -->
111+
<dependency>
112+
<groupId>org.a2aproject.sdk</groupId>
113+
<artifactId>a2a-java-sdk-reference-jsonrpc</artifactId>
114+
</dependency>
115+
<dependency>
116+
<groupId>io.quarkus</groupId>
117+
<artifactId>quarkus-arc</artifactId>
118+
</dependency>
119+
</dependencies>
120+
```

‎docs/content/client.md‎

Lines changed: 2 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -190,42 +190,8 @@ Client client = Client
190190

191191
## Communicating with v0.3 Agents
192192

193-
Use `Client_v0_3` to communicate with agents that only support protocol v0.3:
194-
195-
```xml
196-
<dependency>
197-
<groupId>org.a2aproject.sdk</groupId>
198-
<artifactId>a2a-java-sdk-compat-0.3-client</artifactId>
199-
<version>$\{org.a2aproject.sdk.version}</version>
200-
</dependency>
201-
<dependency>
202-
<groupId>org.a2aproject.sdk</groupId>
203-
<artifactId>a2a-java-sdk-compat-0.3-client-transport-jsonrpc</artifactId>
204-
<version>$\{org.a2aproject.sdk.version}</version>
205-
</dependency>
206-
```
207-
208-
gRPC and REST transports are also available:
209-
- `a2a-java-sdk-compat-0.3-client-transport-grpc`
210-
- `a2a-java-sdk-compat-0.3-client-transport-rest`
211-
212-
```java
213-
AgentCard card = A2ACardResolver.builder().baseUrl("http://localhost:1234")
214-
.build().getAgentCard();
215-
216-
AgentInterface v03Interface = card.supportedInterfaces().stream()
217-
.filter(i -> A2AProtocol_v0_3.PROTOCOL_VERSION.equals(i.protocolVersion()))
218-
.findFirst().orElseThrow();
219-
220-
Client_v0_3 client = ClientBuilder_v0_3.forUrl(v03Interface.url())
221-
.withTransport(JSONRPCTransport_v0_3.class, new JSONRPCTransportConfigBuilder_v0_3())
222-
.build();
223-
```
224-
225-
**Note:** `Client_v0_3` exposes only operations available in protocol v0.3. For example, `listTasks()` is not available (it was added in v1.0). Return types use v0.3 domain objects from the `org.a2aproject.sdk.compat03.spec` package.
193+
See [Backward Compatibility]({site.url('compatibility')}#client-communicating-with-v03-agents) for using `Client_v0_3` with older protocol agents.
226194

227195
## Examples
228196

229-
- [Hello World Client](https://github.com/a2aproject/a2a-java/blob/main/examples/helloworld/client/README.md) — Java client talking to a Python A2A server
230-
- [Hello World Server](https://github.com/a2aproject/a2a-java/blob/main/examples/helloworld/server/README.md) — Python client talking to a Java A2A server
231-
- [a2a-samples repository](https://github.com/a2aproject/a2a-samples/tree/main/samples/java/agents) — More agent examples
197+
See [Examples]({site.url('examples')}) for Hello World walkthroughs and sample applications.

‎docs/content/compatibility.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: Backward Compatibility
3+
description: Serve v1.0 and v0.3 A2A protocol versions simultaneously — multi-version modules, version routing, and v0.3 client support.
4+
layout: page
5+
---
6+
7+
# Backward Compatibility with v0.3
8+
9+
Add compat modules alongside v1.0 modules to serve both protocol versions simultaneously. No changes to your `AgentExecutor` are needed.
10+
11+
## Server: Multi-Version Module (recommended)
12+
13+
```xml
14+
<!-- JSON-RPC with automatic v1.0 + v0.3 routing -->
15+
<dependency>
16+
<groupId>org.a2aproject.sdk</groupId>
17+
<artifactId>a2a-java-sdk-reference-multiversion-jsonrpc</artifactId>
18+
<version>$\{org.a2aproject.sdk.version}</version>
19+
</dependency>
20+
21+
<!-- REST with automatic v1.0 + v0.3 routing -->
22+
<dependency>
23+
<groupId>org.a2aproject.sdk</groupId>
24+
<artifactId>a2a-java-sdk-reference-multiversion-rest</artifactId>
25+
<version>$\{org.a2aproject.sdk.version}</version>
26+
</dependency>
27+
```
28+
29+
## Server: Individual Compat Modules
30+
31+
```xml
32+
<!-- v0.3 JSON-RPC support -->
33+
<dependency>
34+
<groupId>org.a2aproject.sdk</groupId>
35+
<artifactId>a2a-java-sdk-compat-0.3-reference-jsonrpc</artifactId>
36+
<version>$\{org.a2aproject.sdk.version}</version>
37+
</dependency>
38+
39+
<!-- v0.3 REST support -->
40+
<dependency>
41+
<groupId>org.a2aproject.sdk</groupId>
42+
<artifactId>a2a-java-sdk-compat-0.3-reference-rest</artifactId>
43+
<version>$\{org.a2aproject.sdk.version}</version>
44+
</dependency>
45+
46+
<!-- v0.3 gRPC support -->
47+
<dependency>
48+
<groupId>org.a2aproject.sdk</groupId>
49+
<artifactId>a2a-java-sdk-compat-0.3-reference-grpc</artifactId>
50+
<version>$\{org.a2aproject.sdk.version}</version>
51+
</dependency>
52+
```
53+
54+
## How Version Routing Works
55+
56+
- **JSON-RPC and REST**: When serving multiple protocol versions, version routing inspects the `A2A-Version` HTTP header on each request. If the header is `"1.0"`, the request is routed to the v1.0 handler. If it is `"0.3"` or absent, the request is routed to the v0.3 handler.
57+
- **gRPC**: Version dispatch is implicit — v0.3 clients use the `a2a.v1` protobuf package and v1.0 clients use `lf.a2a.v1`, so requests are routed to the correct service automatically.
58+
- **Agent card**: When both v1.0 and v0.3 are enabled, the v1.0 `AgentCard` takes precedence and is served at `/.well-known/agent-card.json`. The v0.3 `AgentCard_v0_3` is ignored. If only v0.3 is enabled, the v0.3 agent card is used. If only v1.0 is enabled, the v1.0 agent card is used as-is.
59+
60+
## Making the v1.0 Agent Card Compatible with v0.3 Clients
61+
62+
When serving both protocol versions, you need to ensure the v1.0 agent card contains fields that v0.3 clients expect. Existing v0.3 client implementations (in any language) look for `url`, `preferredTransport`, and `additionalInterfaces` with `transport`/`url` entries — fields that don't exist in the v1.0 format by default.
63+
64+
To make your v1.0 `AgentCard` parsable by v0.3 clients, set these fields on the builder:
65+
66+
```java
67+
AgentCard card = AgentCard.builder()
68+
.name("My Agent")
69+
// ... other v1.0 fields ...
70+
.supportedInterfaces(List.of(
71+
new AgentInterface("jsonrpc", "http://localhost:9999")))
72+
// v0.3 backward-compatibility fields:
73+
.url("http://localhost:9999")
74+
.preferredTransport("jsonrpc")
75+
.additionalInterfaces(List.of(
76+
new Legacy_0_3_AgentInterface("jsonrpc", "http://localhost:9999")))
77+
.build();
78+
```
79+
80+
The two interface lists serve different clients:
81+
82+
- `supportedInterfaces` — used by **v1.0 clients** to discover endpoints (uses `AgentInterface` with `protocolBinding`/`url`/`tenant` fields)
83+
- `additionalInterfaces` — used by **v0.3 clients** to discover endpoints (uses `Legacy_0_3_AgentInterface` with v0.3 field names: `transport`/`url`)
84+
- `url` and `preferredTransport` — top-level fields that v0.3 clients use to discover the primary endpoint
85+
86+
## Push Notification Behavior
87+
88+
Push notification payloads are automatically formatted to match the protocol version used when the push notification configuration was registered. When a v0.3 client registers a push notification configuration (via any transport), the server records the protocol version alongside the configuration. When a notification is later sent to that webhook, the payload is formatted as a v0.3 Task object. Configurations registered by v1.0 clients receive v1.0 `StreamResponse` payloads as usual. This happens transparently — no additional configuration is needed beyond adding the compat reference module.
89+
90+
## Client: Communicating with v0.3 Agents
91+
92+
Use `Client_v0_3` to communicate with agents that only support protocol v0.3:
93+
94+
```xml
95+
<dependency>
96+
<groupId>org.a2aproject.sdk</groupId>
97+
<artifactId>a2a-java-sdk-compat-0.3-client</artifactId>
98+
<version>$\{org.a2aproject.sdk.version}</version>
99+
</dependency>
100+
<dependency>
101+
<groupId>org.a2aproject.sdk</groupId>
102+
<artifactId>a2a-java-sdk-compat-0.3-client-transport-jsonrpc</artifactId>
103+
<version>$\{org.a2aproject.sdk.version}</version>
104+
</dependency>
105+
```
106+
107+
gRPC and REST transports are also available:
108+
- `a2a-java-sdk-compat-0.3-client-transport-grpc`
109+
- `a2a-java-sdk-compat-0.3-client-transport-rest`
110+
111+
```java
112+
AgentCard card = A2ACardResolver.builder().baseUrl("http://localhost:1234")
113+
.build().getAgentCard();
114+
115+
AgentInterface v03Interface = card.supportedInterfaces().stream()
116+
.filter(i -> A2AProtocol_v0_3.PROTOCOL_VERSION.equals(i.protocolVersion()))
117+
.findFirst().orElseThrow();
118+
119+
Client_v0_3 client = ClientBuilder_v0_3.forUrl(v03Interface.url())
120+
.withTransport(JSONRPCTransport_v0_3.class, new JSONRPCTransportConfigBuilder_v0_3())
121+
.build();
122+
```
123+
124+
**Note:** `Client_v0_3` exposes only operations available in protocol v0.3. For example, `listTasks()` is not available (it was added in v1.0). Return types use v0.3 domain objects from the `org.a2aproject.sdk.compat03.spec` package.

0 commit comments

Comments
 (0)