# ANP (AI Native Protocol) — 协议规范 v1.2

> 基于 Soraecho 实现，与 Maian OS + KOAN Chain 共同制定

---

## 一、协议概述

ANP 是一个去中心化 AI Agent 通信协议，基于 libp2p 构建，支持：

- **Agent 发现**：通过 DHT + AgentCard 注册发现其他 Agent
- **A2A 调用**：Agent 之间直接调用（HTTP 转发 / libp2p stream）
- **能力描述**：AgentCard 描述 Agent 的能力（Capability Bitmap）
- **去中心化**：无中心服务器，所有节点平等

---

## 二、AgentCard 标准

AgentCard 是 Agent 的"身份证"，JSON 格式：

```json
{
  "did": "did:key:z6Mkf5rgaGxWzB2y3QWr1VLp9XxH5bY5uHPJVXxQaX4n",
  "os_did": "did:key:maian-os-z6Mkf5rgaGx...",
  "name": "Maian-Test-Agent-001",
  "version": "1.3.0",
  "capabilities": ["model.chat", "comm.send", "state.snapshot"],
  "endpoints": ["https://43.156.25.118/a2a/v1"],
  "capability_bitmap": 5,
  "metadata": {
    "os": "Maian OS",
    "model": "gpt-4"
  },
  "created_at": "2026-06-29T08:00:00Z",
  "updated_at": "2026-06-29T08:00:00Z"
}
```

### 字段说明

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `did` | string | ✅ | Agent 的 DID（去中心化标识符） |
| `os_did` | string | ❌ | Agent OS 调度域的 DID |
| `name` | string | ✅ | Agent 名称 |
| `capabilities` | string[] | ✅ | 能力列表（点号格式） |
| `endpoints` | string[] | ❌ | A2A 调用端点（HTTP URL） |
| `capability_bitmap` | uint64 | ❌ | 能力位图（12 bits） |
| `metadata` | object | ❌ | 扩展元数据 |
| `created_at` | string | ❌ | 注册时间（ISO8601） |
| `updated_at` | string | ❌ | 更新时间（ISO8601） |

---

## 三、Capability Bitmap（v1.2）

12 个预定义能力位：

| Bit | 名称 | 说明 |
|---|---|---|
| 0 | `model.chat` | 对话模型 |
| 1 | `model.embedding` | 嵌入模型 |
| 2 | `comm.send` | 消息发送 |
| 3 | `settlement.submit` | 结算提交 |
| 4 | `state.snapshot` | 状态快照 |
| 5 | `storage.ipfs` | IPFS 存储 |
| 6 | `compute.gpu` | GPU 计算 |
| 7 | `search.web` | 网页搜索 |
| 8 | `codegen.python` | Python 代码生成 |
| 9 | `translation.en-zh` | 英中翻译 |
| 10 | `vision.ocr` | OCR 视觉 |
| 11 | `audio.tts` | 文本转语音 |

扩展能力（bit 12-63）预留给自定义能力。

---

## 四、A2A 调用流程

### HTTP 转发模式（当前实现）

```
┌─────────┐    POST /a2a/v1/task    ┌──────────────┐
│ Caller  │ ───────────────────────→ │ Soraecho GW │
│ Agent   │                          │  (anpd-new)  │
└─────────┘                          └──────┬───────┘
                                          │ HTTP POST
                                          ↓
                                    ┌──────────────┐
                                    │ Target Agent │
                                    │  endpoints[0]│
                                    └──────────────┘
```

**请求格式：**
```json
POST /a2a/v1/task
{
  "target_did": "did:key:z6Mkf5rgaGx...",
  "target_capability": "model.chat",
  "payload": {
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello"}]
  }
}
```

**响应格式：**
```json
{
  "status": "completed",
  "result": {
    "choices": [{"message": {"content": "Hi there!"}}]
  }
}
```

---

## 五、libp2p 协议 ID

| 协议 ID | 用途 |
|---|---|
| `/anp/v1.2/agentcard` | AgentCard 交换（JSON over stream） |
| `/anp/v1.2/a2a` | A2A 任务协议（预留） |
| `/ipfs/kad/1.0.0` | DHT 路由 |

---

## 六、网络拓扑

```
Bootstrap Node (129.226.202.231:4001)
    ├── Peer A (anpd v1.1.1)
    ├── Peer B (anpd v1.1.1)
    └── Soraecho Node (129.226.217.205:4006, anpd-new v1.2h)
            └── 注册 AgentCard → DHT 可发现
```

- **Bootstrap 节点**：帮助新节点加入网络
- **DHT**：分布式哈希表，存储 Peer 路由信息
- **AgentCard**：存储在本地 + 通过 DHT 发现

---

## 七、与 Maian OS 的集成

Maian OS 通过以下方式与 Soraecho 集成：

1. **Agent 注册**：Maian OS Agent 通过 `POST /api/v1/agentcard/register` 注册到 Soraecho
2. **Agent 发现**：`GET /api/v1/agentcard/discover?capability=model.chat`
3. **A2A 调用**：`POST /a2a/v1/task` → Soraecho 转发到目标 Agent
4. **标准共享**：AgentCard 格式三方共同制定（Soraecho + Maian OS + KOAN Chain）

---

## 八、未来方向（Phase 4）

- **libp2p stream 原生 A2A**：替代 HTTP 转发，真正去中心化
- **端到端加密**：基于 DID 的双向 TLS 认证
- **Agent 信誉系统**：调用成功率 + 响应时间评分
- **SDK 多语言**：Python / JavaScript / Rust

---

*协议版本：v1.2*
*最后更新：2026-06-29*
*共同制定：Soraecho + Maian OS + KOAN Chain*