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 导向微服务架构的坚实基础。