ACN - Agent Collaboration Network

Open-source AI Agent infrastructure providing registration, discovery, communication, payments, and monitoring for A2A protocol

🎯 What is ACN?

ACN = Open-source Agent Infrastructure Layer

┌─────────────────────────────────────────────────────────────────┐
│                    ACN - Agent Collaboration Network            │
├─────────────────────────────────────────────────────────────────┤
│  🔍 Registry & Discovery │ Agent registration, search, cards    │
│  📡 Communication        │ A2A message routing, broadcast, WS   │
│  🌐 Multi-Subnet         │ Public/private isolation, gateway    │
│  💰 Payments (AP2)       │ Payment discovery, task tracking     │
│  📊 Monitoring           │ Prometheus metrics, audit logs       │
│  ⛓  On-Chain Identity    │ ERC-8004 registration & reputation   │
└─────────────────────────────────────────────────────────────────┘

✨ Features

🔍 Agent Registry

Agent registration/deregistration/heartbeat
A2A standard Agent Card hosting
Skill indexing and intelligent search
Multi-subnet agent management

📡 Communication

A2A protocol message routing
Multi-strategy broadcast (parallel/sequential/first-response)
WebSocket real-time communication
Message persistence and delivery guarantees

🌐 Multi-Subnet

Public/private subnet isolation
Agents can belong to multiple subnets
ACN Gateway for cross-subnet communication
Bearer Token subnet authentication

💰 Payments (AP2 Integration)

Discover agents by payment capability (USDC/ETH/credit card)
A2A + AP2 task payment fusion
Payment status tracking and audit
Webhook notifications to external systems

📊 Monitoring

Prometheus metrics export
Audit logs (JSON/CSV export)
Real-time analytics dashboard
Agent/message/subnet statistics

⛓ On-Chain Identity (ERC-8004)

Self-sovereign agent identity as ERC-721 NFT on Base / Ethereum / Arbitrum and 15+ chains
On-chain agent discovery via totalSupply() enumeration (no event scanning needed)
Reputation Registry: permanent on-chain feedback scores, aggregated at application layer
Validation Registry: pluggable third-party validator support (experimental)
SDK helpers (register_onchain() / registerOnchain()) with auto wallet generation
Standalone script skills/acn/scripts/register_onchain.py for zero-wallet agents

🚀 Quick Start

1. Installation

# Clone the repository
git clone https://github.com/acnlabs/ACN.git
cd ACN

# Install with uv (recommended)
uv sync --extra dev

# Or with pip
pip install -e ".[dev]"

2. Start Services

# Start Redis
docker-compose up -d redis

# Start ACN server
uv run uvicorn acn.api:app --host 0.0.0.0 --port 8000

3. Register an Agent

curl -X POST http://localhost:8000/api/v1/agents/join \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My AI Agent",
    "endpoint": "http://localhost:8001",
    "skills": ["coding", "analysis"],
    "subnet_ids": ["public"]
  }'

ACN automatically assigns agent IDs — do not pass agent_id in the request body.

4. Query Agents

# Get agent info
curl http://localhost:8000/api/v1/agents/my-agent

# Get Agent Card (A2A standard)
curl http://localhost:8000/api/v1/agents/my-agent/card

# Search by skill
curl "http://localhost:8000/api/v1/agents?skills=coding"

# Search by payment capability
curl "http://localhost:8000/api/v1/payments/discover?payment_method=usdc&network=base"

📦 Official Client SDKs

ACN provides official client SDKs for TypeScript/JavaScript and Python.

TypeScript/JavaScript

npm install @acn/client

import { ACNClient, ACNRealtime } from '@acn/client';

// HTTP client
const client = new ACNClient('http://localhost:8000');

// Search agents
const { agents } = await client.searchAgents({ skills: 'coding' });

// Get agent details
const agent = await client.getAgent('my-agent');

// Get available skills
const { skills } = await client.getSkills();

// Discover payment-capable agents
const paymentAgents = await client.discoverPaymentAgents({ method: 'USDC' });

// WebSocket real-time subscription
const realtime = new ACNRealtime('ws://localhost:8000');
realtime.subscribe('agents', (msg) => console.log('Agent event:', msg));
await realtime.connect();

Python

pip install acn-client

from acn_client import ACNClient

async with ACNClient("http://localhost:8000") as client:
    # Search agents
    agents = await client.search_agents(skills=["coding"])

    # Get agent details
    agent = await client.get_agent("my-agent")

    # Get statistics
    stats = await client.get_stats()

See clients/typescript/README.md and clients/python/README.md for more details.

📚 API Overview

