Agent/gateway/docs/api.md

Gateway API 参考

HTTP API

Agent 生命周期

POST /gateway/register

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

请求体：

{
  "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"
}

响应：

{
  "status": "registered",
  "agent_id": "my-agent-001"
}

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

---

POST /gateway/heartbeat

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

请求体：

{
  "agent_id": "my-agent-001"
}

响应：

{
  "status": "ok"
}

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

---

POST /gateway/unregister

注销 Agent，标记为离线。

请求体：

{
  "agent_id": "my-agent-001"
}

响应：

{
  "status": "unregistered"
}

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

---

Agent 查询

GET /gateway/agents

获取所有在线 Agent 列表。

查询参数：

• agent_type (可选): 过滤 Agent 类型
• online_only (可选, 默认 true): 只返回在线 Agent

响应：

{
  "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 的在线状态。

响应：

{
  "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 地址推送。

请求体：

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

conversation_id 为空时自动生成。

响应：

{
  "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 运行状态。

响应：

{
  "status": "running",
  "version": "1.0.0",
  "uptime_seconds": 3600,
  "registered_agents": 5
}

---

Webhook 推送格式

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

请求体：

{
  "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 实现：

# 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 的身份和能力，在注册时提供。

{
  "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 层）

---

配置参数

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

详见 架构文档。