# @a2a-js/sdk > Server & Client SDK for Agent2Agent protocol Latest version **1.2.0** (published 2026-09-18) · Apache-2.0 license · 0 weekly downloads ## Install ```sh npm install @a2a-js/sdk pnpm add @a2a-js/sdk yarn add @a2a-js/sdk bun add @a2a-js/sdk ``` ## Health **Score 75/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 1.2.0 | | Published | 2026-09-18 | | First published | 2025-06-14 | | Weekly downloads | 0 | | License | Apache-2.0 | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Node | >=20 | | Dependencies | 1 | | Unpacked size | 4.2 MB | | Known vulnerabilities | 0 | | Install scripts | no | | Provenance | attested (GitHub Actions) | | GitHub stars | 614 | | Maintainers | ishymko, herczyn, swapydapy, google-wombot, kcthota-g | ## Links - npm: https://www.npmjs.com/package/@a2a-js/sdk - Repository: https://github.com/a2aproject/a2a-js - Homepage: https://github.com/a2aproject/a2a-js#readme - Issues: https://github.com/a2aproject/a2a-js/issues - npm.io page: https://npm.io/package/@a2a-js/sdk ## Dependencies (1) - [jose](https://npm.io/package/jose.md) ^6.2.3 ## Recent versions - 1.2.0 (latest) — 2026-09-18 - 1.1.0 — 2026-08-26 - 1.0.1 — 2026-07-28 - 1.0.0 — 2026-07-22 - 0.3.14 — 2026-07-09 - 1.0.0-beta.0 — 2026-07-01 - 1.0.0-alpha.0 — 2026-05-11 - 0.3.13 — 2026-03-16 - 0.3.12 — 2026-03-10 - 0.3.11 — 2026-03-10 - 0.3.10 — 2026-02-03 - 0.3.9 — 2026-01-21 - 0.3.8 — 2026-01-15 - 0.3.7 — 2025-12-17 - 0.3.6 — 2025-12-10 - … 11 more at https://npm.io/package/@a2a-js/sdk/versions ## README # A2A JavaScript SDK [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) [![npm](https://img.shields.io/npm/v/@a2a-js/sdk.svg)](https://www.npmjs.com/package/@a2a-js/sdk)

Agent2Agent Protocol Logo

A JavaScript library that helps run agentic applications as A2AServers following the Agent2Agent (A2A) Protocol.

