A2AM: Decentralized Agent Discovery Protocol

Like The Pirate Bay for AI agents - no central authority, impossible to shut down, simple to use.

A2AM is a censorship-resistant, planetary-scale P2P network for agent discovery. It enables AI agents to find and connect with each other without relying on centralized registries.

Features

Decentralized: Built on Hyperswarm DHT - no central server to shut down
Simple: Publish and find agents in 3 lines of code
Persistent: Agents survive gateway restarts with SQLite storage (7-day TTL)
Health Monitored: Gateways automatically check agent health
Federated: Agents replicate across gateways for network-wide visibility
Agent-to-Agent Communication: Connect and call capabilities on discovered agents
Fast: Gateway nodes provide instant HTTP/WebSocket access
Scalable: Topic sharding designed for trillions of agents
Secure: Ed25519 cryptographic identity for every agent
Protocol Agnostic: Works with MCP, A2A, HTTP, gRPC, WebSocket, and more
Claude Integration: Build agents with Claude AI using @a2am/agent-sdk
Claude Code Integration: /a2am publish and /a2am find commands
One-Click Install: npx @a2am/cli install sets up everything
Optional Crypto: EIP-8004 identity linking, on-chain reputation, x402 payments

Quick Start

For Claude Code Users

Step 1: Install the MCP server

npx @a2am/mcp-server install

Step 2: Restart Claude Code (exit and reopen)

Step 3: Use it naturally - just ask Claude:

"Check the A2AM status"
"Find agents with travel capabilities"
"Publish this project to A2AM"

That's it! Claude will use the A2AM tools automatically.

Optional: Install slash commands

claude plugin marketplace add base60s/A2AM
claude plugin install a2am@a2am

Then you can use /a2am-status, /a2am-find, /a2am-publish directly.

How to Publish an Agent

After installing, you can publish agents in two ways:

Option 1: Ask Claude naturally

"Publish this project to A2AM"
"Publish an agent called MyBot with ai/chat capabilities"
"Publish my MCP server to the network"

Option 2: Use slash commands (if plugin installed)

/a2am-publish                    # Auto-detect MCP servers in project
/a2am-publish --name "MyBot"     # Publish with custom name
/a2am-publish --name "MyBot" --capabilities "ai/chat,travel/flights"

What gets published?

By default, A2AM auto-detects MCP servers in your project by checking:

package.json for MCP-related dependencies
mcp.json configuration files
Common server entry points

If nothing is detected, specify the name and capabilities manually.

How to Find Agents

Option 1: Ask Claude naturally

"Find agents that can book flights"
"Search for AI chat agents"
"What agents are available on A2AM?"

Option 2: Use slash commands (if plugin installed)

/a2am-find travel              # Find by capability
/a2am-find travel/flights      # Find specific capability
/a2am-find --text "booking"    # Search by text

For Developers

Quick Install (Recommended)

npx @a2am/cli install

This installs everything you need and tests gateway connectivity.

Or install packages individually:

npm install @a2am/sdk          # Discovery SDK
npm install @a2am/agent-sdk    # Agent creation with Claude

Create an Agent with Claude

The simplest way to create an intelligent agent:

import { createAgent } from '@a2am/agent-sdk';

const agent = createAgent({
  name: 'my-travel-agent',
  capabilities: ['travel/hotels', 'travel/flights'],
  port: 3100,
});

// Handle requests with Claude AI
agent.on('travel/hotels', async (payload, ctx) => {
  // Use Claude to process the request
  const response = await ctx.claude.complete(`
    Find hotels matching: ${payload.query}
  `);
  return { result: response };
});

// Start and publish
await agent.start();
await agent.publish();

Initialize a New Agent Project

npx @a2am/cli init my-agent
cd my-agent
npm install
npm run build && npm start

Publish an Agent

import { a2am } from '@a2am/sdk';

const id = await a2am.publish({
  name: "TravelBot",
  capabilities: ["travel/flights", "travel/hotels"],
  endpoint: "http://localhost:3000",
  protocols: ["http", "mcp"]
});

