heicode-mananger/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. 健康检查

```http
GET /api/agent/health
```

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

```http
GET /health
```

响应建议：

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

### 2. 创建 Swarm Run

生产目标接口：

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

Manager 当前也可兼容配置：

```text
AGENT_RUNTIME_CREATE_PATH=/api/swarms
```

请求核心字段：

```json
{
  "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 标识：

```json
{
  "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

默认路径：

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

请求：

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

响应：

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

如果蜂群侧希望使用：

```http
POST /api/swarms/{swarm_id}/stop
```

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

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

## 三、Runtime 回调 Manager

统一回调入口：

```http
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：

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

签名内容：

```text
timestamp + "." + event_id + "." + raw_body
```

### 通用事件 envelope

```json
{
  "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 回调

```json
{
  "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 请求回调

```json
{
  "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 已支持调用该接口。蜂群侧需要实现接收。

默认路径：

```http
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 可配置：

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

请求：

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

拒绝时：

```json
{
  "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`。

响应：

```json
{
  "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、私钥、连接串。