heicode/docs/integration/agent-manager-swarm-runtime-change-request.md

Agent Manager / HeiCode-Swarm 蜂群对接改造请求

更新时间：2026-05-27 发起方：Heicode Manager
用途：给 Agent Manager / HeiCode-Swarm 侧确认需要补齐或对齐的生产接口，便于 Heicode 桌面客户端 -> Manager -> 蜂群 Runtime 跑完整蜂群流程。

一、当前 Manager 已准备好的能力

能力	Manager 状态
用户态创建	POST /api/agent/user/deployments、POST /api/swarms 已可创建 Manager deployment
Runtime 创建桥接	可通过 AGENT_RUNTIME_BASE_URL + AGENT_RUNTIME_CREATE_PATH 调用 Runtime
Runtime 停止桥接	可通过 AGENT_RUNTIME_STOP_PATH 停止 Runtime deployment
回调接收	POST /api/agent/callbacks/swarm-events 已支持事件、artifact、approval、timeline 回调
回调安全	支持 X-Agent-Service-Token 或 X-Agent-Signature HMAC
幂等	event_id / idempotency_key 去重
审批结果回传	用户 approve/reject 后，Manager 可调用 Runtime approval decision 接口
密钥边界	Manager 只传 secret_ref / credential_ref，不传长期明文密钥

二、Runtime 需要提供的接口

1. 健康检查

GET /api/agent/health

如果蜂群侧沿用现有 Orchestrator，也可以临时配置为：

GET /health

响应建议：

{
  "success": true,
  "data": {
    "status": "healthy",
    "service": "heicode-swarm-runtime",
    "version": "x.y.z"
  }
}

2. 创建 Swarm Run

生产目标接口：

POST /api/swarms
Authorization: Bearer <service_token>
X-Correlation-ID: <correlation_id>
X-Idempotency-Key: manager-<deployment_id>
Content-Type: application/json

Manager 当前也可兼容配置：

AGENT_RUNTIME_CREATE_PATH=/api/swarms

请求核心字段：

{
  "orchestration_plan": {
    "sub_mode": "agile",
    "risk_level": "high",
    "user_context": {
      "user_id": "22",
      "channel_id": "heicode"
    },
    "billing_context": {
      "provider": "newapi",
      "default_model_id": "model_xxx",
      "allowed_model_ids": ["model_xxx"],
      "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/model-gateway-key"
    },
    "agents": [],
    "resource_grants": []
  },
  "agents": [
    {
      "role": "backend",
      "resource_grants": []
    }
  ],
  "resource_grants": [
    {
      "grant_id": "grant-task-backend",
      "resource_type": "git",
      "permission_scope": ["read", "write"],
      "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main"
    }
  ],
  "callback": {
    "url": "https://code.xinghanlab.com/api/agent/callbacks/swarm-events",
    "signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agent-callback-signing-key",
    "subscribed_events": [
      "deployment.status_changed",
      "task.created",
      "task.claimed",
      "task.heartbeat",
      "task.completed",
      "task.failed",
      "handoff.requested",
      "approval.requested",
      "artifact.created",
      "timeline.updated"
    ]
  },
  "metadata": {
    "manager_deployment_id": "dep_xxx",
    "heicode_runtime_bridge": true,
    "correlation_id": "corr_xxx"
  }
}

响应必须返回至少一个 Runtime 标识：

{
  "success": true,
  "data": {
    "deployment_id": "runtime-dep-123",
    "swarm_id": "swarm-123",
    "status": "created"
  }
}

兼容要求：

1. deployment_id 可作为 Runtime deployment id。
2. swarm_id 用于蜂群任务图、审批和事件关联。
3. 如果 Runtime 只返回顶层 JSON，不包 data，Manager 也能解析。
4. 不要要求 Manager 发送长期明文密钥。

3. 停止 Runtime Run

默认路径：

POST /api/agent/deployments/{deployment_id}/stop
Authorization: Bearer <service_token>
Content-Type: application/json

请求：

{
  "reason": "Heicode Manager requested stop",
  "manager_deployment_id": "dep_xxx"
}

响应：

{
  "success": true,
  "data": {
    "deployment_id": "runtime-dep-123",
    "swarm_id": "swarm-123",
    "status": "stopped"
  }
}

如果蜂群侧希望使用：

POST /api/swarms/{swarm_id}/stop

则 Manager 可通过环境变量配置：

AGENT_RUNTIME_STOP_PATH=/api/swarms/{swarm_id}/stop

三、Runtime 回调 Manager

统一回调入口：

POST https://code.xinghanlab.com/api/agent/callbacks/swarm-events
X-Agent-Service-Token: <callback_token>
X-Agent-Event-Id: <event_id>
X-Correlation-ID: <correlation_id>
Content-Type: application/json

也支持 HMAC：

X-Agent-Timestamp: <unix_ms>
X-Agent-Signature: sha256=<hex>

签名内容：

timestamp + "." + event_id + "." + raw_body

通用事件 envelope

{
  "event_id": "evt_123",
  "idempotency_key": "evt_123",
  "event_type": "task.completed",
  "deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "agent_instance_id": "agent-backend-1",
  "task_id": "task-backend-1",
  "occurred_at": "2026-05-27T10:00:00Z",
  "correlation_id": "corr_xxx",
  "source": "heicode-swarm-runtime",
  "payload": {}
}

