a2aproject/a2a-js

A2A JavaScript SDK – 何であるか

@a2a-js/sdk は Agent-to-Agent (A2A) プロトコル の公式 TypeScript/JavaScript クライアントライブラリ です。このプロトコルにより、自律的な「エージェント」がネットワーク上で機能（例：映画検索ボット、長時間実行のデータ処理タスク）を公開し、他のソフトウェアによって検出・制御できるようになります。SDK を使用することで、A2A サーバー（エージェント）と A2A クライアント（エージェントを呼び出すアプリケーション）を1つのパッケージで開発できます。

コア機能

機能	何を提供するか
3つのトランスポート	JSON-RPC、HTTP + JSON/REST、gRPC（Nodeのみ）— すべて同じ `DefaultRequestHandler` を共有しており、同じエージェントを複数のプロトコルで同時に公開できます。
v1.0プロトコル実装	A2A Specification v1.0（メッセージフォーマット、タスクライフサイクル、プッシュ通知、認証、拡張機能）を完全に実装。
後方互換性レイヤー	オプションで旧バージョン v0.3 のピアに対応。v1.0サーバーが古いクライアントと通信可能（逆も同様）で、移行期間中に利用可能。
サーバーサイドヘルパー	`AgentExecutor`（ビジネスロジック）、`ExecutionEventBus`（タスク、ステータス、アーティファクトイベントの発行）、ExpressおよびgRPC用のトランスポートアダプター、プッシュ通知の実装、JWT/Bearer認証ミドルウェア。
クライアントサイドヘルパー	`ClientFactory`（エージェントカードまたはURLからトランスポート非依存クライアントを構築）、各呼び出し用の `RequestOptions`（ヘッダー、キャンセルシグナル、コンテキスト）、`CallInterceptor` API（ログ、トレーシング、カスタム拡張）。
エージェントカード署名	JWS署名付きエージェントカードの生成・検証ユーティリティ、信頼検証用のJWKS処理。
拡張可能	エージェントカードで拡張機能を宣伝し、`A2A-Extensions` ヘッダーで有効化可能。SDKは出力イベントを変更するためのデコレータフックを提供。

一般的なワークフロー

エージェントの定義 – RequestContext を受け取り、ExecutionEventBus に Message、Task、ステータス、アーティファクトイベントを発行する AgentExecutor を実装。
サーバーの作成 – DefaultRequestHandler をインスタンス化し、1つ以上のトランスポートアダプター（jsonRpcHandler、restHandler、grpcService）をマウント。オプションで認証ミドルウェア、プッシュ通知ストア、署名フックを追加。
エージェントカードの公開 – エージェントの機能、サポートするトランスポート、（オプションで）JWS署名を記述したJSONドキュメント。
エージェントの利用 – クライアント側で ClientFactory.createFromUrl（または createFromAgentCard）を使用して Client を取得。sendMessage、sendMessageStream、createTask、cancelTask などのメソッドを呼び出す。
ストリーミングとキャンセルの処理 – 長時間実行タスクはイベントストリームを発行。クライアントは AsyncGenerator をイテレート。エグゼキュータで cancelTask を実装して、ユーザーによるキャンセルを尊重。
オプションのプッシュ通知 – 長時間のストリームを維持できないタスクには、taskPushNotificationConfig でWebhook URLを設定。サーバーは更新をPOSTで送信。

SDKに同梱されるサンプルプロジェクト

サンプル	機能を示す
`sample-agent`	最小限のストリーミングエージェント（JSON-RPC）。
`movie-agent`	Genkit + TMDB API を使用する実世界エージェント。
`multi-transport-agent`	同じエージェントを JSON-RPC、REST、gRPC で同時に公開。
`cancellable-agent`	`cancelTask` の実装。
`push-notification-agent`	Webhookベースのプッシュ通知。
`authentication`	Expressミドルウェア + Passport JWT認証、`User` をエグゼキュータに伝搬。
`extensions`	拡張メカニズムを介してカスタムメタデータを追加するデコレータ。
`verify-signing`	クライアント側での署名付きエージェントカードの検証。
`cli.ts`	任意のトランスポートに対応する対話型コマンドラインクライアント。認証ヘッダーを注入可能。
`compat-v1-server / compat-v1-client`	v1.0サーバー/クライアントのエンドツーエンドデモ。オプションのv0.3互換性レイヤー付き。

インストールとクイックスタート

# コアSDK
npm install @a2a-js/sdk

# Expressサーバー統合が必要な場合
npm install express

# gRPCトランスポートを使用する場合（Nodeのみ）
npm install @grpc/grpc-js @bufbuild/protobuf

その後、src/samples のREADMEファイルに従って実行可能な例を試してください。

成熟度とエコシステム

バージョン: v1.0.0 – ステーブルリリースとしてマーク。
ライセンス: Apache 2.0（許容性が高く、商用利用に適している）。
ガバナンス: google-a2a GitHub組織下でホスト。明確な貢献ガイドと移行ドキュメントあり。
相互運用性: A2A仕様を実装する任意の言語と動作可能（例：Python SDK a2a-python）。互換性レイヤーにより、古いv0.3仕様からの段階的アップグレードが可能。

どの人にとって適しているか？

自律エージェントを開発する開発者（LLMバックエンドのボット、データパイプライン、ツール呼び出しサービス）で、発見・実行に標準化されたバージョン付きプロトコルが必要な場合。
プラットフォームチーム：内部AIサービスをネットワークアドレス可能なエージェントとして公開し、一貫した認証、ストリーミング、キャンセルのセマンティクスを提供したい場合。
統合担当者：HTTP、JSON-RPC、gRPCのいずれかでエージェントと通信できるマルチトランスポートクライアントが必要な場合。
研究者：プロトコル拡張やカスタムプッシュ通知フローを実験したい場合。

詳細情報の入手先

仕様書: https://a2a-protocol.org/v1.0.0/specification/
ドキュメントフォルダ: リポジトリ内の docs/（移行ガイド、互換性ガイド）。
サンプル: src/samples/ – 各サンプルに独自のREADMEとnpmスクリプトあり。
貢献ガイド: https://github.com/google-a2a/a2a-js/blob/main/CONTRIBUTING.md

TL;DR

A2A JavaScript SDK は、オープンな Agent-to-Agentプロトコル を遵守するエージェントの構築・利用に向けた本番環境対応、型安全なライブラリです。JSON-RPC、REST、gRPCトランスポートをサポートし、組み込みのストリーミング、キャンセル、プッシュ通知、認証、および旧バージョンとの互換性レイヤーを備えており、現代のAI指向マイクロサービスアーキテクチャの堅実な基盤となります。