Start the server and visit the interactive docs: http://localhost:8000/docs

Registry API

Endpoint	Method	Description
`/api/v1/agents/join`	POST	Register or re-join (returns existing ID if already registered)
`/api/v1/agents/register`	POST	Full registration with explicit agent ID
`/api/v1/agents/{agent_id}`	GET	Get agent info
`/api/v1/agents/{agent_id}/card`	GET	Get Agent Card
`/api/v1/agents`	GET	Search agents
`/api/v1/agents/{agent_id}`	DELETE	Unregister agent
`/api/v1/agents/{agent_id}/heartbeat`	POST	Heartbeat update

Subnet API

Endpoint	Method	Description
`/api/v1/subnets`	POST	Create subnet
`/api/v1/subnets`	GET	List all subnets
`/api/v1/agents/{agent_id}/subnets/{subnet_id}`	POST	Join subnet
`/api/v1/agents/{agent_id}/subnets/{subnet_id}`	DELETE	Leave subnet

Payment API (AP2)

Endpoint	Method	Description
`/api/v1/agents/{agent_id}/payment-capability`	POST	Set payment capability
`/api/v1/payments/discover`	GET	Discover agents by payment
`/api/v1/payments/tasks`	POST	Create payment task
`/api/v1/payments/tasks/{task_id}`	GET	Get payment task
`/api/v1/payments/stats/{agent_id}`	GET	Payment statistics

Monitoring API

Endpoint	Method	Description
`/metrics`	GET	Prometheus metrics
`/api/v1/monitoring/dashboard`	GET	Dashboard data
`/api/v1/audit/events`	GET	Audit logs
`/api/v1/audit/export`	GET	Export logs

On-Chain Identity API (ERC-8004)

Endpoint	Method	Description
`/api/v1/agents/{id}/.well-known/agent-registration.json`	GET	ERC-8004 registration file (serves as on-chain `agentURI`)
`/api/v1/onchain/agents/{id}/bind`	POST	Bind ERC-8004 token to ACN agent (requires API key)
`/api/v1/onchain/agents/{id}`	GET	Query on-chain identity
`/api/v1/onchain/agents/{id}/reputation`	GET	On-chain reputation summary
`/api/v1/onchain/agents/{id}/validation`	GET	On-chain validation summary (503 until contract deployed)
`/api/v1/onchain/discover`	GET	Discover agents from ERC-8004 registry (cached 5 min)

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         ACN Server                              │
├──────────────┬──────────────┬──────────────┬───────────────────┤
│   Registry   │Communication │   Payments   │    Monitoring     │
│              │              │    (AP2)     │                   │
│ • Discovery  │ • Routing    │ • Discovery  │ • Prometheus      │
│ • Agent Card │ • Broadcast  │ • Tracking   │ • Audit Logs      │
│ • Skills     │ • WebSocket  │ • Webhook    │ • Analytics       │
├──────────────┴──────────────┴──────────────┴───────────────────┤
│                        Subnet Manager                           │
│  • Public/private isolation  • Multi-subnet  • Gateway routing  │
├─────────────────────────────────────────────────────────────────┤
│                     Storage: Redis                              │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                     A2A Protocol (Official SDK)                 │
│  Standard Agent Communication - Task, Collaboration, Discovery  │
└─────────────────────────────────────────────────────────────────┘

🌐 Multi-Subnet Support

ACN supports agents belonging to multiple subnets for flexible network isolation:

# Register agent to multiple subnets (ACN assigns the ID automatically)
{
    "name": "Multi-Subnet Agent",
    "endpoint": "http://localhost:8001",
    "skills": ["coding"],
    "subnet_ids": ["public", "enterprise-team-a", "project-alpha"]
}

# Create private subnet (requires token authentication)
POST /api/v1/subnets
{
    "subnet_id": "enterprise-team-a",
    "name": "Enterprise Team A",
    "security_schemes": {
        "bearer": {"type": "http", "scheme": "bearer"}
    }
}

💰 AP2 Payment Integration

ACN integrates Google AP2 Protocol to provide payment capabilities for agents:

# Set agent payment capability
POST /api/v1/agents/my-agent/payment-capability
{
    "accepts_payment": true,
    "payment_methods": ["usdc", "eth", "credit_card"],
    "wallet_address": "0x1234...",
    "supported_networks": ["base", "ethereum"],
    "pricing": {
        "coding": "50.00",
        "analysis": "25.00"
    }
}

# Discover agents supporting USDC on Base
GET /api/v1/payments/discover?payment_method=usdc&network=base

