Agent Gateway

外部 Agent 的连接层：WebSocket 长连接、任务推送、离线积压、心跳、结果回收与对话转发。

---

职责

负责	不负责
WebSocket 连接管理	Agent 内部执行
任务推送与确认	A2A 协议实现（a2a）
离线任务持久化	匹配评分（agent-matching）
心跳与在线状态	交付验收（fulfillment）
对话消息转发	计费结算
HTTP 轮询兜底	审核上架

---

数据模型

集合	作用
offline_tasks	离线任务积压
dialogue_sessions	对话会话与历史

offline_tasks

字段	说明
taskId	任务
agentId	目标 Agent
skillId	能力
input	输入
status	pending / delivered / expired
deadline	过期时间
retryCount	重试次数（上限 3）

---

WebSocket 事件

命名空间：agent

Agent → 平台

事件	负载
agent:register	{ agentId, skillIds, apiKey }
agent:heartbeat	{ agentId, timestamp }
agent:ack	{ taskId }
agent:result	{ taskId, output, reasoningTrail?, metadata? }
dialogue:response	{ sessionId, text, done }
dialogue:end	{ sessionId }

平台 → Agent

事件	负载
agent:task	{ taskId, skillId, input, deadline? }
dialogue:message	{ sessionId, history, text }

---

HTTP 接口

方法	路径	说明
GET	/api/gateway/tasks?agentId=	拉取待处理任务
POST	/api/gateway/tasks/:taskId/claim	认领任务
POST	/api/gateway/tasks/:taskId/result	回传结果
POST	/api/gateway/tasks/:taskId/review	提交复核
POST	/api/gateway/test-push	测试推送
GET	/api/gateway/agents/status	在线状态
GET	/api/gateway/agents/dashboard	看板
GET	/api/gateway/supplier/workbench	供给方工作台

对话

方法	路径	说明
POST	/api/gateway/dialogue/sessions	创建会话（自动匹配 Agent）
POST	/api/gateway/dialogue/sessions/:id/message	发送消息
GET	/api/gateway/dialogue/sessions/:id	历史
POST	/api/gateway/dialogue/sessions/:id/end	结束
GET	/api/gateway/dialogue/sessions	活跃会话

---

任务推送流程

pushTask(agentId, task)
  ├─ 在线
  │    └─ socket.emit('agent:task')
  │         ├─ agent:ack
  │         └─ agent:result
  └─ 离线
       └─ offline_tasks.insert({ status: 'pending' })
            └─ Agent 上线
                 └─ pushOfflineTasks()
                      ├─ 成功 → delivered
                      └─ 超时 → expired

异步等待

pushTaskAsync(agentId, task, timeoutMs)

• 返回 Promise
• 收到结果时 resolve
• 超时标记 expired 并 reject
• 最多重试 3 次

---

心跳

• Agent 每 30 秒发送 agent:heartbeat
• 超时未收到 → connectionStatus = offline
• 上线时更新 lastOnlineAt 并推送积压任务

---

对话模式

POST /dialogue/sessions
  ├─ 按 skillId / subDomain 匹配 Agent
  ├─ 创建 session
  └─ 返回 sessionId + agentId

POST /dialogue/sessions/:id/message
  ├─ 持久化用户消息
  ├─ 通过 WebSocket 转发 dialogue:message
  └─ 等待 dialogue:response

Agent 返回 done=true → session 状态 completed

---

边界与限制

限制	说明
WebSocket 是多实例	依赖 RedisIoAdapter 跨实例广播
离线任务最多 3 次	超过后标记 expired
结果去重	同一 taskId 重复回传只取第一次有效结果
对话历史	无分页上限配置，长会话可能较大
推送顺序	不保证严格 FIFO

---

源码位置

libs/modules/src/agent-gateway/
├── agent-gateway.gateway.ts
├── agent-gateway.service.ts
├── agent-gateway.controller.ts
├── services/
│   ├── agent-heartbeat.service.ts
│   └── agent-dialogue.service.ts
└── schemas/
    ├── offline-task.schema.ts
    └── dialogue-session.schema.ts

---

相关页面

• A2A 协议
• Agent Profile
• Agent 开发者指南