Antigravity × A2A Protocol: Complete Implementation Guide for Scalable Multi-Agent Systems

# Initialize the project
mkdir a2a-agent-system && cd a2a-agent-system
npm init -y
 
# Install AgentKit 2.0 and dependencies
npm install @google/agentkit@^2.0 @google/genai zod hono
 
# Dev tooling
npm install -D typescript @types/node tsx nodemon

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "esModuleInterop": true
  }
}

# A2A Agent Development Rules
 
- Every agent must serve /.well-known/agent-card.json
- Task IDs must be UUID v4
- Error responses must follow the A2A JSONRPC error format
- Streaming must be implemented with SSE (Server-Sent Events)
- Authentication must use Bearer Token (JWT)

// src/agent-card.ts
import { z } from "zod";
 
const AgentSkillSchema = z.object({
  id: z.string(),
  name: z.string(),
  description: z.string(),
  tags: z.array(z.string()),
  inputModes: z.array(z.enum(["text", "file", "data"])),
  outputModes: z.array(z.enum(["text", "file", "data"])),
  examples: z.array(z.object({
    name: z.string(),
    description: z.string(),
    input: z.record(z.unknown()),
  })).optional(),
});
 
export const CODE_REVIEW_AGENT_CARD = {
  name: "CodeReviewAgent",
  description: "Reviews code and suggests quality improvements",
  url: process.env.AGENT_BASE_URL ?? "http://localhost:3001",
  version: "1.2.0",
  documentationUrl: "https://your-docs.example.com/agents/code-review",
  capabilities: {
    streaming: true,
    pushNotifications: true,
    stateTransitionHistory: true,
  },
  authentication: {
    schemes: ["Bearer"],
  },
  defaultInputMode: "text",
  defaultOutputMode: "text",
  skills: [
    {
      id: "review-code",
      name: "Code Review",
      description: "Reviews TypeScript/JavaScript/Python code quality and suggests improvements",
      tags: ["code-review", "quality", "typescript", "python"],
      inputModes: ["text", "file"],
      outputModes: ["text", "data"],
      examples: [
        {
          name: "TypeScript Function Review",
          description: "Review error handling in an async function",
          input: { message: "Please improve the error handling in this function" },
        },
      ],
    },
    {
      id: "security-scan",
      name: "Security Scan",
      description: "Detects common security vulnerabilities (XSS, SQL injection, etc.)",
      tags: ["security", "vulnerability", "owasp"],
      inputModes: ["text", "file"],
      outputModes: ["text", "data"],
    },
  ],
} satisfies AgentCard;
 
export type AgentCard = {
  name: string;
  description: string;
  url: string;
  version: string;
  documentationUrl?: string;
  capabilities: {
    streaming: boolean;
    pushNotifications: boolean;
    stateTransitionHistory: boolean;
  };
  authentication: { schemes: string[] };
  defaultInputMode: string;
  defaultOutputMode: string;
  skills: z.infer<typeof AgentSkillSchema>[];
};

// src/server.ts
import { Hono } from "hono";
import { cors } from "hono/cors";
import { bearerAuth } from "hono/bearer-auth";
import { CODE_REVIEW_AGENT_CARD } from "./agent-card";
import { taskRouter } from "./routes/tasks";
 
const app = new Hono();
 
app.use("*", cors({
  origin: "*",
  allowMethods: ["GET", "POST"],
  allowHeaders: ["Content-Type", "Authorization"],
}));
 
// Agent Card — no auth required
app.get("/.well-known/agent-card.json", (c) => {
  return c.json(CODE_REVIEW_AGENT_CARD);
});
 
// Task endpoints — auth required
app.use("/tasks/*", bearerAuth({ token: process.env.AGENT_TOKEN! }));
app.route("/tasks", taskRouter);
 
export default app;

// src/routes/tasks.ts
import { Hono } from "hono";
import { z } from "zod";
import { GoogleGenerativeAI } from "@google/genai";
import { v4 as uuidv4 } from "uuid";
 