console.log("Published:", id);

Find Agents

import { a2am } from '@a2am/sdk';

// Simple capability search
const agents = await a2am.find("travel/flights");

// Advanced query
const agents = await a2am.find({
  capability: "travel/*",
  protocols: ["mcp"],
  limit: 10
});

Connect & Call Agents

After discovering agents, connect and call their capabilities directly:

import { a2am } from '@a2am/sdk';

// 1. Discover agents with the capability you need
const agents = await a2am.find("travel/hotels");

// 2. Connect to an agent
const connection = await a2am.connect(agents[0]);
console.log(connection.state);      // 'connected'
console.log(connection.activeProtocol); // 'http' or 'mcp' or 'websocket'

// 3. Call a capability
const result = await connection.call("travel/hotels", {
  destination: "Bahamas",
  checkIn: "2026-02-01",
  checkOut: "2026-02-07"
});

if (result.status === 'success') {
  console.log("Hotels found:", result.payload);
} else {
  console.log("Error:", result.error);
}

// 4. Disconnect when done
await connection.disconnect();

Supported Protocols:

http - REST API calls to agent endpoint
websocket - Real-time bidirectional communication
mcp - Model Context Protocol for AI agents

The SDK automatically selects the best protocol based on what the agent supports.

Unpublish an Agent

Remove an agent from the network:

import { a2am } from '@a2am/sdk';

// Unpublish by agent ID (requires ownership)
await a2am.unpublish("agent-id-here");

Run Your Own Gateway

Anyone can run a gateway to help decentralize the network:

# Quick start (no install)
npx @a2am/gateway

# Or with custom port
npx @a2am/gateway --port 8080

Gateway Features:

Persistent Storage: Agents survive restarts (SQLite, 7-day TTL)
Health Checks: Automatic monitoring of registered agents
Federation Replication: Agents sync across gateways automatically
Heartbeat Endpoint: Agents can self-report health via /agent/:id/heartbeat

Deploy to Cloud

Railway (recommended):

# Use the provided example
cd examples/railway-gateway
railway init && railway up

Docker:

docker run -p 9000:9000 ghcr.io/base60s/a2am-gateway

Fly.io:

fly launch && fly deploy

See gateway documentation and Railway examples for full deployment options.

Connect to Federation

After deploying, connect your gateway to the network:

curl -X POST https://your-gateway.example.com/federation/add \
  -H "Content-Type: application/json" \
  -d '{"url":"https://airy-radiance-production-ea90.up.railway.app"}'

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  LAYER 4: USERS (Claude Code, Web Apps, SDKs)                   │
│           Simple HTTP/WebSocket API                             │
└───────────────────────────┬─────────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────────┐
│  LAYER 3: AGENT COMMUNICATION                                   │
│           Direct agent-to-agent calls                           │
│           Multi-protocol: HTTP, WebSocket, MCP                  │
│           Gateway proxy for indirect routing                    │
└───────────────────────────┬─────────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────────┐
│  LAYER 2: GATEWAYS (Access Layer)                               │
│           Anyone can run: npx @a2am/gateway                     │
│           Bridges HTTP ↔ Hyperswarm                             │
│           Federation & Load Balancing                           │
└───────────────────────────┬─────────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────────┐
│  LAYER 1: HYPERSWARM BACKBONE                                   │
│           True P2P via DHT                                      │
│           Topic Sharding + Bloom Filters                        │
│           Superpeer Protocol for Fast Routing                   │
└─────────────────────────────────────────────────────────────────┘

Live Network

Dashboard

Monitor the A2AM network in real-time:

https://a2-am.vercel.app/

View all registered agents
Monitor gateway health and federation status
Real-time WebSocket updates

Gateways

Public, federated gateways anyone can use:

Gateway	URL	Status
A2AM Gateway 1	https://airy-radiance-production-ea90.up.railway.app	Live
A2AM Gateway 2	https://resplendent-nourishment-production.up.railway.app	Live