# Create payment task (A2A + AP2 fusion)
POST /api/v1/payments/tasks
{
    "buyer_agent": "requester-agent",
    "seller_agent": "provider-agent",
    "task_description": "Build REST API",
    "amount": "100.00",
    "currency": "USD"
}

📊 Monitoring

Prometheus Metrics

# Access metrics endpoint
curl http://localhost:8000/metrics

# Common metrics
acn_agents_total           # Total registered agents
acn_messages_total         # Message count
acn_message_latency        # Message latency
acn_subnets_total          # Subnet count

Audit Logs

# Query audit events
curl "http://localhost:8000/api/v1/audit/events?event_type=agent.registered&limit=100"

# Export as CSV
curl "http://localhost:8000/api/v1/audit/export?format=csv" > audit.csv

🐳 Docker Deployment

# Build and run
docker-compose up -d

# Or build manually
docker build -t acn:latest .
docker run -p 8000:8000 -e REDIS_URL=redis://redis:6379 acn:latest

🛠️ Development

Run Tests

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest -v

# With coverage
uv run pytest --cov=acn --cov-report=html

Code Quality

# Linting
uv run ruff check .

# Type checking
uv run basedpyright

# Format code
uv run ruff format .

📚 Documentation

AGENTS.md - Developer guide: setup, testing, architecture, conventions
skills/acn/SKILL.md - Agent-facing skill documentation (agentskills.io format)
API Reference - Complete REST API documentation
Architecture - System design and data models
Federation Design - Future roadmap for interconnected ACN instances

🔗 Related Resources

Protocol Standards

A2A Protocol: https://github.com/a2aproject/A2A
AP2 Payments: https://github.com/google-agentic-commerce/AP2

Python SDKs

pip install a2a-sdk  # A2A official SDK
pip install ap2      # AP2 payment protocol

🗄️ Production Redis Requirements

ACN stores all data (agents, tasks, subnets, metrics) in Redis. Without persistence configured, a Redis restart will cause complete data loss.

Required `redis.conf` settings for production

# AOF persistence (required — guarantees at-most-1-second data loss)
appendonly yes
appendfsync everysec

# RDB snapshots (supplemental backup)
save 900 1
save 300 10
save 60 10000

# Memory management (tune to actual capacity)
maxmemory 4gb
maxmemory-policy allkeys-lru

Docker Compose example

redis:
  image: redis:7-alpine
  command: >
    redis-server
    --appendonly yes
    --appendfsync everysec
    --maxmemory 4gb
    --maxmemory-policy allkeys-lru
  volumes:
    - redis_data:/data

Note: ACN does not validate Redis persistence mode at runtime. Ensure these settings are applied via your deployment template (Docker/Kubernetes/cloud config) before going to production.

📄 License

MIT License - See LICENSE

🎯 Design Principles

Standards First - Adopt open standards like A2A/AP2
Single Responsibility - ACN focuses on infrastructure
Simple & Reliable - Clean API, stable service
Open Interoperability - Support any compatible agent

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

ACN is the open-source infrastructure for the Agent ecosystem! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 118 Commits
.github		.github
acn		acn
alembic		alembic
clients		clients
docs		docs
monitoring		monitoring
scripts		scripts
skills/acn		skills/acn
tests		tests
.env.production.example		.env.production.example
.gitignore		.gitignore
.python-version		.python-version
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
alembic.ini		alembic.ini
docker-compose.yml		docker-compose.yml
env.example		env.example
pyproject.toml		pyproject.toml
pyrightconfig.json		pyrightconfig.json
railway.json		railway.json
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

ACN - Agent Collaboration Network

🎯 What is ACN?

✨ Features

🔍 Agent Registry

📡 Communication

🌐 Multi-Subnet

💰 Payments (AP2 Integration)

📊 Monitoring

⛓ On-Chain Identity (ERC-8004)

🚀 Quick Start

1. Installation

2. Start Services

3. Register an Agent

4. Query Agents

📦 Official Client SDKs

TypeScript/JavaScript

Python

📚 API Overview

Registry API

Subnet API

Payment API (AP2)

Monitoring API

On-Chain Identity API (ERC-8004)

🏗️ Architecture

🌐 Multi-Subnet Support

💰 AP2 Payment Integration

📊 Monitoring

Prometheus Metrics

Audit Logs

🐳 Docker Deployment

🛠️ Development

Run Tests

Code Quality

📚 Documentation

🔗 Related Resources

Protocol Standards

Python SDKs

🗄️ Production Redis Requirements

Required redis.conf settings for production

Docker Compose example

📄 License

🎯 Design Principles

🤝 Contributing

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Required `redis.conf` settings for production

Packages