const taskRouter = new Hono();
const genai = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY!);
 
const SendTaskSchema = z.object({
  jsonrpc: z.literal("2.0"),
  id: z.string().or(z.number()),
  method: z.literal("tasks/send"),
  params: z.object({
    id: z.string().uuid(),
    message: z.object({
      role: z.literal("user"),
      parts: z.array(z.object({
        type: z.enum(["text", "file", "data"]),
        text: z.string().optional(),
      })),
    }),
    skillId: z.string().optional(),
  }),
});
 
taskRouter.post("/send", async (c) => {
  const body = await c.req.json();
  const parsed = SendTaskSchema.safeParse(body);
 
  if (!parsed.success) {
    return c.json({
      jsonrpc: "2.0",
      id: body.id ?? null,
      error: { code: -32600, message: "Invalid Request", data: parsed.error.flatten() },
    }, 400);
  }
 
  const { params } = parsed.data;
  const userMessage = params.message.parts
    .filter(p => p.type === "text")
    .map(p => p.text)
    .join("\n");
 
  try {
    const model = genai.getGenerativeModel({ model: "gemini-2.5-pro" });
    const result = await model.generateContent([{
      role: "user",
      parts: [{ text: `You are a senior code reviewer. Analyze the following code:\n\n${userMessage}` }],
    }]);
 
    const responseText = result.response.text();
 
    return c.json({
      jsonrpc: "2.0",
      id: parsed.data.id,
      result: {
        id: params.id,
        sessionId: uuidv4(),
        status: {
          state: "completed",
          message: {
            role: "agent",
            parts: [{ type: "text", text: responseText }],
          },
          timestamp: new Date().toISOString(),
        },
        artifacts: [{
          name: "review-result",
          description: "Code review output",
          parts: [{ type: "text", text: responseText }],
        }],
      },
    });
  } catch (error) {
    return c.json({
      jsonrpc: "2.0",
      id: parsed.data.id,
      error: {
        code: -32603,
        message: "Internal error",
        data: error instanceof Error ? error.message : "Unknown error",
      },
    }, 500);
  }
});
 
export { taskRouter };

taskRouter.post("/sendSubscribe", async (c) => {
  const body = await c.req.json();
  const taskId = body.params?.id ?? uuidv4();
 
  const stream = new ReadableStream({
    async start(controller) {
      const encoder = new TextEncoder();
 
      const sendEvent = (data: unknown) => {
        controller.enqueue(encoder.encode(`data: ${JSON.stringify(data)}\n\n`));
      };
 
      try {
        // Signal that work has started
        sendEvent({
          jsonrpc: "2.0",
          id: body.id,
          result: {
            id: taskId,
            status: {
              state: "working",
              message: { role: "agent", parts: [{ type: "text", text: "Analyzing code..." }] },
              timestamp: new Date().toISOString(),
            },
          },
        });
 
        const model = genai.getGenerativeModel({ model: "gemini-2.5-pro" });
        const userMessage = body.params?.message?.parts
          ?.filter((p: { type: string }) => p.type === "text")
          .map((p: { text: string }) => p.text)
          .join("\n") ?? "";
 
        const streamResult = await model.generateContentStream([{
          role: "user",
          parts: [{ text: `Review this code:\n\n${userMessage}` }],
        }]);
 
        let chunkIndex = 0;
        for await (const chunk of streamResult.stream) {
          const chunkText = chunk.text();
          sendEvent({
            jsonrpc: "2.0",
            id: body.id,
            result: {
              id: taskId,
              status: { state: "working", timestamp: new Date().toISOString() },
              artifact: {
                name: "review-in-progress",
                index: chunkIndex++,
                append: chunkIndex > 1,
                lastChunk: false,
                parts: [{ type: "text", text: chunkText }],
              },
            },
          });
        }
 
        // Signal completion
        sendEvent({
          jsonrpc: "2.0",
          id: body.id,
          result: {
            id: taskId,
            status: { state: "completed", timestamp: new Date().toISOString() },
            artifact: {
              name: "review-complete",
              index: chunkIndex,
              lastChunk: true,
              parts: [{ type: "text", text: "" }],
            },
          },
        });
 
        controller.close();
      } catch (error) {
        sendEvent({
          jsonrpc: "2.0",
          id: body.id,
          error: { code: -32603, message: error instanceof Error ? error.message : "Stream error" },
        });
        controller.close();
      }
    },
  });
 
  return new Response(stream, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache",
      "Connection": "keep-alive",
    },
  });
});

