# Gateway API 参考

## HTTP API

### Agent 生命周期

#### `POST /gateway/register`

注册 Agent 到 Gateway，并提供 Webhook 地址用于接收消息。

**请求体**：
```json
{
  "agent_id": "my-agent-001",
  "agent_name": "My Agent",
  "agent_type": "analyst",
  "capabilities": ["search", "analyze"],
  "description": "我的分析 Agent",
  "webhook_url": "http://my-agent.local:8080/webhook/a2a-messages"
}
```

**响应**：
```json
{
  "status": "registered",
  "agent_id": "my-agent-001"
}
```

**实现**：`gateway/core/router.py:GatewayRouter.register_agent`

---

#### `POST /gateway/heartbeat`

更新 Agent 心跳，保持在线状态。每 30 秒调用一次。

**请求体**：
```json
{
  "agent_id": "my-agent-001"
}
```

**响应**：
```json
{
  "status": "ok"
}
```

**实现**：`gateway/core/router.py:GatewayRouter.heartbeat`

---

#### `POST /gateway/unregister`

注销 Agent，标记为离线。

**请求体**：
```json
{
  "agent_id": "my-agent-001"
}
```

**响应**：
```json
{
  "status": "unregistered"
}
```

**实现**：`gateway/core/router.py:GatewayRouter.unregister_agent`

---

### Agent 查询

#### `GET /gateway/agents`

获取所有在线 Agent 列表。

**查询参数**：
- `agent_type` (可选): 过滤 Agent 类型
- `online_only` (可选, 默认 true): 只返回在线 Agent

**响应**：
```json
{
  "agents": [
    {
      "agent_id": "agent-001",
      "agent_name": "Research Agent",
      "agent_type": "analyst",
      "capabilities": ["search", "analyze"],
      "status": "online",
      "last_heartbeat": "2026-03-05T12:00:00Z"
    }
  ],
  "total": 1
}
```

**实现**：`gateway/core/router.py:GatewayRouter.list_agents`

---

#### `GET /gateway/status/{agent_id}`

查询指定 Agent 的在线状态。

**响应**：
```json
{
  "agent_id": "agent-001",
  "status": "online",
  "last_heartbeat": "2026-03-05T12:00:00Z"
}
```

**实现**：`gateway/core/router.py:GatewayRouter.get_agent_status`

---

### 消息发送

#### `POST /gateway/send`

发送消息到目标 Agent。Gateway 通过目标 Agent 注册的 Webhook 地址推送。

**请求体**：
```json
{
  "from_agent_id": "sender-001",
  "to_agent_id": "receiver-001",
  "conversation_id": "conv-abc-123",
  "content": [
    {"type": "text", "text": "Hello"}
  ],
  "metadata": {}
}
```

`conversation_id` 为空时自动生成。

**响应**：
```json
{
  "message_id": "msg-xyz-789",
  "conversation_id": "conv-abc-123",
  "status": "sent"
}
```

若目标 Agent 不在线：返回 `404`。
若 Webhook 调用失败：返回 `502`，Gateway 会记录失败原因。

**实现**：`gateway/core/router.py:GatewayRouter.send_message`

---

### Gateway 状态

#### `GET /gateway/health`

获取 Gateway 运行状态。

**响应**：
```json
{
  "status": "running",
  "version": "1.0.0",
  "uptime_seconds": 3600,
  "registered_agents": 5
}
```

---

## Webhook 推送格式

当目标 Agent 收到消息时，Gateway 会向其注册的 `webhook_url` 发送 HTTP POST 请求。

**请求体**：
```json
{
  "message_id": "msg-xyz-789",
  "conversation_id": "conv-abc-123",
  "from_agent_id": "sender-001",
  "content": [
    {"type": "text", "text": "Hello"}
  ],
  "metadata": {},
  "timestamp": "2026-03-05T12:00:00Z"
}
```

**期望响应**：HTTP 200，内容任意。

**Agent 端 Webhook 实现**：

```python
# api_server.py
@app.post("/webhook/a2a-messages")
async def receive_a2a_message(message: dict):
    message_queue.push(message)
    return {"status": "received"}
```

**实现**：`agent/tools/builtin/a2a_im.py:A2AMessageQueue`（待实现）

---

## Agent Card 格式

Agent Card 用于描述 Agent 的身份和能力，在注册时提供。

```json
{
  "agent_id": "agent-001",
  "agent_name": "Research Agent",
  "agent_type": "analyst",
  "capabilities": ["search", "analyze", "summarize"],
  "description": "专注于信息检索和分析的 Agent",
  "webhook_url": "http://agent.local:8080/webhook/a2a-messages",
  "metadata": {
    "version": "1.0.0",
    "owner": "team-a"
  }
}
```

**实现**：`gateway/core/registry.py:AgentConnection`

---

## 错误码

| HTTP 状态码 | 说明 |
|------------|------|
| `404` | 目标 Agent 不在线或不存在 |
| `400` | 请求格式错误 |
| `502` | Webhook 推送失败（目标 Agent 的 webhook 返回非 200） |
| `401` | 未授权访问（Enterprise 层） |
| `429` | 超过速率限制（Enterprise 层） |

---

## 配置参数

```python
# gateway_server.py
gateway = GatewayRouter(
    host="0.0.0.0",
    port=8001,
    heartbeat_timeout=60,    # 心跳超时（秒），超过则标记离线
    webhook_timeout=10,      # Webhook 推送超时（秒）
)
```

---

## 扩展点

### Enterprise 集成

Gateway 提供扩展点用于集成 Enterprise 层功能：

- **认证**：`gateway/enterprise/auth.py`（规划中）
- **审计**：`gateway/enterprise/audit.py`（规划中）
- **速率限制**：`gateway/enterprise/rate_limit.py`（规划中）

详见 [架构文档](./architecture.md#扩展点)。