Agent-to-Agent (A2A) Protocol

The Agent-to-Agent (A2A) Protocol is an open standard that allows autonomous AI agents from different runtimes, organizations, and ecosystems to discover, communicate, and collaborate with one another. HazelJS provides a first-class implementation of the A2A specification, ensuring your agents are ready for the decentralized AI future.

Quick Reference

Purpose: Standardized inter-agent communication, discovery, and task delegation.
When to use: Use A2A when your HazelJS agent needs to call another agent (even one not built with HazelJS) or when you want your agent to be discoverable by external orchestrators.
Key concepts: AgentCard, Task Lifecycle, JSON-RPC, /.well-known/agent.json.
Primary Spec: Google A2A Protocol (HazelJS follows this spec).

Why A2A?

Most AI agents today are isolated. An "Agentic" ecosystem requires agents to behave like services in a microservices architecture. A2A provides the "Service Discovery" and "REST API" standards specifically tailored for LLM reasoning loops.

Feature	Without A2A	With A2A
Discovery	Hardcoded URLs	Standard `/.well-known/agent.json`
Communication	Proprietary JSON formats	Standard `A2AMessage` shapes
Task Tracking	Custom polling logic	Standardized `submitted` → `working` → `completed` states
Interoperability	Locked into one framework	Cross-framework collaboration (e.g., HazelJS talking to LangGraph)

🏗️ Architecture

graph LR
  A["Orchestrator Agent"] -->|"1. Discover"| B["/.well-known/agent.json"]
  A -->|"2. tasks/send"| C["A2A Server"]
  C -->|"3. Execute"| D["HazelJS Agent"]
  D -->|"4. Callback/Update"| A
  style A fill:#3b82f6,color:#fff
  style C fill:#6366f1,color:#fff
  style B fill:#10b981,color:#fff

1. Discovery: The Agent Card

The entry point for any A2A agent is the Agent Card. This is a JSON document that describes the agent's identity, capabilities, and the skills it offers.

HazelJS AgentCardBuilder

HazelJS makes it easy to generate standard-compliant cards from your agent instances.

import { AgentCardBuilder } from '@hazeljs/agent';

const card = new AgentCardBuilder()
  .setName('FinancialAnalyzer')
  .setDescription('Analyzes stock market trends and generates reports.')
  .setVersion('1.0.0')
  .addSkill({
    id: 'stock-analysis',
    name: 'Real-time Stock Analysis',
    description: 'Get deep insights into ticker symbols.',
    tags: ['finance', 'stocks']
  })
  .addCapability('streaming', true)
  .setProvider('Hazel Labs', 'https://hazeljs.ai')
  .build();

2. Communication: Tasks and Messages

In A2A, all work is modeled as a Task. You don't just "call a function"; you "send a task" and track its progress.

Message Structure

Messages consist of Parts (Text, File, or Data).

// A2A Message format
{
  "role": "agent",
  "parts": [
    { "type": "text", "text": "I have analyzed the portfolio." },
    { "type": "data", "data": { "riskScore": 0.82 } }
  ]
}

Task States

A2A defines a strict state machine for task execution:

submitted: Agent has received the request.
working: Agent is currently reasoning or executing tools.
input-required: Agent needs more info (Human-in-the-loop).
completed: Task finished successfully with results.
failed: An error occurred.

3. Implementation in HazelJS

The @hazeljs/agent package includes a built-in A2AServer to expose your agents via the protocol automatically.

import { A2AServer, AgentExecutor } from '@hazeljs/agent';

const executor = new AgentExecutor(myAgent);
const a2aServer = new A2AServer({
  executor,
  baseUrl: 'https://api.myagent.com/a2a',
  card: myAgentCard
});

// Start the A2A server (over HTTP/JSON-RPC)
a2aServer.listen(3000);

Core JSON-RPC Methods

HazelJS implements the standard A2A JSON-RPC 2.0 interface:

tasks/send: Initiate a new task.
tasks/get: Poll for status and artifacts.
tasks/cancel: Stop a running task.

🛡️ Security & Authentication

A2A supports multiple authentication schemes. HazelJS allows you to mount A2A servers behind standard middleware (like @hazeljs/auth) while advertising the required schemes in the Agent Card.

const card = new AgentCardBuilder()
  .setAuthentication({
    schemes: ['Bearer', 'HmacV1'],
    credentials: 'API Key required in Authorization header'
  })
  .build();

Agent Package – The core runtime for A2A execution.
MCP Package – Contrast between A2A (high-level agents) and MCP (low-level tools).
Observability – Tracing A2A calls across different agents.

For the full specification details, visit the Official Google A2A Site.