// src/a2a-client.ts
export class A2AClient {
  private agentUrl: string;
  private token: string;
 
  constructor(agentUrl: string, token: string) {
    this.agentUrl = agentUrl.replace(/\/$/, "");
    this.token = token;
  }
 
  async getAgentCard() {
    const res = await fetch(`${this.agentUrl}/.well-known/agent-card.json`);
    if (!res.ok) throw new Error(`Agent card fetch failed: ${res.status}`);
    return res.json();
  }
 
  async sendTask(params: { taskId: string; message: string; skillId?: string }) {
    const body = {
      jsonrpc: "2.0",
      id: crypto.randomUUID(),
      method: "tasks/send",
      params: {
        id: params.taskId,
        message: { role: "user", parts: [{ type: "text", text: params.message }] },
        skillId: params.skillId,
      },
    };
 
    const res = await fetch(`${this.agentUrl}/tasks/send`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${this.token}`,
      },
      body: JSON.stringify(body),
    });
 
    if (!res.ok) throw new Error(`Task failed: ${res.status}`);
 
    const result = await res.json();
    if (result.error) throw new Error(`A2A Error ${result.error.code}: ${result.error.message}`);
 
    return result.result;
  }
 
  async *sendTaskStream(params: { taskId: string; message: string }): AsyncGenerator<unknown> {
    const body = {
      jsonrpc: "2.0",
      id: crypto.randomUUID(),
      method: "tasks/sendSubscribe",
      params: {
        id: params.taskId,
        message: { role: "user", parts: [{ type: "text", text: params.message }] },
      },
    };
 
    const res = await fetch(`${this.agentUrl}/tasks/sendSubscribe`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${this.token}`,
      },
      body: JSON.stringify(body),
    });
 
    if (!res.ok || !res.body) throw new Error("Stream init failed");
 
    const reader = res.body.getReader();
    const decoder = new TextDecoder();
    let buffer = "";
 
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
 
      buffer += decoder.decode(value, { stream: true });
      const lines = buffer.split("\n\n");
      buffer = lines.pop() ?? "";
 
      for (const line of lines) {
        if (line.startsWith("data: ")) yield JSON.parse(line.slice(6));
      }
    }
  }
}

// src/auth.ts
import { SignJWT, jwtVerify } from "jose";
 
const SECRET = new TextEncoder().encode(process.env.JWT_SECRET!);
 
export async function issueAgentToken(params: {
  issuerId: string;
  targetId: string;
  scopes: string[];
  expiresIn?: number;
}): Promise<string> {
  return new SignJWT({ iss: params.issuerId, aud: params.targetId, scopes: params.scopes })
    .setProtectedHeader({ alg: "HS256" })
    .setIssuedAt()
    .setExpirationTime(`${params.expiresIn ?? 3600}s`)
    .sign(SECRET);
}
 
export async function verifyAgentToken(
  token: string,
  requiredScope: string,
  audienceId: string
): Promise<{ issuerId: string; scopes: string[] }> {
  const { payload } = await jwtVerify(token, SECRET, { audience: audienceId });
  const scopes = (payload.scopes as string[]) ?? [];
 
  if (!scopes.includes(requiredScope)) {
    throw new Error(`Insufficient scope. Required: ${requiredScope}`);
  }
 
  return { issuerId: payload.iss as string, scopes };
}

// src/middleware/rate-limit.ts
import { MiddlewareHandler } from "hono";
 
