mc-skills/catalog

Fork 0

mc-skills 6e3f9bab06 catalog: 更新 2026-04-06 22:24

2026-04-06 22:24:03 +08:00

15 KiB

Raw Blame History

AI智能体协作网络

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

ACN - 智能体协作网络

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

🎯 什么是 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. 安装

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

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

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

2. 启动服务

# 启动 Redis
docker-compose up -d redis

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

3. 注册智能体

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. 查询智能体

# 获取智能体信息
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

npm install @acn/client

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

pip install acn-client

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/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 支持智能体属于多个子网，实现灵活的网络隔离：

# 将智能体注册到多个子网（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 协议，为智能体提供支付能力：

# 设置智能体支付能力
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 指标

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

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

审计日志

# 查询审计事件
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 部署

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

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

🛠️ 开发

运行测试

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

# 运行测试
uv run pytest -v

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

代码质量

# 代码检查
uv run ruff check .

# 类型检查
uv run basedpyright

# 格式化代码
uv run ruff format .

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

# 在 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 - 开发者指南：设置、测试、架构、规范
skills/acn/SKILL.md - 面向智能体的技能文档（agentskills.io 格式）
API 参考 - 完整 REST API 文档
架构 - 系统设计与数据模型
ACN 后端运维 - Railway 变量、冒烟检查和告警手册
联邦设计 - ACN 实例互联的未来路线图

🔗 相关资源

协议标准

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

Python SDK

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

🗄️ 生产 Redis 要求

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

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

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

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

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

Docker Compose 示例

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

🎯 设计原则

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

🤝 贡献

欢迎贡献！详见贡献指南。

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

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

15 KiB Raw Blame History Unescape Escape

AI智能体协作网络

ACN - 智能体协作网络

🎯 什么是 ACN？

✨ 功能特性

🔍 智能体注册中心

📡 通信

🌐 多子网

💰 支付（AP2 集成）

📊 监控

⛓ 链上身份（ERC-8004）

🚀 快速开始

1. 安装

2. 启动服务

3. 注册智能体

4. 查询智能体

📦 官方客户端 SDK

TypeScript/JavaScript

Python

📚 API 概览

注册中心 API

子网 API

支付 API（AP2）

监控 API

链上身份 API（ERC-8004）

🏗️ 架构

🌐 多子网支持

💰 AP2 支付集成

📊 监控

Prometheus 指标

审计日志

🐳 Docker 部署

🛠️ 开发

运行测试

代码质量

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

📚 文档

🔗 相关资源

协议标准

Python SDK

🗄️ 生产 Redis 要求

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

Docker Compose 示例

📄 许可证

🎯 设计原则

🤝 贡献

15 KiB

Raw Blame History

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