npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@a2a-js/sdk

v1.1.0

Published

Server & Client SDK for Agent2Agent protocol

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

ishymkoishymkoherczynherczynswapydapyswapydapygoogle-wombotgoogle-wombotkcthota-gkcthota-g

Keywords

Readme

A2A JavaScript SDK

License npm

@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.
  • 🔌 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:

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:

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:

npm install @grpc/grpc-js @bufbuild/protobuf

Compatibility

This SDK implements the A2A Protocol Specification v1.0.0.

| 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.

Documentation

A2A Protocol Specification (v1.0.0): https://a2a-protocol.org/v1.0.0/specification/

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/:

Samples

End-to-end runnable examples live under src/samples. Each sample directory has its own README.md with run instructions.

| Sample | What it shows | | :------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------- | | agents/sample-agent | Minimal streaming agent: task lifecycle (submitted → working → artifact → completed) over JSON-RPC. | | agents/movie-agent | Realistic agent backed by Genkit + the TMDB API. | | agents/multi-transport-agent | Single agent exposed over JSON-RPC, HTTP+JSON/REST, and gRPC simultaneously. | | agents/cancellable-agent | Implements cancelTask to support user-initiated cancellation of in-flight tasks. | | agents/push-notification-agent | Long-running agent that POSTs task updates to a client-provided webhook (server + webhook + client). | | agents/verify-signing | Client-side verification of signed agent cards (JWS + JWKS). | | authentication | Server-side Bearer/JWT authentication using Passport, including a UserBuilder that propagates the authenticated user into the agent context. | | extensions | A2A protocol extension implemented as an AgentExecutor decorator that adds metadata to outgoing events. | | client/interceptors | Client CallInterceptors for header injection and request timing, plus per-call AbortSignal.timeout(...). | | cli.ts | Multi-transport interactive CLI client (JSON-RPC / REST / gRPC) with --auth / --svc-param header injection. | | 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 | 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:

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 sample).

Reference samples: sample-agent, multi-transport-agent, cancellable-agent, push-notification-agent.

Clients

Use ClientFactory 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, RestTransportFactory, and GrpcTransportFactory (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, 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 and the sample-agent / 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 and the 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 and the push-notification-agent sample (which includes a runnable webhook receiver).

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 and the AuthenticationHandler interface, which automatically attach Authorization headers and retry on 401/403 responses.

See the client/interceptors sample for header injection + per-call AbortSignal.timeout(...), and the 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 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 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 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 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, and the compat-v1-server / 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.

Contributing

See CONTRIBUTING.md for contribution guidelines.