A2A Java SDK 1.0.0.Alpha1 - 1.0仕様への対応
By
A2A Java SDK 1.0.0.Alpha1 のリリースを発表できることを嬉しく思います。このリリースは、今後の1.0バージョンの Agent2Agent (A2A) プロトコル仕様 に対応する重要なマイルストーンとなります。なお、仕様自体はまだ最終決定段階にあるため、最終的な1.0バージョンまでにいくつかの微妙な変更がある可能性があります。
A2Aプロトコルは、AIエージェント間の標準化された通信を可能にし、エージェントが機能を検出し、タスクを委任し、シームレスに連携できるようにします。このSDKは、A2Aエコシステムに参加するエージェントとクライアントの両方を構築するための堅牢なJava実装を提供します。
1.0が重要である理由
A2A仕様のバージョン1.0への移行は、実験段階から製品対応への移行を示します。仕様が成熟するにつれて、当社は技術的負債を整理し、実装を近代化し、将来にわたって役立つパターンを確立する機会を得ました。
このリリースには破壊的な変更が含まれています。 1.0が仕様の最初の「正式な」リリースであるため、当社は0.3.xシリーズとの後方互換性を維持しないという意図的な決定をしました。これにより、レガシーパターンを引き継ぐことなく、強固な基盤の上に構築できます。
主な変更点
1. 仕様への対応
SDKは現在、プロトコルバージョン 1.0 を実装し、最新の a2a.proto 定義に対応しています。主な仕様変更は以下のとおりです。
-
AgentCardの進化:
AgentCardは、個別のurl、preferredTransport、additionalInterfacesフィールドの代わりに、supportedInterfacesリストを使用するようになりました。これにより、複数のプロトコルバインディングを宣伝するための、よりクリーンで柔軟な方法が提供されます。 -
種類識別子の削除: 1.0仕様では、
kindフィールドを型識別子として廃止し、プロトコルを簡素化しました。 -
エラーハンドリングの改善: エラークラスは、1.0仕様のエラーモデルに合うように再設計されました。
2. モダンJava: レコードへの標準化
spec モジュール全体が、Javaレコードを継続的に使用するように近代化されました。以前は、ドメインモデル全体で従来のクラスとレコードが混在していました。現在、すべてのドメインクラスは不変性と簡潔さのためにレコードを活用し、すべてのゲッターは同じ命名パターンに従います。
// Before (0.3.x): Mix of classes and records with inconsistent patterns
public class AgentCard { // Some were classes
private final String name;
public String getName() { return name; } // JavaBean-style getters
}
public record AgentSkill(String id, String name, ...) { } // Some were already records
// Accessor: skill.name() without 'get' prefix
// After (1.0.x): Consistent records throughout
public record AgentCard(
String name,
String description,
AgentProvider provider,
String version,
List<AgentInterface> supportedInterfaces,
String protocolVersion) {
public static final String CURRENT_PROTOCOL_VERSION = "1.0";
}
public record AgentSkill(String id, String name, String description, ...) { }
// Uniform accessor pattern throughout: card.name(), skill.name()この標準化により、混乱が解消され、ボイラープレートが削減されるとともに、よりクリーンで保守しやすいAPIが提供されます。
A2A Java SDKは、過去数ヶ月にわたるJSpecifyアノテーションの段階的な採用を通じて、型安全性と **null安全** において大幅な改善がみられました。この取り組みは、コード品質に対するプロジェクトのコミットメントと、コンパイル時におけるNullPointerExceptionの防止を示しています。
静的ファクトリーメソッドを使用したビルダーパターン
すべてのビルダーは、パブリックコンストラクターの代わりに静的ファクトリーメソッドを使用するようになりました。これにより、カプセル化が向上し、最新のJavaのベストプラクティスに従うことができます。
// Before (0.3.x): Public builder constructor
AgentCard card = new AgentCard.Builder()
.name("My Agent")
.description("Does things")
.build();
// After (1.0.x): Static factory method
AgentCard card = AgentCard.builder() (1)
.name("My Agent")
.description("Does things")
.version("1.0.0")
.capabilities(AgentCapabilities.builder() (2)
.streaming(true)
.pushNotifications(false)
.build())
.defaultInputModes(List.of("text"))
.defaultOutputModes(List.of("text"))
.skills(List.of(
AgentSkill.builder() (3)
.id("weather_query")
.name("Weather Queries")
.description("Get current weather")
.build()
))
.supportedInterfaces(List.of(
new AgentInterface("JSONRPC", "http://localhost:9999")
))
.protocolVersion(AgentCard.CURRENT_PROTOCOL_VERSION)
.build();| 1 | AgentCard.builder() がビルダーを作成します — コンストラクターは現在プライベートです |
| 2 | ネストされたビルダーも静的ファクトリーメソッドを使用します |
| 3 | すべての仕様クラスは、このパターンを一貫して踏襲しています |
ビルダーコンストラクターは、宣言クラスで現在プライベートであり、SDK全体で静的ファクトリーメソッドパターンの使用を強制しています。
3. Protocol Buffersを信頼できる唯一の情報源として
Jacksonへの依存を排除し、プロトコルバッファ (protobuf) をドメインモデルの信頼できる唯一の情報源として確立しました。アーキテクチャは次のとおりです。
-
Protobuf定義 は
a2a.protoでワイヤーフォーマットを定義します -
Javaレコード は
specモジュールでSDKのAPIを提供します -
MapStructマッパー は変換を処理し、protobufと仕様クラスの同期が外れた場合にコンパイルエラーを発生させます
-
Gson はJSON-RPCトランスポートのJSONシリアライゼーションを処理します
これにより、すべてのトランスポートで型安全性、プロトコルの信頼できる唯一の情報源、およびシリアライゼーションアノテーションでドメインクラスを煩雑にすることなく、ワイヤーフォーマットとAPIのクリーンな分離が提供されます。
4. 部品表 (BOM)
依存関係管理を簡素化するためにMaven BOMを導入しました。
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.github.a2asdk</groupId>
<artifactId>a2a-java-sdk-bom</artifactId>
<version>1.0.0.Alpha1</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>3つのBOMが利用可能です。
-
a2a-java-sdk-bom: コアSDKおよびクライアントライブラリ -
a2a-java-extras-bom: オプションの拡張機能 (JpaDatabaseTaskStore および -PushNotificationStore、レプリケートされたQueueManager、Vert.X HTTPクライアント) -
a2a-java-reference-bom: Quarkusリファレンス実装
これにより、複数のSDKモジュールとその依存関係を使用する際のバージョン管理の悩みを解消します。
破壊的な変更の概要
0.3.xから移行する場合、主な破壊的な変更点は次のとおりです。
-
AgentCard構造:
url+preferredTransportをsupportedInterfacesリストに置き換える -
ビルダーパターン:
new AgentCard.Builder()の代わりにAgentCard.builder()を使用する — すべての仕様クラスに適用されます -
プロトコルバージョン:
AgentCard.CURRENT_PROTOCOL_VERSION(現在"1.0") に更新する -
フィールド名の変更:
supportsAuthenticatedExtendedCard→supportsExtendedAgentCard -
ゲッターの命名: レコードは
card.getName()の代わりにcard.name()を使用します -
パッケージのクリーンアップ:
io.a2a.apecパッケージはトリミングされました -
シリアル化: Jackson のアノテーションに依存していた場合は、Gson パターンに移行してください
はじめに
Maven を使用して、BOM と依存関係を追加します。
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.github.a2asdk</groupId>
<artifactId>a2a-java-sdk-bom</artifactId>
<version>1.0.0.Alpha1</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>io.github.a2asdk</groupId>
<artifactId>a2a-java-sdk-reference-jsonrpc</artifactId>
</dependency>
</dependencies>エージェントの作成には、AgentCard と AgentExecutor の生成が必要です。@PublicAgentCard 修飾子は、検出のエントリポイントとして機能する公開エージェントカードをマークします。これは、クライアントがエージェントを検出する際に取得するものです。また、追加の認証情報を含む拡張エージェントカードを提供することもできます。以下に最小限の例を示します。
@ApplicationScoped
public class MyAgentCardProducer {
@Produces @PublicAgentCard
public AgentCard agentCard() {
return AgentCard.builder()
.name("Weather Agent")
.description("Provides weather information")
.version("1.0.0")
.capabilities(AgentCapabilities.builder()
.streaming(true)
.pushNotifications(false)
.build())
.defaultInputModes(List.of("text"))
.defaultOutputModes(List.of("text"))
.skills(List.of(
AgentSkill.builder()
.id("weather_query")
.name("Weather Queries")
.description("Get current weather for a location")
.build()
))
.protocolVersion(AgentCard.CURRENT_PROTOCOL_VERSION)
.supportedInterfaces(List.of(
new AgentInterface("JSONRPC", "http://localhost:9999")
))
.build();
}
}
@ApplicationScoped
public class MyAgentExecutorProducer {
@Produces
public AgentExecutor agentExecutor() {
return new MyAgentExecutor();
}
private static class MyAgentExecutor implements AgentExecutor {
@Override
public void execute(RequestContext context, EventQueue eventQueue) {
TaskUpdater updater = new TaskUpdater(context, eventQueue);
updater.submit();
updater.startWork();
// Your agent logic here
String response = "Current weather: Sunny, 72°F";
updater.addArtifact(List.of(new TextPart(response, null)));
updater.complete();
}
}
}完全な例については、リポジトリ内の Hello World の例 を参照してください。
今後の展望
このアルファ版リリースにより、安定版の 1.0 SDK に大きく近づきました。今後のリリースにおける主要な焦点は以下のとおりです。
-
1.0 TCK テストスイートへの完全な準拠
-
実世界の利用状況に基づいたパフォーマンスの最適化
-
追加の例と統合ガイド
-
シームレスな Jakarta EE 統合のための WildFly Feature Pack
A2A 仕様自体も 1.0 リリースに向けて進化を続けています。私たちは仕様策定プロセスに積極的に参加しており、仕様が最終化されるにつれて SDK の調整を継続していきます。
