Skip to content
reaatech

@reaatech/a2a-reference-server

npm v0.2.0

A server framework that implements the A2A (Agent-to-Agent) protocol, providing Express 5 and Hono adapters that expose JSON-RPC 2.0 endpoints, SSE streaming, health checks, rate limiting, and push notifications for agent communication.

@reaatech/a2a-reference-server

A2A server framework with Express 5 and Hono adapters.

Quick Start

ts
import { createA2AExpressApp } from '@reaatech/a2a-reference-server';
 
const app = createA2AExpressApp({
  agentCard: { /* ... */ },
  executor: {
    async execute(context, eventBus) { /* your logic */ },
  },
});
 
app.listen(3000);

Features

Dual Adapters

ts
// Express
const app = createA2AExpressApp({ agentCard, executor });
 
// Hono (edge-compatible)
const app = createA2AHonoApp({ agentCard, executor });

Health Checks

ts
const app = createA2AExpressApp({
  agentCard,
  executor,
  healthChecks: [{ name: 'db', check: async () => ({ status: 'ok' }) }],
});
// GET /healthz, GET /readyz

Rate Limiting

ts
import { RateLimiter } from '@reaatech/a2a-reference-server';
 
const app = createA2AExpressApp({
  agentCard,
  executor,
  rateLimiter: new RateLimiter({ windowMs: 60_000, maxRequests: 100 }),
});

Push Notifications

ts
import { PushNotificationManager } from '@reaatech/a2a-reference-server';
 
const app = createA2AExpressApp({
  agentCard: { ...agentCard, capabilities: { pushNotifications: true } },
  executor,
  pushNotificationManager: new PushNotificationManager({ maxRetries: 3 }),
});

Extended Agent Card

ts
const app = createA2AExpressApp({
  agentCard,
  executor,
  extendedAgentCard: { customData: '...' },
});
// GET /.well-known/agent-card/extended
// RPC: tasks/extendedAgentCard

SSE via Redis Pub/Sub

ts
import { RedisSseCoordinator } from '@reaatech/a2a-reference-server';
import { Redis } from 'ioredis';
 
const coordinator = new RedisSseCoordinator({
  redis: new Redis(),
  connectOnInit: true, // auto-connects
});

Auth Integration

ts
const app = createA2AExpressApp({
  agentCard,
  executor,
  authStrategy: new JwtStrategy({ jwksUri: 'https://auth.example.com/jwks' }),
});

Server Options

OptionTypeDefaultDescription
agentCardAgentCardrequiredAgent discovery metadata
executorAgentExecutorrequiredYour agent logic
taskStoreTaskStoreInMemoryTaskStoreTask persistence
authStrategyAuthStrategynoneAuthentication
rateLimiterRateLimiternoneRequest rate limiting
extendedAgentCardRecord<string, unknown>noneExtended metadata
pushNotificationManagerPushNotificationManagerautoWebhook delivery
healthChecksHealthCheck[]noneCustom health probes
versionstringagentCard.versionVersion for health endpoint
trustProxyHeadersbooleanfalseDerive the rate-limit client IP from X-Forwarded-For (only enable behind a trusted proxy)

Endpoints

MethodPathDescription
GET/.well-known/agent.jsonAgent Card
GET/.well-known/agent-cardAgent Card
GET/.well-known/agent-card/extendedExtended Agent Card
GET/healthzHealth check
GET/readyzReadiness check
POST/JSON-RPC 2.0 endpoint
POST/tasks/sendSubscribeSSE streaming
GET/tasks/:taskId/subscribeSSE subscription