a2a-js-dev

A2A JavaScript/TypeScript SDK Development Guide

Build standards-compliant agent-to-agent applications using the @a2a-js/sdk. This guide covers server agents, clients, task management, streaming, and all three transport bindings.

Quick Reference

# Install the SDK
npm install @a2a-js/sdk

# For Express server integration
npm install express

# For gRPC support (Node.js only)
npm install @grpc/grpc-js @bufbuild/protobuf

Import paths:

import { AgentCard, Message, Task, AGENT_CARD_PATH } from '@a2a-js/sdk';
import { AgentExecutor, DefaultRequestHandler, InMemoryTaskStore } from '@a2a-js/sdk/server';
import { agentCardHandler, jsonRpcHandler, restHandler, UserBuilder } from '@a2a-js/sdk/server/express';
import { ClientFactory } from '@a2a-js/sdk/client';
import { GrpcTransportFactory } from '@a2a-js/sdk/client/grpc';

The SDK implements A2A Protocol Specification v0.3.0.

---

Architecture Overview

An A2A application has two sides:

1. Server (Agent) — exposes capabilities via an Agent Card, handles incoming messages, manages tasks, and publishes events
2. Client (Consumer) — discovers agents, sends messages, tracks tasks, and consumes streaming updates

The protocol supports three transport bindings. Each transport provides the same operations — pick based on your deployment needs:

Transport	Client	Server	Notes
JSON-RPC	Yes	Yes	Default, works everywhere
HTTP+JSON/REST	Yes	Yes	RESTful, good for web clients
gRPC	Yes	Yes	Node.js only, high performance

---

Building an A2A Server

Step 1: Define the Agent Card

The Agent Card is the identity and capability declaration for your agent. Other agents discover it at /.well-known/agent-card.json.

import { AgentCard } from '@a2a-js/sdk';

const agentCard: AgentCard = {
  name: 'My Agent',
  description: 'Describe what your agent does clearly.',
  protocolVersion: '0.3.0',
  version: '1.0.0',
  url: 'http://localhost:4000/a2a/jsonrpc',
  skills: [
    {
      id: 'skill-id',
      name: 'Skill Name',
      description: 'What this skill does',
      tags: ['relevant', 'tags'],
    },
  ],
  capabilities: {
    pushNotifications: false,
    streaming: true,
  },
  defaultInputModes: ['text'],
  defaultOutputModes: ['text'],
  additionalInterfaces: [
    { url: 'http://localhost:4000/a2a/jsonrpc', transport: 'JSONRPC' },
    { url: 'http://localhost:4000/a2a/rest', transport: 'HTTP+JSON' },
  ],
};