Skip to content

Commit 2b4f72f

Browse files
kabirkabir
committed
Rework the TCK and add README
1 parent bedce8d commit 2b4f72f

File tree

2 files changed

+92
-31
lines changed

2 files changed

+92
-31
lines changed

‎README.md‎

Lines changed: 44 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,54 @@
11
# A2A Java SDK for Jakarta Servers
22

3-
This is the integration of the A2A Java SDK for use in Jakarta servers.
3+
This is the integration of the [A2A Java SDK](https://github.com/a2aproject/a2a-java) for use in Jakarta servers. It is currently tested on **WildFly**, but it should be usable in other compliant Jakarta servers such as Tomcat, Jetty, and OpenLiberty. For Quarkus, use the reference implementation in the [A2A Java SDK](https://github.com/a2aproject/a2a-java) project.
44

5-
It is currently tested on WildFly, but should be usable in other compliant Jakarta servers.
5+
For more information about the A2A protocol, see [here](https://github.com/a2aproject/a2a-spec).
66

7-
For more information about the A2A protocol, see [here](https://a2aproject.github.io/A2A/latest/).
8-
And for more information about the A2A Java SDK, see [here](https://github.com/a2aproject/a2a-java).
7+
## Getting Started
98

9+
To use the A2A Java SDK in your application, you will need to package it as a `.war` file. This can be done with your standard build tool.
1010

11+
### Packaging your application
1112

13+
The key to enabling A2A in your Java application is to correctly package it. Here are the general steps you need to follow:
1214

15+
1. **Create a standard `.war` archive:** Your project should be configured to produce a `.war` file. This is a standard format for web applications in Java and is supported by all major runtimes.
1316

17+
2. **Provide implementations for `AgentExecutor` and `AgentCard`:** The A2A SDK requires you to provide your own implementations of the `AgentExecutor` and `AgentCard` interfaces. These are the core components that define the behavior of your agent. You can find more information about them in the [A2A Java SDK documentation](https://github.com/a2aproject/a2a-java).
18+
19+
3. **Manage Dependencies:** Your `.war` file must contain all necessary libraries in the `/WEB-INF/lib` directory. However, some libraries may already be provided by the application server itself.
20+
21+
* **Bundling Dependencies:** For libraries not provided by the server, you must bundle them inside your `.war`.
22+
23+
* **Provided Dependencies:** To avoid conflicts and reduce the size of your archive, you should exclude libraries that your target runtime already provides. For example, **WildFly** includes the **Jackson** libraries, so you do not need to package them in your application. Check the documentation for your specific runtime (Tomcat, Jetty, OpenLiberty, etc.) to see which dependencies are provided.
24+
25+
### Example
26+
27+
The [tck/pom.xml](./tck/pom.xml) is a good example of how to package an A2A application. In this case, the application is deployed in WildFly, so the dependencies included in the `.war` are tailored to what WildFly provides.
28+
29+
In this case we have the following dependencies:
30+
31+
* `org.wildfly.extras.a2a:a2a-java-sdk-server-jakarta` - this is the main dependency which transitively pulls in all the dependencies from the A2A Java SDK project.
32+
* Since some of these dependencies are provided by WildFly already, we exclude those so they do not become part of the `.war`, in order to avoid inconsistencies.
33+
* `jakarta.ws.rs:jakarta.ws.rs-api` - this is not part of the dependencies brought in via `org.wildfly.extras.a2a:a2a-java-sdk-server-jakarta` but is needed to compile the TCK module. Since it is provided by WildFly, we make the scope `provided` so it is not included in the `.war`.
34+
* `io.github.a2asdk:a2a-tck-server` - this is the application, which contains the `AgentExecutor` and `AgentCard` implementations for the TCK. In your case, they will most likely be implemented in the project you use to create the `.war`.
35+
* In this case we exclude all transitive dependencies, since we are doing the main dependency management via the `org.wildfly.extras.a2a:a2a-java-sdk-server-jakarta` dependency.
36+
37+
## Running the TCK
38+
39+
The project includes a TCK (Technology Compatibility Kit) that you can use to test the integration with WildFly.
40+
41+
To run the TCK, build the full project
42+
```bash
43+
mvn clean install -DskipTests
44+
```
45+
46+
You now have a server provisioned with the `.war` deployed in the `tck/target/wildfly` folder.
47+
48+
We can start the server using the following command:
49+
50+
```bash
51+
./tck/target/wildfly/bin/standalone.sh
52+
```
53+
Once the server is up and running, run the TCK with the instructions in [a2aproject/a2a-tck](a2aproject/a2a-tck). Make sure you check out the correct tag of `a2aproject/a2a-tck` for the protocol version we are targeting.
1454

‎tck/pom.xml‎

Lines changed: 48 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -18,50 +18,71 @@
1818
<description>Java SDK for the Agent2Agent Protocol (A2A) - SDK - Jakarta - TCK - WildFly Jar</description>
1919

2020
<dependencies>
21+
<!--
22+
Dependencies needed to build the application.
23+
-->
2124
<dependency>
2225
<groupId>${project.groupId}</groupId>
23-
<artifactId>a2a-java-sdk-server-jakarta-wildfly</artifactId>
26+
<artifactId>a2a-java-sdk-server-jakarta</artifactId>
2427
<version>${project.version}</version>
2528
<exclusions>
29+
<!--
30+
Exclude these transitive dependencies since we are deploying the TCK in WildFly,
31+
where the server provides these dependencies.
32+
Other servlet containers/application servers may provide other things.
33+
-->
2634
<exclusion>
27-
<groupId>*</groupId>
35+
<groupId>com.fasterxml.jackson.core</groupId>
36+
<artifactId>*</artifactId>
37+
</exclusion>
38+
<exclusion>
39+
<groupId>com.fasterxml.jackson.datatype</groupId>
2840
<artifactId>*</artifactId>
2941
</exclusion>
42+
<exclusion>
43+
<groupId>jakarta.enterprise</groupId>
44+
<artifactId>jakarta.enterprise.cdi-api</artifactId>
45+
</exclusion>
46+
<exclusion>
47+
<groupId>jakarta.inject</groupId>
48+
<artifactId>jakarta.inject-api</artifactId>
49+
</exclusion>
3050
</exclusions>
3151
</dependency>
32-
<dependency>
33-
<groupId>io.github.a2asdk</groupId>
34-
<artifactId>a2a-java-sdk-spec</artifactId>
35-
<scope>provided</scope>
36-
</dependency>
37-
<dependency>
38-
<groupId>io.github.a2asdk</groupId>
39-
<artifactId>a2a-tck-server</artifactId>
40-
<exclusions>
41-
<exclusion>
42-
<groupId>*</groupId>
43-
<artifactId>*</artifactId>
44-
</exclusion>
45-
</exclusions>
46-
</dependency>
47-
<dependency>
48-
<groupId>jakarta.annotation</groupId>
49-
<artifactId>jakarta.annotation-api</artifactId>
50-
<scope>provided</scope>
51-
</dependency>
52-
<dependency>
53-
<groupId>jakarta.enterprise</groupId>
54-
<artifactId>jakarta.enterprise.cdi-api</artifactId>
55-
<scope>provided</scope>
56-
</dependency>
5752
<dependency>
5853
<groupId>jakarta.ws.rs</groupId>
5954
<artifactId>jakarta.ws.rs-api</artifactId>
6055
<scope>provided</scope>
6156
</dependency>
57+
58+
<!--
59+
Include the TCK server from the a2a-java project.
60+
This is the application we will be using, providing the AgentExecutor and the AgentCard.
61+
For your own applications you should not use this dependency, but rather provide your own.
62+
-->
63+
<dependency>
64+
<groupId>io.github.a2asdk</groupId>
65+
<artifactId>a2a-tck-server</artifactId>
66+
<exclusions>
67+
<!--
68+
Exclude all dependencies, since we are managing what is included in the jar in the
69+
org.wildfly.extras.a2a:ctId>a2a-java-sdk-server-jakarta dependency.
70+
-->
71+
<exclusion>
72+
<groupId>*</groupId>
73+
<artifactId>*</artifactId>
74+
</exclusion>
75+
</exclusions>
76+
</dependency>
6277
</dependencies>
6378
<build>
6479
<plugins>
80+
<!--
81+
WildFly specific plugin to provision a WildFly server with the functionality required to
82+
run our .war file.
83+
It deploys the war renamed to 'ROOT.war' so that it is deployed under the root context, i.e. under '/'.
84+
By default, this will be under http://localhost:8080/.
85+
-->
6586
<plugin>
6687
<groupId>org.wildfly.plugins</groupId>
6788
<artifactId>wildfly-maven-plugin</artifactId>

0 commit comments

Comments
 (0)