a2aproject/a2a-js

A2A JavaScript SDK – What it is

@a2a-js/sdk is the official TypeScript/JavaScript client library for the Agent‑to‑Agent (A2A) Protocol. The protocol lets autonomous “agents” expose capabilities (e.g., a movie‑search bot, a long‑running data‑processing task) over a network and be discovered and driven by other software. The SDK lets you write A2A servers (the agents) and A2A clients (applications that call those agents) in a single package.

Core capabilities

Feature	What it gives you
Three transports	JSON‑RPC, HTTP + JSON/REST, and gRPC (Node‑only) – all share the same `DefaultRequestHandler` so you can expose the same agent over multiple protocols simultaneously.
v1.0 protocol implementation	Fully implements the A2A Specification v1.0 (message formats, task lifecycle, push notifications, authentication, extensions).
Backward‑compatibility layer	Opt‑in support for legacy v0.3 peers, allowing a v1.0 server to talk to older clients (and vice‑versa) during migration.
Server side helpers	`AgentExecutor` (your business logic), `ExecutionEventBus` (publish task, status, artifact events), transport adapters for Express and gRPC, push‑notification plumbing, and JWT/Bearer authentication middleware.
Client side helpers	`ClientFactory` that builds a transport‑agnostic client from an agent card or URL, per‑call `RequestOptions` (headers, abort signals, context), `CallInterceptor` API for logging, tracing, or custom extensions.
Agent card signing	Utilities to generate and verify JWS‑signed agent cards, plus JWKS handling for trust verification.
Extensible	Protocol extensions can be advertised in the agent card and activated via the `A2A-Extensions` header; the SDK provides decorator hooks to modify outgoing events.

Typical workflow

Define an agent – implement an AgentExecutor that receives a RequestContext and publishes Message, Task, status, and artifact events to the ExecutionEventBus.
Create a server – instantiate DefaultRequestHandler and mount one or more transport adapters (jsonRpcHandler, restHandler, grpcService). Optionally add authentication middleware, push‑notification store, or signing hooks.
Expose the agent card – a JSON document describing the agent’s capabilities, supported transports, and (optionally) a JWS signature.
Consume the agent – on the client side, use ClientFactory.createFromUrl (or createFromAgentCard) to obtain a Client. Call methods like sendMessage, sendMessageStream, createTask, cancelTask, etc.
Handle streaming & cancellation – long‑running tasks emit a stream of events; the client iterates an AsyncGenerator. Implement cancelTask in the executor to respect user‑initiated aborts.
Optional push notifications – for tasks that can’t keep a live stream open, configure a webhook URL via taskPushNotificationConfig; the server will POST updates.

Sample projects shipped with the SDK

Sample	Demonstrates
`sample-agent`	Minimal streaming agent (JSON‑RPC).
`movie-agent`	Real‑world agent using Genkit + TMDB API.
`multi-transport-agent`	Same agent exposed over JSON‑RPC, REST, and gRPC at once.
`cancellable-agent`	Implementation of `cancelTask`.
`push-notification-agent`	Webhook‑based push notifications.
`authentication`	Express middleware + Passport JWT auth, propagating a `User` into the executor.
`extensions`	Decorator that adds custom metadata via the extensions mechanism.
`verify-signing`	Client‑side verification of signed agent cards.
`cli.ts`	Interactive command‑line client that can talk to any transport and inject auth headers.
`compat‑v1‑server / compat‑v1‑client`	End‑to‑end demo of v1.0 server/client with the optional v0.3 compatibility layer.

Installation & quick start

# Core SDK
npm install @a2a-js/sdk

# If you need the Express server integration
npm install express

# If you plan to use the gRPC transport (Node only)
npm install @grpc/grpc-js @bufbuild/protobuf

Then follow the src/samples README files for runnable examples.

Maturity & ecosystem

Version: v1.0.0 – marked as a stable release.
License: Apache 2.0 (permissive, commercial‑friendly).
Governance: Hosted under the google-a2a GitHub org, with a clear contribution guide and migration docs.
Interoperability: Works with any language that implements the A2A spec (e.g., the Python SDK a2a-python). The compatibility layer ensures gradual upgrades from the older v0.3 spec.

Who should use this?

Developers building autonomous agents (LLM‑backed bots, data pipelines, tool‑calling services) that need a standard, versioned protocol for discovery and execution.
Platform teams that want to expose internal AI services as network‑addressable agents with uniform authentication, streaming, and cancellation semantics.
Integrators needing a multi‑transport client that can talk to agents over HTTP, JSON‑RPC, or gRPC without rewriting code.
Researchers experimenting with protocol extensions or custom push‑notification flows.

Where to learn more

Specification: https://a2a-protocol.org/v1.0.0/specification/
Docs folder: docs/ in the repo (migration guide, compatibility guide).
Samples: src/samples/ – each with its own README and npm scripts.
Contribution guide: https://github.com/google-a2a/a2a-js/blob/main/CONTRIBUTING.md

TL;DR

The A2A JavaScript SDK is a production‑ready, type‑safe library for building and consuming agents that follow the open Agent‑to‑Agent protocol. It supports JSON‑RPC, REST, and gRPC transports, offers built‑in streaming, cancellation, push‑notification, authentication, and a compatibility layer for older protocol versions, making it a solid foundation for any modern AI‑oriented micro‑service architecture.