必须支持的事件类型：

event_type	用途
deployment.status_changed	Runtime 整体状态变化
task.created	任务图新增任务
task.claimed	Agent claim 任务
task.heartbeat	Agent 执行心跳
task.completed	任务完成
task.failed	任务失败
handoff.requested	任务交接
handoff.completed	交接完成
approval.requested	请求用户审批
artifact.created	产物生成
timeline.updated	用户可见时间线

artifact 回调

{
  "event_id": "evt_artifact_1",
  "event_type": "artifact.created",
  "deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "task_id": "task-backend-1",
  "artifact": {
    "artifact_id": "art_backend_patch_1",
    "artifact_type": "code_patch",
    "title": "Backend patch",
    "summary": "完成后端接口修改",
    "uri": "git://repo#agent-backend-1-results",
    "checksum": "sha256:xxx",
    "metadata": {
      "commit_sha": "abc123",
      "branch": "agent-backend-1-results",
      "redacted": true
    }
  }
}

approval 请求回调

{
  "event_id": "evt_approval_1",
  "event_type": "approval.requested",
  "deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "task_id": "task-deploy-1",
  "payload": {
    "approval_id": "runtime-approval-1",
    "operation": "production_deploy",
    "resource_id": "azure-prod",
    "resource_type": "cloud_resource",
    "resource_scope": "/subscriptions/.../resourceGroups/prod",
    "target_role": "ops",
    "risk_level": "high",
    "requires_credential": true,
    "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/azure-prod-sp",
    "ttl_seconds": 900,
    "reason": "部署到生产环境需要用户确认"
  }
}

四、Manager 回传审批结果给 Runtime

Manager 已支持调用该接口。蜂群侧需要实现接收。

默认路径：

POST /api/swarms/{swarm_id}/approvals/{approval_id}
Authorization: Bearer <service_token>
X-Correlation-ID: <correlation_id>
X-Idempotency-Key: approval-decision-<approval_id>-<decision>
Content-Type: application/json

Manager 可配置：

AGENT_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}

请求：

{
  "approval_id": "runtime-approval-1",
  "decision": "approved",
  "manager_deployment_id": "dep_xxx",
  "runtime_deployment_id": "runtime-dep-123",
  "swarm_id": "swarm-123",
  "operation": "production_deploy",
  "resource_id": "azure-prod",
  "resource_type": "cloud_resource",
  "resource_scope": "/subscriptions/.../resourceGroups/prod",
  "target_role": "ops",
  "risk_level": "high",
  "requires_credential": true,
  "credential_ref": "lease://agent/lease_xxx",
  "lease_id": "lease_xxx",
  "lease_expires_at": 1770000000000,
  "decided_by": "user:22",
  "reason": "用户确认部署",
  "decided_at": 1770000000000
}

拒绝时：

{
  "approval_id": "runtime-approval-1",
  "decision": "rejected",
  "manager_deployment_id": "dep_xxx",
  "runtime_deployment_id": "runtime-dep-123",
  "swarm_id": "swarm-123",
  "reason": "风险过高",
  "decided_by": "user:22",
  "decided_at": 1770000000000
}

安全要求：

1. Manager 不会在该请求中发送 secret_ref。
2. 如果审批通过且需要凭证，只发送短期 credential_ref = lease://agent/...。
3. Runtime 不得把 credential_ref、service token、签名密钥写入日志或 artifact metadata。
4. Runtime 收到 approved 后继续原高危动作；收到 rejected 后停止该动作并回调 timeline.updated 或 task.failed/blocked。

响应：

{
  "success": true,
  "data": {
    "approval_id": "runtime-approval-1",
    "status": "accepted"
  }
}

五、当前 HeiCode-Swarm 现状与建议

当前 HeiCode-Swarm 可见 Orchestrator 入口是：

当前入口	可用性	建议
GET /health	可直接作为健康检查	Manager AGENT_RUNTIME_HEALTH_PATH=/health
POST /tasks	可临时创建任务	只能做兼容桥接，不建议作为最终生产契约
GET /tasks	可查任务	后续需要映射到 callback/timeline
GET /agents	可查 Agent	后续需要回调 agent status
GET /handoffs	可查 handoff	后续需要回调 handoff events
GET /metrics	可查指标	后续需要按 deployment/swarm 关联
WS /ws/{agent_id}	Agent 内部通道	Manager 不直接接 WS

建议蜂群侧优先补正式 POST /api/swarms 和 approval decision 接口；如果短期只想先跑通，可由 Manager 临时把 create path 指到 /tasks，但这会缺少 secret_ref、resource grants、approval policy、artifact callback 等正式字段。

六、联调验收

最小验收顺序：

1. Manager 调 GET /api/agent/health 或 /health 返回 healthy。
2. Manager 调 Runtime create，拿到 runtime_deployment_id 和 swarm_id。
3. Runtime 回调 deployment.status_changed，Manager timeline 可见。
4. Runtime 回调 task.claimed、task.completed，Manager timeline 可见。
5. Runtime 回调 artifact.created，Manager artifacts 可见。
6. Runtime 回调 approval.requested，Manager/客户端能看到 pending approval。
7. 用户 approve/reject 后，Runtime 收到 approval decision。
8. Runtime 根据 decision 继续或停止，并回调最终结果。
9. 全链路无明文长期密钥、模型 key、云 access key、私钥、连接串。