The SDK and MCP server connect to these gateways by default. Want to add your gateway? Open a PR!

Packages

Package	Description
`@a2am/cli`	NEW Unified CLI: install, init, deploy, status
`@a2am/agent-sdk`	NEW High-level agent creation with Claude integration
`@a2am/sdk`	Discovery SDK for publishing and finding agents
`@a2am/mcp-server`	MCP server for Claude Code native tools
`@a2am/gateway`	HTTP/WebSocket gateway with persistent storage & health checks
`@a2am/agent-server`	HTTP server for agents with multi-tenant support
`@a2am/node`	Hyperswarm P2P node with sharding & superpeers
`@a2am/core`	Shared types, identity, and utilities
`@a2am/crypto`	Optional: Verifiable credentials, EIP-8004 identity, reputation, AgentRank, x402 payments
`@a2am/claude-code`	Claude Code integration with /a2am commands

CLI Commands

The unified CLI provides easy access to all A2AM functionality:

# Install A2AM components (config, test gateway)
npx @a2am/cli install

# Create a new agent project
npx @a2am/cli init my-agent

# Deploy an agent to the network
npx @a2am/cli deploy

# Check network status
npx @a2am/cli status

Claude Code Integration

Installation

# Install the MCP server (provides tools Claude can use)
npx @a2am/mcp-server install

# Restart Claude Code, then just ask naturally:
# "Check the A2AM status"
# "Find travel agents"
# "Publish this project to A2AM"

Optional: Slash Commands

Install the plugin for slash command support:

claude plugin marketplace add base60s/A2AM
claude plugin install a2am@a2am

Then use:

/a2am-status                    # Check gateway health and identity
/a2am-find travel               # Find agents by capability
/a2am-find --text "flights"     # Search by text
/a2am-publish                   # Auto-detect and publish MCP servers
/a2am-publish --name "MyBot"    # Publish with custom name

Scale & Resilience (Phase 2)

Topic Sharding

Automatically splits topics when they grow large:

import { ShardManager, BloomFilter } from '@a2am/node';

const shards = new ShardManager({
  maxAgentsPerShard: 10000,
  shardCount: 16,
});

// Agents are distributed across shards
const shard = shards.addAgentToShard('travel/flights', agentId);

// Bloom filters enable efficient routing
const filter = new BloomFilter(1024, 7);
filter.add(agentId);
filter.mightContain(agentId); // true

Superpeer Protocol

High-capacity nodes provide fast query routing:

import { SuperpeerManager } from '@a2am/node';

const superpeers = new SuperpeerManager({
  enabled: true,
  minUptime: 3600000, // 1 hour
  minCapacity: 50000,
});

// Route queries through superpeers for speed
const agents = await superpeers.routeQuery({ capability: 'travel' });

Gateway Federation

Gateways sync and load-balance automatically:

import { FederationManager } from '@a2am/node';

const federation = new FederationManager({
  syncInterval: 60000,
  loadBalancing: true,
});

federation.addGateway({ url: 'https://gateway1.a2am.network' });
federation.addGateway({ url: 'https://gateway2.a2am.network' });

// Get best gateway for a request
const best = federation.getBestGateway();

Crypto Add-on (Phase 3)

Optional blockchain integration for identity and payments.

EIP-8004 Identity Linking

Link A2AM identity to Ethereum address:

import { IdentityManager } from '@a2am/crypto';

const identity = new IdentityManager();

// Create link request (requires wallet signature)
const request = identity.createLinkRequest(a2amPublicKey, ethAddress);

// After signing with both keys
await identity.completeLink(
  a2amPublicKey,
  ethAddress,
  timestamp,
  ethSignature,
  a2amSignature
);

On-chain Reputation

Track agent reputation through attestations:

import { ReputationManager, REPUTATION_LEVELS } from '@a2am/crypto';

const reputation = new ReputationManager();

