# Soraecho ANP API 文档 v1.2

> 基础 URL: `http://129.226.217.205:4006`（或 `https://soraecho.com/api/node/`）

---

## 一、健康检查

### `GET /health`

返回节点状态。

**响应：**
```json
{
  "status": "ok",
  "peers": 166,
  "connections": 103,
  "agent_cards": 3,
  "timestamp": "2026-06-29T08:00:00Z"
}
```

---

## 二、AgentCard 管理

### `POST /api/v1/agentcard/register`

注册/更新 AgentCard。

**请求：**
```json
{
  "did": "did:key:z6Mkf5rgaGxWzB2y3QWr1VLp9XxH5bY5uHPJVXxQaX4n",
  "os_did": "did:key:maian-os-z6Mkf5rgaGx...",
  "name": "Maian-Test-Agent-001",
  "capabilities": ["model.chat", "comm.send"],
  "endpoints": ["https://43.156.25.118/a2a/v1"],
  "metadata": {"version": "1.3.0"}
}
```

**响应：**
```json
{ "did": "did:key:...", "status": "ok" }
```

---

### `GET /api/v1/agentcard/query?did=...`

查询单个 AgentCard。

**参数：**
- `did`：Agent 的 DID

**响应：** AgentCard JSON（见协议文档）

---

### `GET /api/v1/agentcard/list`

列出所有已注册的 AgentCard。

**响应：**
```json
{
  "cards": [ ...AgentCard 数组... ],
  "count": 3
}
```

---

### `GET /api/v1/agentcard/discover?capability=...`

按能力发现 Agent（只返回有 endpoints 的 Agent）。

**参数：**
- `capability`：能力名称（如 `model.chat`）

**响应：**
```json
{
  "cards": [ ...AgentCard 数组... ],
  "count": 2
}
```

---

## 三、A2A 调用

### `POST /a2a/v1/task`

提交 A2A 任务（真实 HTTP 转发到目标 Agent）。

**请求：**
```json
{
  "target_did": "did:key:z6Mkf5rgaGxWzB2y3QWr1VLp9XxH5bY5uHPJVXxQaX4n",
  "target_capability": "model.chat",
  "payload": {
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello"}]
  }
}
```

**响应：**
```json
{
  "status": "completed",
  "result": { ...目标 Agent 的响应... }
}
```

---

## 四、路由表（调试）

### `GET /routing-table`

返回 libp2p DHT 路由表。

### `GET /connections`

返回当前活跃连接。

---

## 五、错误格式

```json
{
  "error": "描述信息",
  "code": 400
}
```

HTTP 状态码：
- `200`：成功
- `400`：请求格式错误
- `404`：Agent 未找到
- `500`：服务器内部错误

---

## 六、Maian OS 集成示例

```python
import requests

API = "http://129.226.217.205:4006"

# 1. 注册 Agent
requests.post(f"{API}/api/v1/agentcard/register", json={
    "did": "did:key:your-agent-did",
    "name": "MyAgent",
    "capabilities": ["model.chat"],
    "endpoints": ["https://your-domain/a2a/v1"]
})

# 2. 发现 model.chat Agent
resp = requests.get(f"{API}/api/v1/agentcard/discover?capability=model.chat")
target_did = resp.json()["cards"][0]["did"]

# 3. 调用 A2A
resp = requests.post(f"{API}/a2a/v1/task", json={
    "target_did": target_did,
    "target_capability": "model.chat",
    "payload": {"model": "gpt-4", "messages": [{"role": "user", "content": "Hello"}]}
})
print(resp.json())
```

---

*API 版本：v1.2*
*最后更新：2026-06-29*