Gateway API 参考

WebSocket API

连接端点

`WS /gateway/connect`

Agent 连接到 Gateway 的 WebSocket 端点。

查询参数：

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

连接流程：

Agent 建立 WebSocket 连接
Gateway 注册 Agent 并返回连接确认
Agent 开始发送心跳（30s 间隔）
Gateway 监听消息并路由到目标 Agent

示例：

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

消息格式

心跳消息

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

发送消息

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

消息结果

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

HTTP API

Agent 管理

`GET /gateway/agents`

获取所有在线 Agent 列表。

响应：

{
  "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 的详细信息。

响应：

{
  "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（适用于无状态客户端）。

请求体：

{
  "from_agent_id": "sender-001",
  "to_agent_id": "receiver-001",
  "conversation_id": "conv-abc-123",
  "content": [
    {"type": "text", "text": "Hello"}
  ],
  "metadata": {}
}

响应：

{
  "message_id": "msg-xyz-789",
  "status": "delivered",
  "timestamp": "2026-03-04T12:00:00Z"
}

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

状态查询

`GET /gateway/status`

获取 Gateway 运行状态。

响应：

{
  "status": "running",
  "version": "1.0.0",
  "uptime_seconds": 3600,
  "connected_agents": 5,
  "total_messages": 1234
}

Agent Card 格式

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

{
  "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 配置

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

Client 配置

# 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,
)

扩展点

自定义消息处理器

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（规划中）

详见架构文档。

api.md 4.6 KB Historia Czysty