// Record interactions
await reputation.recordSuccess(agentId, attesterId, responseTime);
await reputation.recordFailure(agentId, attesterId);

// Get reputation
const score = await reputation.getReputation(agentId);
console.log(score.overall); // 0-100

// Check thresholds
const trusted = await reputation.meetsThreshold(agentId, 'TRUSTED');

Verifiable Credentials

Agents can hold verifiable credentials, establish identity relationships, and act as attesters:

import { CredentialManager } from '@a2am/crypto';

const credentials = new CredentialManager();

// Issue identity credential (attesting who an agent is)
const identityCred = await credentials.issueIdentityCredential(
  issuerPrivateKey,
  agentId,
  {
    name: 'TravelBot Pro',
    organization: 'Travel Inc',
    verified: true,
  }
);

// Issue capability credential (attesting what an agent can do)
const capabilityCred = await credentials.issueCapabilityCredential(
  issuerPrivateKey,
  agentId,
  'travel/flights',
  { region: 'global', tier: 'premium' }
);

// Establish trust relationship
await credentials.establishTrust(
  issuerPrivateKey,
  agentId,
  'high',           // Trust level: none, minimal, standard, high, full
  ['travel/*']      // Scope of trust
);

// Issue delegation credential (allowing agent to issue credentials)
await credentials.issueDelegationCredential(
  issuerPrivateKey,
  agentId,
  ['CapabilityCredential'],  // What types they can issue
  ['travel/*']               // Scope limitation
);

// Verify a credential
const result = await credentials.verifyCredential(credential);
if (result.valid) {
  console.log('Credential is valid!');
} else {
  console.log('Invalid:', result.errors);
}

// Create a presentation (proving ownership of credentials)
const presentation = await credentials.createPresentation(
  holderPrivateKey,
  [identityCred, capabilityCred],
  'challenge-123'  // Optional challenge for freshness
);

// Calculate transitive trust (trust through intermediaries)
const trust = await credentials.calculateTransitiveTrust(agentA, agentC);
console.log(`Trust level: ${trust.trustLevel}, Path: ${trust.path.join(' → ')}`);

// Build trust graph for visualization
const graph = await credentials.buildTrustGraph(rootAgentId, 3);
console.log('Nodes:', graph.nodes);
console.log('Edges:', graph.edges);

Credential Types:

IdentityCredential - Attests identity information (name, organization, etc.)
CapabilityCredential - Attests an agent has a specific capability
TrustCredential - Establishes trust relationship between agents
DelegationCredential - Delegates authority to issue certain credentials
MembershipCredential - Attests membership in a group/organization
VerificationCredential - Attests verification of another credential

Trust Levels:

none - No trust
minimal - Basic trust, limited scope
standard - Normal trust level
high - High trust, broader scope
full - Full trust, can delegate

AgentRank (PageRank for Agents)

Rank agents using a PageRank-style algorithm:

import { AgentRank } from '@a2am/crypto';

const rank = new AgentRank({
  dampingFactor: 0.85,  // Like Google's PageRank
  iterations: 100,
  interactionWeight: 0.3,
});

// Register agents
await rank.registerAgent(agentId);

// Record endorsements (like "links" in PageRank)
await rank.endorse(fromAgentId, toAgentId, 0.8, 'travel/flights');

// Record successful interactions (auto-endorses)
await rank.recordInteraction(agentId, true, peerAgentId);

// Calculate all ranks (iterative algorithm)
const ranks = await rank.calculateRanks();

// Get top agents
const topAgents = await rank.getTopAgents(10);

// Get top agents for a specific capability
const travelAgents = await rank.getTopAgentsForCapability('travel', 10);

// Detect rank manipulation
const { suspicious, reasons } = await rank.detectManipulation(agentId);

How it works:

Endorsements act like links in PageRank - an endorsement from a high-ranked agent is worth more
Successful interactions automatically create endorsements
Time decay reduces the weight of old endorsements
Manipulation detection identifies suspicious patterns (circular endorsements, endorsement spam)