const requestCounts = new Map<string, { count: number; resetAt: number }>();
 
export const rateLimitMiddleware = (
  maxRequests = 60,
  windowMs = 60_000
): MiddlewareHandler => {
  return async (c, next) => {
    const clientId = c.req.header("Authorization")?.slice(7) ?? "anonymous";
    const now = Date.now();
    const record = requestCounts.get(clientId);
 
    if (!record || now > record.resetAt) {
      requestCounts.set(clientId, { count: 1, resetAt: now + windowMs });
      c.header("X-RateLimit-Remaining", String(maxRequests - 1));
      return next();
    }
 
    if (record.count >= maxRequests) {
      return c.json({
        jsonrpc: "2.0",
        id: null,
        error: {
          code: -32000,
          message: "Rate limit exceeded",
          data: { retryAfter: Math.ceil((record.resetAt - now) / 1000) },
        },
      }, 429);
    }
 
    record.count++;
    c.header("X-RateLimit-Remaining", String(maxRequests - record.count));
    return next();
  };
};

"error": {
  "code": -32001,
  "message": "Task not found",
  "data": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "TASK_NOT_FOUND",
      "domain": "a2a-protocol.org",
      "metadata": { "taskId": "123" }
    }
  ]
}

// src/retry-client.ts
type RetryOptions = {
  maxAttempts?: number;
  initialDelayMs?: number;
  maxDelayMs?: number;
  retryableErrors?: number[];    // retryable A2A error codes
  retryOnNetworkError?: boolean; // retry dropped connections / timeouts
};
 
