513 lines
15 KiB
Markdown
513 lines
15 KiB
Markdown
# AI智能体协作网络
|
||
|
||
`AI智能体` `A2A协议` `基础设施` `服务注册` `支付集成` `多子网` `区块链身份`
|
||
|
||
# ACN - 智能体协作网络
|
||
|
||
> 开源 AI 智能体基础设施，为 A2A 协议提供注册、发现、通信、支付和监控功能
|
||
|
||
[](https://github.com/acnlabs/ACN/actions/workflows/ci.yml)
|
||
[](https://opensource.org/licenses/MIT)
|
||
[](https://www.python.org/downloads/)
|
||
[](https://github.com/a2aproject/A2A)
|
||
[](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 是智能体生态系统的开源基础设施！** 🚀 |