a2aproject/a2a-js

A2A JavaScript SDK – 是什麼

@a2a-js/sdk 是 Agent-to-Agent (A2A) 協定 的官方 TypeScript/JavaScript 客戶端程式庫。此協定讓自主的「代理」能透過網路公開功能（例如，電影搜尋機器人、長時間執行的資料處理工作），並被其他軟體發現與驅動。SDK 讓你能在單一套件中撰寫 A2A 伺服器（代理）與 A2A 客戶端（呼叫這些代理的應用程式）。

核心功能

功能	提供的能力
三種傳輸方式	JSON-RPC、HTTP + JSON/REST 與 gRPC（僅 Node）—— 全部共用相同的 `DefaultRequestHandler`，因此可同時透過多種協定公開同一個代理。
v1.0 協定實作	完全實作 A2A 規格 v1.0（訊息格式、任務生命週期、推送通知、認證、擴充）。
向後相容層	可選支援舊版 v0.3 對等端，讓 v1.0 伺服器能與舊版客戶端（反之亦然）通訊，方便遷移期間使用。
伺服器端輔助工具	`AgentExecutor`（你的業務邏輯）、`ExecutionEventBus`（發布任務、狀態、工件事件）、Express 與 gRPC 用的傳輸適配器、推送通知實作、JWT/Bearer 認證中間件。
客戶端輔助工具	`ClientFactory`（從代理卡或 URL 建構與傳輸無關的客戶端）、每次呼叫的 `RequestOptions`（標頭、取消訊號、上下文）、`CallInterceptor` API（用於記錄、追蹤或自訂擴充）。
代理卡簽章	產生與驗證 JWS 簽章代理卡的工具，以及用於信任驗證的 JWKS 處理。
可擴充	協定擴充可透過代理卡宣告，並透過 `A2A-Extensions` 標頭激活；SDK 提供裝飾器鉤子以修改輸出事件。

典型工作流程

定義代理 – 實作一個 AgentExecutor，接收 RequestContext，並向 ExecutionEventBus 發布 Message、Task、狀態與工件事件。
建立伺服器 – 實例化 DefaultRequestHandler 並掛載一個或多個傳輸適配器（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 導向微服務架構的堅實基礎。