export async function withRetry<T>(fn: () => Promise<T>, options: RetryOptions = {}): Promise<T> {
  const {
    maxAttempts = 3,
    initialDelayMs = 500,
    maxDelayMs = 10_000,
    retryableErrors = [-32603],
    retryOnNetworkError = true,
  } = options;
 
  let lastError: Error | null = null;
 
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error instanceof Error ? error : new Error(String(error));
 
      if (!isRetryable(lastError, retryableErrors, retryOnNetworkError)) throw lastError;
 
      if (attempt < maxAttempts) {
        // Exponential backoff + jitter
        const delay = Math.min(
          initialDelayMs * Math.pow(2, attempt - 1) + Math.random() * 100,
          maxDelayMs
        );
        console.warn(`Attempt ${attempt}/${maxAttempts} failed. Retrying in ${Math.round(delay)}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      }
    }
  }
 
  throw lastError ?? new Error("Max retry attempts exceeded");
}
 
/** Only use the A2A code when we can actually read one. Never wave an unknown error through. */
function isRetryable(
  err: Error,
  retryableErrors: number[],
  retryOnNetworkError: boolean
): boolean {
  const match = err.message.match(/A2A Error (-?\d+):/);
  if (match) return retryableErrors.includes(Number(match[1]));
 
  // No code means this wasn't an A2A response at all: a dropped socket, an abort, or our own bug
  return retryOnNetworkError && isTransportError(err);
}
 
function isTransportError(err: Error): boolean {
  const name = err.name;
  return name === "TypeError" || name === "AbortError" || /fetch failed|ECONN|ETIMEDOUT/i.test(err.message);
}
 
// Usage — mint the task ID once, outside the retried call
const taskId = crypto.randomUUID();
const result = await withRetry(
  () => client.sendTask({ taskId, message: "Please review this code" }),
  { maxAttempts: 3, retryableErrors: [-32603, -32000] }
);

// src/worker.ts
import { Hono } from "hono";
import { CODE_REVIEW_AGENT_CARD } from "./agent-card";
import { taskRouter } from "./routes/tasks";
 
const app = new Hono<{ Bindings: Env }>();
 
app.get("/.well-known/agent-card.json", (c) => {
  const card = { ...CODE_REVIEW_AGENT_CARD, url: `https://${new URL(c.req.url).hostname}` };
  return c.json(card, 200, { "Cache-Control": "public, max-age=3600" });
});
 
app.route("/tasks", taskRouter);
 
export default app;

name = "code-review-agent"
main = "src/worker.ts"
compatibility_date = "2026-01-01"
compatibility_flags = ["nodejs_compat"]
 
[vars]
AGENT_BASE_URL = "https://code-review-agent.your-subdomain.workers.dev"
 
[[secrets]]
name = "GOOGLE_API_KEY"
 
[[secrets]]
name = "JWT_SECRET"
 
[[secrets]]
name = "AGENT_TOKEN"

wrangler secret put GOOGLE_API_KEY
wrangler secret put JWT_SECRET
wrangler secret put AGENT_TOKEN
wrangler deploy
 
# Verify the Agent Card is live
curl https://code-review-agent.your-subdomain.workers.dev/.well-known/agent-card.json | jq .

// src/orchestrator.ts
import { A2AClient } from "./a2a-client";
import { withRetry } from "./retry-client";
 
export async function runCodePipeline(sourceCode: string) {
  const reviewClient = new A2AClient(process.env.REVIEW_AGENT_URL!, process.env.REVIEW_AGENT_TOKEN!);
  const docClient = new A2AClient(process.env.DOC_AGENT_URL!, process.env.DOC_AGENT_TOKEN!);
 
  // Verify both agents are reachable before starting
  const [reviewCard, docCard] = await Promise.all([
    reviewClient.getAgentCard(),
    docClient.getAgentCard(),
  ]);
 
  console.log(`✓ ${reviewCard.name} (${reviewCard.version}) — online`);
  console.log(`✓ ${docCard.name} (${docCard.version}) — online`);
 
  // Run independent tasks in parallel to maximize throughput
  const [reviewResult, docResult] = await Promise.all([
    withRetry(() => reviewClient.sendTask({
      taskId: crypto.randomUUID(),
      message: `Review this code:\n\`\`\`typescript\n${sourceCode}\n\`\`\``,
      skillId: "review-code",
    })),
    withRetry(() => docClient.sendTask({
      taskId: crypto.randomUUID(),
      message: `Generate JSDoc comments and a README section for:\n\`\`\`typescript\n${sourceCode}\n\`\`\``,
    })),
  ]);
 
  return {
    review: reviewResult.artifacts?.[0]?.parts?.[0]?.text ?? "",
    documentation: docResult.artifacts?.[0]?.parts?.[0]?.text ?? "",
  };
}

- Independent agent tasks must be executed with Promise.all, never sequentially

// src/agent-registry.ts
type AgentRegistration = {
  url: string;
  token: string;
  card?: AgentCard;
  lastSeen: Date;
  healthy: boolean;
};
 
export class AgentRegistry {
  private agents = new Map<string, AgentRegistration>();
 
  register(name: string, url: string, token: string) {
    this.agents.set(name, { url, token, lastSeen: new Date(), healthy: true });
  }
 
  async resolve(name: string): Promise<{ url: string; token: string; card: AgentCard }> {
    const registration = this.agents.get(name);
    if (!registration) throw new Error(`Agent not registered: ${name}`);
    if (!registration.healthy) throw new Error(`Agent unhealthy: ${name}`);
 
    // Fetch and cache the Agent Card on first use
    if (!registration.card) {
      const res = await fetch(`${registration.url}/.well-known/agent-card.json`);
      registration.card = await res.json();
    }
 
    return { url: registration.url, token: registration.token, card: registration.card! };
  }
 
  /** Find agents that support a given skill ID */
  async findBySkill(skillId: string): Promise<string[]> {
    const matches: string[] = [];
 
    for (const [name, reg] of this.agents.entries()) {
      if (!reg.card) {
        try {
          const res = await fetch(`${reg.url}/.well-known/agent-card.json`);
          reg.card = await res.json();
        } catch {
          reg.healthy = false;
          continue;
        }
      }
      const hasSkill = reg.card?.skills?.some(s => s.id === skillId);
      if (hasSkill) matches.push(name);
    }
 
    return matches;
  }
 
  /** Periodic health check — mark unresponsive agents as unhealthy */
  async healthCheck() {
    const checks = Array.from(this.agents.entries()).map(async ([name, reg]) => {
      try {
        const controller = new AbortController();
        const timeout = setTimeout(() => controller.abort(), 5000);
        const res = await fetch(`${reg.url}/.well-known/agent-card.json`, {
          signal: controller.signal,
        });
        clearTimeout(timeout);
        reg.healthy = res.ok;
        reg.lastSeen = new Date();
      } catch {
        reg.healthy = false;
      }
      return { name, healthy: reg.healthy };
    });
 
    return Promise.all(checks);
  }
}
 
// Usage in orchestrator
const registry = new AgentRegistry();
registry.register("code-review", process.env.REVIEW_AGENT_URL!, process.env.REVIEW_AGENT_TOKEN!);
registry.register("documentation", process.env.DOC_AGENT_URL!, process.env.DOC_AGENT_TOKEN!);
registry.register("test-generator", process.env.TEST_AGENT_URL!, process.env.TEST_AGENT_TOKEN!);
 
// Dynamically route by skill
const reviewAgents = await registry.findBySkill("review-code");
console.log(`Found ${reviewAgents.length} agent(s) with review-code skill`);

// src/load-balancer.ts
export class RoundRobinBalancer {
  private counters = new Map<string, number>();
 
  next(candidates: string[]): string {
    if (candidates.length === 0) throw new Error("No candidates available");
    const key = candidates.join("|");
    const current = this.counters.get(key) ?? 0;
    const selected = candidates[current % candidates.length];
    this.counters.set(key, current + 1);
    return selected;
  }
}
 
// In the orchestrator: pick the least-busy agent for a skill
const balancer = new RoundRobinBalancer();
 
async function delegateToSkill(skillId: string, message: string) {
  const candidates = await registry.findBySkill(skillId);
  if (candidates.length === 0) throw new Error(`No agents available for skill: ${skillId}`);
 
  const agentName = balancer.next(candidates);
  const { url, token } = await registry.resolve(agentName);
  const client = new A2AClient(url, token);
 
  return client.sendTask({ taskId: crypto.randomUUID(), message, skillId });
}

type CardEntry = { card: AgentCard; etag: string | null; expiresAt: number };
const cardCache = new Map<string, CardEntry>();
 
/** Honors Cache-Control max-age; revalidates expired entries with If-None-Match */
export async function getCachedAgentCard(
  url: string,
  fallbackTtlMs = 3_600_000
): Promise<AgentCard> {
  const endpoint = `${url.replace(/\/$/, "")}/.well-known/agent-card.json`;
  const cached = cardCache.get(endpoint);
 
  // Still fresh: never touch the network
  if (cached && Date.now() < cached.expiresAt) return cached.card;
 
  const headers: Record<string, string> = {};
  if (cached?.etag) headers["If-None-Match"] = cached.etag;
 
  const res = await fetch(endpoint, { headers });
 
  // 304 carries no body — extend the copy we already hold
  if (res.status === 304 && cached) {
    cached.expiresAt = Date.now() + maxAgeMs(res, fallbackTtlMs);
    return cached.card;
  }
  if (!res.ok) {
    // A failed revalidation shouldn't take discovery down with it
    if (cached) return cached.card;
    throw new Error(`Agent card fetch failed: ${res.status}`);
  }
 
  const card = (await res.json()) as AgentCard;
  cardCache.set(endpoint, {
    card,
    etag: res.headers.get("etag"),
    expiresAt: Date.now() + maxAgeMs(res, fallbackTtlMs),
  });
  return card;
}
 
function maxAgeMs(res: Response, fallbackMs: number): number {
  const cc = res.headers.get("cache-control") ?? "";
  const m = cc.match(/max-age=(\d+)/);
  return m ? Number(m[1]) * 1000 : fallbackMs;
}