# Gateway API 参考

## WebSocket API

### 连接端点

#### `WS /gateway/connect`

Agent 连接到 Gateway 的 WebSocket 端点。

**查询参数**：
- `agent_id` (必需): Agent 唯一标识符
- `agent_name` (可选): Agent 显示名称
- `capabilities` (可选): Agent 能力列表，JSON 数组格式

**连接流程**：
1. Agent 建立 WebSocket 连接
2. Gateway 注册 Agent 并返回连接确认
3. Agent 开始发送心跳（30s 间隔）
4. Gateway 监听消息并路由到目标 Agent

**示例**：
```python
from gateway.core.client import GatewayClient

client = GatewayClient(
    gateway_url="ws://localhost:8001",
    agent_id="my-agent-001",
    agent_name="My Agent"
)
await client.connect()
```

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

### 消息格式

#### 心跳消息

```json
{
  "type": "heartbeat",
  "timestamp": "2026-03-04T12:00:00Z"
}
```

#### 发送消息

```json
{
  "type": "send",
  "to_agent_id": "target-agent-001",
  "conversation_id": "conv-abc-123",
  "content": [
    {"type": "text", "text": "Hello"}
  ],
  "metadata": {}
}
```

#### 消息结果

```json
{
  "type": "result",
  "conversation_id": "conv-abc-123",
  "success": true,
  "result": "Response content",
  "metadata": {}
}
```

## HTTP API

### Agent 管理

#### `GET /gateway/agents`

获取所有在线 Agent 列表。

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

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

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

获取指定 Agent 的详细信息。

**响应**：
```json
{
  "agent_id": "agent-001",
  "agent_name": "Research Agent",
  "capabilities": ["search", "analyze"],
  "status": "online",
  "last_heartbeat": "2026-03-04T12:00:00Z",
  "connected_at": "2026-03-04T11:00:00Z"
}
```

### 消息发送

#### `POST /gateway/send`

通过 HTTP 发送消息到指定 Agent（适用于无状态客户端）。

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

**响应**：
```json
{
  "message_id": "msg-xyz-789",
  "status": "delivered",
  "timestamp": "2026-03-04T12:00:00Z"
}
```

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

### 状态查询

#### `GET /gateway/status`

获取 Gateway 运行状态。

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

## Agent Card 格式

Agent Card 用于描述 Agent 的身份和能力，在首次连接或查询时返回。

```json
{
  "agent_id": "agent-001",
  "agent_name": "Research Agent",
  "agent_type": "analyst",
  "capabilities": ["search", "analyze", "summarize"],
  "description": "专注于信息检索和分析的 Agent",
  "version": "1.0.0",
  "owner": {
    "user_id": "user-123",
    "device_id": "device-456"
  },
  "metadata": {
    "location": "PC-001",
    "timezone": "Asia/Shanghai"
  }
}
```

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

## 错误码

| 错误码 | 说明 |
|-------|------|
| `AGENT_NOT_FOUND` | 目标 Agent 不在线或不存在 |
| `INVALID_MESSAGE` | 消息格式错误 |
| `TIMEOUT` | 消息发送超时 |
| `UNAUTHORIZED` | 未授权访问（Enterprise 层） |
| `RATE_LIMIT` | 超过速率限制（Enterprise 层） |

## 配置参数

### Gateway 配置

```python
# gateway_server.py
gateway = GatewayRouter(
    host="0.0.0.0",
    port=8001,
    heartbeat_interval=30,  # 心跳间隔（秒）
    heartbeat_timeout=60,   # 心跳超时（秒）
)
```

### Client 配置

```python
# gateway/core/client.py
client = GatewayClient(
    gateway_url="ws://localhost:8001",
    agent_id="my-agent",
    agent_name="My Agent",
    capabilities=["search", "analyze"],
    auto_reconnect=True,
    reconnect_interval=5,
)
```

## 扩展点

### 自定义消息处理器

```python
from gateway.core.router import GatewayRouter

class CustomGateway(GatewayRouter):
    async def handle_custom_message(self, message: dict):
        # 自定义消息处理逻辑
        pass
```

### Enterprise 集成

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

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

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