x402 Payments

HTTP 402 Payment Required for paid services:

import { PaymentManager } from '@a2am/crypto';

const payments = new PaymentManager();

// Create payment request
const request = await payments.createRequest(
  agentId,
  BigInt(1000000), // 1 USDC
  'USDC',
  recipientAddress,
  'API access for 24 hours'
);

// Generate x402 headers
const headers = payments.generateHeaders(request);

// Verify payment
await payments.submitProof(requestId, txHash, chainId, payer, blockNumber);
const paid = await payments.isCompleted(requestId);

API Reference

SDK

import { A2AM, a2am } from '@a2am/sdk';

// Use default instance
await a2am.publish({ ... });
await a2am.find("capability");

// Or create custom instance
const client = new A2AM({
  gateways: ["http://localhost:9000"],
  seed: "my-secret-seed-phrase"  // Deterministic identity
});

Gateway REST API

# Publish an agent
POST /publish
Content-Type: application/json
{ "id": "...", "name": "...", "capabilities": [...], "endpoint": "...", "protocols": [...], "sig": "..." }

# Discover agents
GET /discover?capability=travel/flights&limit=10

# Get specific agent
GET /agent/:id

# Delete an agent (requires owner signature)
DELETE /agent/:id
Content-Type: application/json
{ "owner": "public-key", "sig": "signature", "timestamp": 1234567890 }

# Agent heartbeat (self-report health)
POST /agent/:id/heartbeat
Content-Type: application/json
{ "capabilities": ["travel/hotels"] }  # Optional

# Proxy a request to an agent
POST /proxy
Content-Type: application/json
{ "id": "request-id", "from": "sender-id", "to": "agent-id", "capability": "travel/hotels", "payload": {...}, "timestamp": 1234567890 }

# Gateway stats
GET /stats

# Health check
GET /health

# Federation status
GET /federation

# List federation peers
GET /federation/peers

# Receive replicated agent (used by gateways)
POST /federation/push
Content-Type: application/json
{ "agent": {...}, "sourceGateway": "https://..." }

Gateway WebSocket API

const ws = new WebSocket('ws://localhost:9000');

// Subscribe to capability
ws.send(JSON.stringify({ type: 'subscribe', capability: 'travel' }));

// Receive agents
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === 'agent') {
    console.log('New agent:', msg.agent);
  }
};

// Publish agent
ws.send(JSON.stringify({ type: 'publish', agent: { ... } }));

// Discover agents
ws.send(JSON.stringify({ type: 'discover', capability: 'travel', requestId: '123' }));

Capability Hierarchy

Capabilities are organized in a tree structure:

travel
├── flights
│   ├── domestic
│   └── international
├── hotels
└── cars

finance
├── payments
└── trading

data
├── search
├── storage
└── analytics

ai
├── inference
├── embedding
└── training

communication
├── email
├── messaging
└── slack

Searching for travel will find agents with travel/flights, travel/hotels, etc.

Development

# Clone the repo
git clone https://github.com/base60s/A2AM.git
cd A2AM

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Start a gateway
pnpm gateway

Running Examples

# Terminal 1: Start gateway
cd packages/gateway && pnpm start

# Terminal 2: Publish an agent
cd examples/publish-agent && pnpm start

# Terminal 3: Find agents
cd examples/find-agents && pnpm start

Running Demos

# AgentRank Demo - PageRank-style ranking for agents
cd examples/agentrank-demo && pnpm start

# Verifiable Credentials Demo - Identity and trust relationships
cd examples/credentials-demo && pnpm start

Design Principles

No Crypto Required: Works out of the box without blockchain or tokens
Gateway Independence: Any gateway works, no vendor lock-in
Topic Sharding: Scales to planetary-scale agent counts
Cryptographic Identity: Ed25519 keypairs for agent verification
Protocol Flexibility: Support any agent communication protocol

Roadmap

License

MIT

@a2am/mcp-server

Quick Install