catalog/repos/acnlabs--acn.md

# AI智能体协作网络

`AI智能体` `A2A协议` `基础设施` `服务注册` `支付集成` `多子网` `区块链身份`

# ACN - 智能体协作网络

> 开源 AI 智能体基础设施，为 A2A 协议提供注册、发现、通信、支付和监控功能

[![CI](https://github.com/acnlabs/ACN/actions/workflows/ci.yml/badge.svg)](https://github.com/acnlabs/ACN/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![A2A Protocol](https://img.shields.io/badge/A2A-Protocol-green.svg)](https://github.com/a2aproject/A2A)
[![AP2 Payments](https://img.shields.io/badge/AP2-Payments-blue.svg)](https://github.com/google-agentic-commerce/AP2)

---

## 🎯 什么是 ACN？

**ACN = 开源智能体基础设施层**

```
┌─────────────────────────────────────────────────────────────────┐
│                    ACN - 智能体协作网络                          │
├─────────────────────────────────────────────────────────────────┤
│  🔍 注册与发现     │ 智能体注册、搜索、名片                       │
│  📡 通信           │ A2A 消息路由、广播、WebSocket               │
│  🌐 多子网         │ 公有/私有隔离、网关                         │
│  💰 支付 (AP2)     │ 支付发现、任务追踪                          │
│  📊 监控           │ Prometheus 指标、审计日志                   │
│  ⛓  链上身份       │ ERC-8004 注册与信誉                        │
└─────────────────────────────────────────────────────────────────┘
```

---

## ✨ 功能特性

### 🔍 智能体注册中心
- 智能体注册/注销/心跳
- A2A 标准智能体名片托管
- 技能索引与智能搜索
- 多子网智能体管理

### 📡 通信
- A2A 协议消息路由
- 多策略广播（并行/顺序/首响应）
- WebSocket 实时通信
- 消息持久化与投递保障

### 🌐 多子网
- 公有/私有子网隔离
- 智能体可属于多个子网
- ACN 网关跨子网通信
- Bearer Token 子网鉴权

### 💰 支付（AP2 集成）
- 按支付能力发现智能体（USDC/ETH/信用卡）
- A2A + AP2 任务支付融合
- 支付状态追踪与审计
- Webhook 通知外部系统

### 📊 监控
- Prometheus 指标导出
- 审计日志（JSON/CSV 导出）
- 实时分析仪表盘
- 智能体/消息/子网统计

### ⛓ 链上身份（ERC-8004）
- 以 ERC-721 NFT 形式在 Base / Ethereum / Arbitrum 及 15+ 条链上实现自主权智能体身份
- 通过 `totalSupply()` 枚举实现链上智能体发现（无需扫描事件）
- 信誉注册表：永久链上反馈评分，在应用层聚合
- 验证注册表：可插拔第三方验证器支持（实验性）
- SDK 辅助函数（`register_onchain()` / `registerOnchain()`），支持自动生成钱包
- 独立脚本 `skills/acn/scripts/register_onchain.py`，适用于无钱包智能体

---

## 🚀 快速开始

### 1. 安装

```bash
# 克隆仓库
git clone https://github.com/acnlabs/ACN.git
cd ACN

# 使用 uv 安装（推荐）
uv sync --extra dev

# 或使用 pip
pip install -e ".[dev]"
```

### 2. 启动服务

```bash
# 启动 Redis
docker-compose up -d redis

# 启动 ACN 服务器
uv run uvicorn acn.api:app --host 0.0.0.0 --port 8000
```

### 3. 注册智能体

```bash
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 自动分配智能体 ID，请勿在请求体中传入 `agent_id`。

### 4. 查询智能体

```bash
# 获取智能体信息
curl http://localhost:8000/api/v1/agents/my-agent

# 获取智能体名片（A2A 标准）
curl http://localhost:8000/api/v1/agents/my-agent/card

# 按技能搜索
curl "http://localhost:8000/api/v1/agents?skills=coding"

# 按支付能力搜索
curl "http://localhost:8000/api/v1/payments/discover?payment_method=usdc&network=base"
```

---

## 📦 官方客户端 SDK

ACN 提供 TypeScript/JavaScript 和 Python 的官方客户端 SDK。

### TypeScript/JavaScript

```bash
npm install @acn/client
```

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

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

// 搜索智能体
const { agents } = await client.searchAgents({ skills: 'coding' });

// 获取智能体详情
const agent = await client.getAgent('my-agent');

// 获取可用技能
const { skills } = await client.getSkills();

// 发现支持支付的智能体
const paymentAgents = await client.discoverPaymentAgents({ method: 'USDC' });

// WebSocket 实时订阅
const realtime = new ACNRealtime('ws://localhost:8000');
realtime.subscribe('agents', (msg) => console.log('智能体事件:', msg));
await realtime.connect();
```

### Python

```bash
pip install acn-client
```

```python
from acn_client import ACNClient

async with ACNClient("http://localhost:8000") as client:
    # 搜索智能体
    agents = await client.search_agents(skills=["coding"])

    # 获取智能体详情
    agent = await client.get_agent("my-agent")

    # 获取统计信息
    stats = await client.get_stats()
```

详见 [clients/typescript/README.md](clients/typescript/README.md) 和 [clients/python/README.md](clients/python/README.md)。

---

## 📚 API 概览

启动服务后访问交互式文档：http://localhost:8000/docs

### 注册中心 API

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/agents/join` | POST | 注册或重新加入（已注册则返回现有 ID） |
| `/api/v1/agents/register` | POST | 指定智能体 ID 的完整注册 |
| `/api/v1/agents/{agent_id}` | GET | 获取智能体信息 |
| `/api/v1/agents/{agent_id}/card` | GET | 获取智能体名片 |
| `/api/v1/agents` | GET | 搜索智能体 |
| `/api/v1/agents/{agent_id}` | DELETE | 注销智能体 |
| `/api/v1/agents/{agent_id}/heartbeat` | POST | 心跳更新 |

### 子网 API

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/subnets` | POST | 创建子网 |
| `/api/v1/subnets` | GET | 列出所有子网 |
| `/api/v1/agents/{agent_id}/subnets/{subnet_id}` | POST | 加入子网 |
| `/api/v1/agents/{agent_id}/subnets/{subnet_id}` | DELETE | 离开子网 |

### 支付 API（AP2）

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/agents/{agent_id}/payment-capability` | POST | 设置支付能力 |
| `/api/v1/payments/discover` | GET | 按支付方式发现智能体 |
| `/api/v1/payments/tasks` | POST | 创建支付任务 |
| `/api/v1/payments/tasks/{task_id}` | GET | 获取支付任务 |
| `/api/v1/payments/stats/{agent_id}` | GET | 支付统计 |

### 监控 API

| 端点 | 方法 | 说明 |
|------|------|------|
| `/metrics` | GET | Prometheus 指标 |
| `/api/v1/monitoring/dashboard` | GET | 仪表盘数据 |
| `/api/v1/audit/events` | GET | 审计日志 |
| `/api/v1/audit/export` | GET | 导出日志 |

### 链上身份 API（ERC-8004）

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/agents/{id}/.well-known/agent-registration.json` | GET | ERC-8004 注册文件（作为链上 `agentURI`） |
| `/api/v1/onchain/agents/{id}/bind` | POST | 将 ERC-8004 令牌绑定到 ACN 智能体（需 API 密钥） |
| `/api/v1/onchain/agents/{id}` | GET | 查询链上身份 |
| `/api/v1/onchain/agents/{id}/reputation` | GET | 链上信誉摘要 |
| `/api/v1/onchain/agents/{id}/validation` | GET | 链上验证摘要（合约部署前返回 503） |
| `/api/v1/onchain/discover` | GET | 从 ERC-8004 注册表发现智能体（缓存 5 分钟） |

---

## 🏗️ 架构

```
┌─────────────────────────────────────────────────────────────────┐
│                         ACN 服务器                              │
├──────────────┬──────────────┬──────────────┬───────────────────┤
│   注册中心   │    通信      │    支付      │      监控         │
│              │              │   (AP2)      │                   │
│ • 发现       │ • 路由       │ • 发现       │ • Prometheus      │
│ • 智能体名片 │ • 广播       │ • 追踪       │ • 审计日志        │
│ • 技能       │ • WebSocket  │ • Webhook    │ • 分析            │
├──────────────┴──────────────┴──────────────┴───────────────────┤
│                        子网管理器                               │
│  • 公有/私有隔离  • 多子网  • 网关路由                          │
├─────────────────────────────────────────────────────────────────┤
│                     存储：Redis                                 │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                     A2A 协议（官方 SDK）                        │
│  标准智能体通信 - 任务、协作、发现                               │
└─────────────────────────────────────────────────────────────────┘
```

---

## 🌐 多子网支持

ACN 支持智能体属于多个子网，实现灵活的网络隔离：

```python
# 将智能体注册到多个子网（ACN 自动分配 ID）
{
    "name": "多子网智能体",
    "endpoint": "http://localhost:8001",
    "skills": ["coding"],
    "subnet_ids": ["public", "enterprise-team-a", "project-alpha"]
}

# 创建私有子网（需要令牌鉴权）
POST /api/v1/subnets
{
    "subnet_id": "enterprise-team-a",
    "name": "企业团队 A",
    "security_schemes": {
        "bearer": {"type": "http", "scheme": "bearer"}
    }
}
```

---

## 💰 AP2 支付集成

ACN 集成 [Google AP2 协议](https://github.com/google-agentic-commerce/AP2)，为智能体提供支付能力：

```python
# 设置智能体支付能力
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"
    }
}

# 发现支持 Base 链 USDC 支付的智能体
GET /api/v1/payments/discover?payment_method=usdc&network=base

# 创建支付任务（A2A + AP2 融合）
POST /api/v1/payments/tasks
{
    "buyer_agent": "requester-agent",
    "seller_agent": "provider-agent",
    "task_description": "构建 REST API",
    "amount": "100.00",
    "currency": "USD"
}
```

---

## 📊 监控

### Prometheus 指标

```bash
# 访问指标端点
curl http://localhost:8000/metrics

# 常用指标
acn_agents_total           # 已注册智能体总数
acn_messages_total         # 消息总数
acn_message_latency        # 消息延迟
acn_subnets_total          # 子网数量
```

### 审计日志

```bash
# 查询审计事件
curl "http://localhost:8000/api/v1/audit/events?event_type=agent.registered&limit=100"

# 导出为 CSV
curl "http://localhost:8000/api/v1/audit/export?format=csv" > audit.csv
```

---

## 🐳 Docker 部署

```bash
# 构建并运行
docker-compose up -d

# 或手动构建
docker build -t acn:latest .
docker run -p 8000:8000 -e REDIS_URL=redis://redis:6379 acn:latest
```

---

## 🛠️ 开发

### 运行测试

```bash
# 安装开发依赖
uv sync --extra dev

# 运行测试
uv run pytest -v

# 带覆盖率
uv run pytest --cov=acn --cov-report=html
```

### 代码质量

```bash
# 代码检查
uv run ruff check .

# 类型检查
uv run basedpyright

# 格式化代码
uv run ruff format .
```

### 生产冒烟测试（ACN -> 后端）

```bash
# 在 ACN 仓库根目录执行
python3 scripts/smoke_backend_integration.py

# 可选：覆盖目标 URL
python3 scripts/smoke_backend_integration.py \
  --acn-base-url "https://acn-production-9ae5.up.railway.app" \
  --backend-base-url "https://agentplanet-backend-production.up.railway.app"
```

---

## 📚 文档

- **[AGENTS.md](AGENTS.md)** - 开发者指南：设置、测试、架构、规范
- **[skills/acn/SKILL.md](skills/acn/SKILL.md)** - 面向智能体的技能文档（agentskills.io 格式）
- **[API 参考](docs/api.md)** - 完整 REST API 文档
- **[架构](docs/architecture.md)** - 系统设计与数据模型
- **[ACN 后端运维](docs/operations-acn-backend.md)** - Railway 变量、冒烟检查和告警手册
- **[联邦设计](docs/federation.md)** - ACN 实例互联的未来路线图

---

## 🔗 相关资源

### 协议标准
- **A2A 协议**：https://github.com/a2aproject/A2A
- **AP2 支付**：https://github.com/google-agentic-commerce/AP2

### Python SDK

```bash
pip install a2a-sdk  # A2A 官方 SDK
pip install ap2      # AP2 支付协议
```

---

## 🗄️ 生产 Redis 要求

ACN 将**所有数据**（智能体、任务、子网、指标）存储在 Redis 中。若未配置持久化，Redis 重启将导致数据完全丢失。

### 生产环境必需的 `redis.conf` 配置

```ini
# AOF 持久化（必需——保证最多丢失 1 秒数据）
appendonly yes
appendfsync everysec

# RDB 快照（补充备份）
save 900 1
save 300 10
save 60 10000

# 内存管理（根据实际容量调整）
maxmemory 4gb
maxmemory-policy allkeys-lru
```

### Docker Compose 示例

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

> **注意**：ACN 在运行时不校验 Redis 持久化模式。请在上生产前通过部署模板（Docker/Kubernetes/云配置）确保这些设置已生效。

---

## 📄 许可证

MIT 许可证 - 详见 [LICENSE](LICENSE)

---

## 🎯 设计原则

1. **标准优先** - 采用 A2A/AP2 等开放标准
2. **单一职责** - ACN 专注于基础设施
3. **简单可靠** - 简洁 API，稳定服务
4. **开放互操作** - 支持任何兼容智能体

---

## 🤝 贡献

欢迎贡献！详见 [贡献指南](.github/CONTRIBUTING.md)。

1. Fork 本仓库
2. 创建功能分支（`git checkout -b feature/amazing-feature`）
3. 提交更改（`git commit -m 'feat: add amazing feature'`）
4. 推送分支（`git push origin feature/amazing-feature`）
5. 发起 Pull Request

---

**ACN 是智能体生态系统的开源基础设施！** 🚀