`@a2a-js/sdk` is the official TypeScript / JavaScript SDK for the A2A Protocol. Use it to build A2A **servers** (agents exposing their capabilities over the protocol) and A2A **clients** (applications discovering and driving those agents) — one package, three wire transports (JSON-RPC, HTTP+JSON/REST, gRPC), and an opt-in compatibility layer for v0.3 peers. - 🚀 **v1.0 stable release** implementing [A2A Protocol Specification v1.0](https://a2a-protocol.org/v1.0.0/specification/). - 🔌 **Three transports** — JSON-RPC, HTTP+JSON/REST, and gRPC (Node-only), all backed by a single `DefaultRequestHandler`. - 🔄 **v0.3 backward compatibility** as an opt-in layer so v1.0 deployments can interoperate with peers still on v0.3 during a staged migration. ## Installation You can install the A2A SDK using `npm`: ```bash npm install @a2a-js/sdk ``` ### For Server Usage If you plan to use the Express integration (imports from `@a2a-js/sdk/server/express`) for A2A server, you'll also need to install Express as it's a peer dependency: ```bash npm install express ``` ### For gRPC Usage If you plan to use the GRPC transport (imports from `@a2a-js/sdk/server/grpc`, `@a2a-js/sdk/client/grpc`, or the gRPC-specific error helpers in `@a2a-js/sdk/errors/grpc`), you must install the required peer dependencies: ```bash npm install @grpc/grpc-js @bufbuild/protobuf ``` --- ## Compatibility This SDK implements the A2A Protocol Specification [`v1.0.0`](https://a2a-protocol.org/v1.0.0/specification). | Transport | Client | Server | | :---------------------- | :----: | :----: | | **JSON-RPC** | ✅ | ✅ | | **HTTP+JSON/REST** | ✅ | ✅ | | **GRPC** (Node.js only) | ✅ | ✅ | Upgrading from `0.3.x`? Read the [v0.3 → v1.0 migration guide](docs/migration-guide.md). ## Documentation **A2A Protocol Specification (v1.0.0):** The protocol specification is the source of truth for message formats, task lifecycle states, transport bindings, push notifications, extensions, and authentication. This SDK provides a TypeScript implementation of that surface; when in doubt about behavior, consult the specification. SDK-specific guides live under [`docs/`](docs/): - [Migration guide (`v0.3` → `v1.0`)](docs/migration-guide.md) - [v0.3 compatibility guide](docs/compatibility-v0_3.md) ## Samples End-to-end runnable examples live under [`src/samples`](https://github.com/a2aproject/a2a-js/tree/main/src/samples). Each sample directory has its own `README.md` with run instructions. | Sample | What it shows | | :------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------- | | [`agents/sample-agent`](src/samples/agents/sample-agent/) | Minimal streaming agent: task lifecycle (`submitted` → `working` → artifact → `completed`) over JSON-RPC. | | [`agents/movie-agent`](src/samples/agents/movie-agent/) | Realistic agent backed by Genkit + the TMDB API. | | [`agents/multi-transport-agent`](src/samples/agents/multi-transport-agent/) | Single agent exposed over JSON-RPC, HTTP+JSON/REST, and gRPC simultaneously. | | [`agents/cancellable-agent`](src/samples/agents/cancellable-agent/) | Implements `cancelTask` to support user-initiated cancellation of in-flight tasks. | | [`agents/push-notification-agent`](src/samples/agents/push-notification-agent/) | Long-running agent that POSTs task updates to a client-provided webhook (server + webhook + client). | | [`agents/verify-signing`](src/samples/agents/verify-signing/) | Client-side verification of signed agent cards (JWS + JWKS). | | [`authentication`](src/samples/authentication/) | Server-side Bearer/JWT authentication using Passport, including a `UserBuilder` that propagates the authenticated user into the agent context. | | [`extensions`](src/samples/extensions/) | A2A protocol extension implemented as an `AgentExecutor` decorator that adds metadata to outgoing events. | | [`client/interceptors`](src/samples/client/interceptors/) | Client `CallInterceptor`s for header injection and request timing, plus per-call `AbortSignal.timeout(...)`. | | [`cli.ts`](src/samples/cli.ts) | Multi-transport interactive CLI client (JSON-RPC / REST / gRPC) with `--auth` / `--svc-param` header injection. | | [`agents/compat-v1-server`](src/samples/agents/compat-v1-server/) | v1.0-native server with `legacyCompat: { enabled: true }` on every transport — JSON-RPC, REST, gRPC, agent card, and push notifications. | | [`agents/compat-v1-client`](src/samples/agents/compat-v1-client/) | v1.0-native client driving both the compat-aware server above and a hand-rolled mock v0.3 server in-process; pairs with `compat-v1-server`. | To run a sample, install dependencies inside `src/samples` and use the provided npm scripts: ```bash cd src/samples npm install npm run agents:sample-agent # see src/samples/package.json for the full list ``` ## Capability overview This section is a quick orientation. For wire-format details and full semantics, follow the spec links and the sample `README.md` files. ### Servers The server side is built around three pieces: - **`AgentExecutor`** — your business logic. Receives a `RequestContext` and publishes `Message`, `Task`, status, and artifact events to an `ExecutionEventBus`. - **`DefaultRequestHandler`** — orchestrates message routing, task storage, cancellation, and push notifications. - **Transport adapters** — `jsonRpcHandler` and `restHandler` from `@a2a-js/sdk/server/express`, plus `grpcService` from `@a2a-js/sdk/server/grpc`. All three can be mounted against the same `DefaultRequestHandler` instance (see the [multi-transport-agent](src/samples/agents/multi-transport-agent/) sample). Reference samples: [`sample-agent`](src/samples/agents/sample-agent/), [`multi-transport-agent`](src/samples/agents/multi-transport-agent/), [`cancellable-agent`](src/samples/agents/cancellable-agent/), [`push-notification-agent`](src/samples/agents/push-notification-agent/). ### Clients Use [`ClientFactory`](src/client/factory.ts) to build a `Client`: - `factory.createFromUrl(baseUrl, path?)` fetches the agent card and selects the best matching transport based on `supportedInterfaces` and `preferredTransports`. - `factory.createFromAgentCard(card)` works from an in-memory `AgentCard`. Available transport factories: [`JsonRpcTransportFactory`](src/client/transports/json_rpc_transport.ts), [`RestTransportFactory`](src/client/transports/rest_transport.ts), and [`GrpcTransportFactory`](src/client/transports/grpc/grpc_transport.ts) (Node.js only, exported from `@a2a-js/sdk/client/grpc`). Each `Client` method (`sendMessage`, `sendMessageStream`, `getTask`, `cancelTask`, `createTaskPushNotificationConfig`, …) accepts a `RequestOptions` object that supports per-call `signal`, custom `serviceParameters` (HTTP headers), and `context`. Reference samples: [`cli.ts`](src/samples/cli.ts), [`client/interceptors`](src/samples/client/interceptors/). ### Streaming Long-running tasks publish a stream of `task`, `status-update`, and `artifact-update` events. On the server, publish events through the `ExecutionEventBus`. On the client, consume them by iterating `client.sendMessageStream(...)` (an `AsyncGenerator`). See the spec section [Streaming](https://a2a-protocol.org/v1.0.0/specification/#312-send-streaming-message) and the [`sample-agent`](src/samples/agents/sample-agent/) / [`movie-agent`](src/samples/agents/movie-agent/) samples. ### Task cancellation Implement `cancelTask(taskId, eventBus)` on your `AgentExecutor` and have your `execute` loop check for cancellation before each unit of work. Publish a final `TaskState.TASK_STATE_CANCELED` status update when aborting. See the spec section [`cancelTask`](https://a2a-protocol.org/v1.0.0/specification/#315-cancel-task) and the [`cancellable-agent`](src/samples/agents/cancellable-agent/) sample. ### Push notifications For long-running tasks where the client cannot keep an SSE / gRPC stream open, A2A supports webhook-based push notifications: 1. Declare `capabilities.pushNotifications: true` on your agent card. 2. Wire `InMemoryPushNotificationStore` and `DefaultPushNotificationSender` into `DefaultRequestHandler` (or provide your own implementations). 3. Clients send a `taskPushNotificationConfig` (URL + optional token) with their `MessageSendParams`. The server POSTs every task / status / artifact event to that URL. See the spec section [Push Notifications](https://a2a-protocol.org/v1.0.0/specification/#43-push-notification-objects) and the [`push-notification-agent`](src/samples/agents/push-notification-agent/) sample (which includes a runnable webhook receiver). ### Custom event bus and task store `TaskStore`, `ExecutionEventBus` and `ExecutionEventBusManager` are all constructor-injected into `DefaultRequestHandler`, so you can back them with a database, a cache, or a message broker instead of the in-process defaults. One caveat applies to a bus that does not deliver events synchronously. When the agent executor returns, the handler decides whether to tear that task's bus down from the last state it saw delivered, so a bus that batches or persists events before handing them to subscribers has shown the handler nothing by that point and its bus is released too early. Such a bus should implement the optional `settleByTaskId` on its manager, which is offered that decision first: return `true` to take ownership of the bus and settle it from your own drain, or `false` to let the handler apply its usual policy for that call. See the doc comments on [`ExecutionEventBusManager`](src/server/events/execution_event_bus_manager.ts) for the full contract, and `test/integration/delayed_event_bus.spec.ts` for a worked example against a bus that withholds every batch. ### Client customization `@a2a-js/sdk/client` exposes a transport-agnostic `CallInterceptor` interface with `before` / `after` hooks for every method. Common uses: - Request logging and metrics. - Header injection (request IDs, distributed-tracing headers, custom routing). - A2A protocol extensions (modifying `serviceParameters`). For authentication, the SDK includes [`createAuthenticatingFetchWithRetry`](src/client/auth-handler.ts) and the `AuthenticationHandler` interface, which automatically attach Authorization headers and retry on 401/403 responses. See the [`client/interceptors`](src/samples/client/interceptors/) sample for header injection + per-call `AbortSignal.timeout(...)`, and the [`cli.ts`](src/samples/cli.ts) sample for passing `--auth "Bearer $TOKEN"` as per-call `serviceParameters`. ### Authentication (server side) Server-side authentication is implemented as Express middleware plus a `UserBuilder` that converts the authenticated request into an A2A `User` object available to your `AgentExecutor` via the `RequestContext`. See the [`authentication`](src/samples/authentication/) sample for a complete Bearer/JWT example using Passport. ### Protocol extensions Extensions are advertised via `capabilities.extensions` on the agent card and activated per-request through the `A2A-Extensions` HTTP header. They are implemented as `AgentExecutor` decorators that wrap the published events. See the [`extensions`](src/samples/extensions/) sample. ### Agent card signing Agent cards can be signed using JWS so clients can verify their authenticity via a published JWKS. The SDK exposes `verifyAgentCardSignature`, `canonicalizeAgentCard`, and a server-side `AgentCardSignatureGenerator` hook on `DefaultRequestHandler`. See the [`agents/verify-signing`](src/samples/agents/verify-signing/) sample. ### v0.3 backward compatibility A v1.0 server can transparently accept v0.3 clients (and a v1.0 client can transparently talk to v0.3 servers) by opting into the compat layer with `legacyCompat: { enabled: true }` on the relevant transport / handler. The compat surface is shipped as six subpath exports off `@a2a-js/sdk`: | Subpath | Use it for | | :--------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `@a2a-js/sdk/compat/v0_3` | v0.3 protocol constants and method-name translators. Workers-safe — no Node-only peer deps. | | `@a2a-js/sdk/compat/v0_3/server` | Framework-agnostic transport handlers (`LegacyJsonRpcTransportHandler`, `LegacyRestTransportHandler`), push-notification factory (`createLegacyAwarePushNotificationSender`), serializer, and `LegacyA2AError`. Workers-safe. | | `@a2a-js/sdk/compat/v0_3/server/express` | Express routers (`legacyAgentCardRouter`, `legacyRestRouter`) that wrap the handlers above with the v0.3 well-known agent-card and REST endpoint paths. | | `@a2a-js/sdk/compat/v0_3/server/grpc` | `legacyGrpcService` + `LegacyA2AService`. Register alongside the v1.0 `grpcService` on the same gRPC `Server`. | | `@a2a-js/sdk/compat/v0_3/client` | `LegacyJsonRpcTransport`, `LegacyRestTransport`, and the `isLegacyAgentCard` / `parseLegacyAgentCard` helpers. Workers-safe. | | `@a2a-js/sdk/compat/v0_3/client/grpc` | `LegacyGrpcTransport`, instantiated by the v1.0 `GrpcTransportFactory` when the matched `AgentInterface.protocolVersion` falls in `[0.3, 1.0)`. | See the end-user [v0.3 compatibility guide](docs/compatibility-v0_3.md) for opt-in mechanics and caveats (dropped fields, defaults, unavailable methods like `ListTasks`, push-notification routing, per-interface v0.3 advertisement). For the architecture-level walkthrough — translators, version negotiation under §3.6.2, push-notification wire-version routing — see [`src/compat/v0_3/README.md`](src/compat/v0_3/README.md), and the [`compat-v1-server`](src/samples/agents/compat-v1-server/) / [`compat-v1-client`](src/samples/agents/compat-v1-client/) samples for an end-to-end demonstration across every transport. ## License This project is licensed under the terms of the [Apache 2.0 License](LICENSE). ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines. --- _Source: https://npm.io/package/@a2a-js/sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._