@a2a-js/sdk

@a2a-js/sdk is the official JavaScript and TypeScript implementation of the Agent2Agent (A2A) Protocol, a spec for letting autonomous agents discover each other’s capabilities and exchange tasks over a common wire format. The package bundles both halves of that exchange: an AgentExecutor-based server stack for exposing an agent’s capabilities, and a ClientFactory-driven client stack for discovering and driving remote agents, all from one npm install.

A single DefaultRequestHandler backs three interchangeable wire transports — JSON-RPC, HTTP+JSON/REST, and gRPC (Node-only) — so a server can expose one agent over multiple protocols simultaneously, and the SDK ships an opt-in v0.3 compatibility layer so v1.0 deployments can keep talking to peers still running the previous protocol version during a staged migration.

What You Get

• A DefaultRequestHandler that wires task routing, cancellation, and push notifications across all three supported transports from one instance
• JSON-RPC, HTTP+JSON/REST, and gRPC transport adapters (client and server) built on the same AgentCard-driven negotiation
• A ClientFactory that resolves an agent’s preferred transport automatically from its published AgentCard, plus manual factories per transport
• Streaming primitives (SSE-based ExecutionEventBus / AsyncGenerator) for task, status, and artifact update events
• Built-in push-notification store/sender pair and agent-card signature generation/verification helpers

Common Use Cases

• Exposing an existing agentic application as an A2A-compliant server other agents can discover and call
• Building a client that discovers an agent’s AgentCard and drives it over whichever transport it prefers
• Migrating an A2A v0.3 deployment to v1.0 while keeping interoperability with peers still on v0.3
• Implementing long-running agent tasks with webhook-based push notifications instead of held-open streams

Under The Hood

Architecture The project splits into modular entry points (src/index.ts, src/client, src/server, src/compat/v0_3) for tree-shaking and separation of concerns. Server-side, DefaultRequestHandler (src/server/request_handler/default_request_handler.ts) is the shared orchestration core — it composes an injected AgentExecutor, TaskStore, ExecutionEventBusManager, and PushNotificationStore/Sender, and every transport adapter (jsonRpcHandler, restHandler, grpcService) is built directly against its interface, so all three protocols stay behaviorally consistent. Client-side, ClientFactory decouples callers from the wire format via a shared TransportFactory contract implemented separately for JSON-RPC, REST, and gRPC, selecting one based on the server’s published AgentCard. Data flows from AgentExecutor publishing events onto an ExecutionEventBus, through an ExecutionEventQueue and ResultManager, out to whichever transport adapter serializes it — a clean pipeline, though any change to DefaultRequestHandler’s contract ripples through every transport and sample.

Tech Stack TypeScript targeting Node.js 20+, published as a dual ESM/CJS package via tsup. Protocol types are code-generated from a shared protobuf definition (buf generate, src/types/pb), with @bufbuild/protobuf and @grpc/grpc-js as optional peer dependencies gating the gRPC transport, and express as an optional peer dependency for the server/express entry point. jose handles JWS/JWKS agent-card signing and verification. Testing runs on vitest, including a Cloudflare Workers pool config for edge-safe transports and a separate integration-test config; linting combines ESLint 9’s flat config with typescript-eslint and tsc --noEmit gates on both source and test trees.

Code Quality The test/ tree mirrors src/ (client, server, compat, integration) with dozens of spec files — errors.spec.ts and e2e.spec.ts alone run to tens of kilobytes — using vitest idiomatically with nested describe/it blocks per method. Error handling is structured rather than ad hoc: src/errors/{base,json_rpc,rest,grpc}.ts define a typed A2AError hierarchy (TaskNotFoundError, UnsupportedOperationError, etc.) plus a centralized extractErrorMessage helper, and tsconfig.base.json enables noImplicitAny and useUnknownInCatchVariables. CI is extensive: separate unit, integration, lint, build, and TCK-compatibility workflows run against the official A2A test-compatibility kit, well beyond what most SDKs run.

What Makes It Unique Most protocol SDKs commit to a single wire format; this one runs JSON-RPC, HTTP+JSON/REST, and gRPC off one shared request handler and lets the client auto-negotiate the transport from the server’s advertised AgentCard rather than hardcoding it. It also ships a first-class v0.3-to-v1.0 compatibility shim so protocol upgrades don’t force a hard cutover across a fleet of agents, and a signed-AgentCard mechanism (JWS/JWKS) for verifying an agent’s identity before trusting its capabilities — a concern most agent SDKs leave unaddressed.