heicode-mananger/docs/integration/AgentManager蜂群Runtime接口实现要求.md

# Agent Manager 蜂群 Runtime 接口实现要求

更新时间：2026-05-28
面向对象：Agent Manager / HeiCode-Swarm Runtime 开发负责人
用途：Agent Manager 按本文实现接口、字段和回调后，Heicode Manager 可直接联调蜂群模式。

## 1. 结论

Heicode Manager 已负责控制面和记录面：

- 生成 deployment / swarm 创建请求。
- 传递 `resource_grants`、`secret_ref`、预算、模型网关上下文和 callback 地址。
- 保存 `deployment_id <-> runtime_deployment_id <-> swarm_id` 映射。
- 接收 Runtime callback，落库 artifact / approval / timeline / audit。
- 用户 approve/reject 后，把审批决定回传 Runtime。

Agent Manager / Swarm Runtime 需要负责执行层：

- 创建真实 Swarm Run。
- 生成真实 task graph。
- 管理 Agent claim / heartbeat / handoff / retry / blocked / failed 状态机。
- 真实执行任务并产出 artifact。
- 在高危动作前暂停并回调审批请求。
- 接收审批结果后继续或停止。
- 回传日志、指标、用量和最终结果。

### 1.1 2026-05-28 生产联调实测结论

使用测试用户 `zsbgnw@gmail.com`（Manager 用户 `chenchen`，`user_id=22`）在生产 Manager 上实测蜂群入口。

当前生产 Manager Runtime 配置实际为：

```text
AGENT_RUNTIME_BASE_URL=http://20.212.121.126
AGENT_RUNTIME_CREATE_PATH=/api/agent/deployments
AGENT_RUNTIME_STOP_PATH=/api/agent/deployments/{deployment_id}/stop
```

实测结果：

| 项 | 结果 |
|---|---|
| `GET /api/agent/runtime/health` | 通过，远端 Agent Manager IP healthy |
| `POST /api/swarms` 使用 `agent_runtime.platform=agent-swarm` | 失败，Manager 返回 `agent_runtime.platform must be agent when runtime context is present` |
| `POST /api/swarms` 使用 `agent_runtime.platform=agent` | 通过 |
| Manager deployment | `dep_72cdc138b9c8` |
| Manager 返回 swarm_id | `dep_72cdc138b9c8`，当前是 Manager 本地 deployment id |
| Runtime deployment | `dep_77370f27186f` |
| Manager events | `deployment.accepted`、`runtime.sync.started`、`runtime.sync.accepted` |
| Manager stop | 通过 |
| Runtime stop | 通过，Agent Manager 侧 `dep_77370f27186f` 状态为 `stopped` |
| Runtime callback | 未观察到，生产 Manager callback 表 0 条对应记录 |
| artifact / timeline callback | 未产出 |
| SK / usage callback | 未产出 |
| Runtime logs | 仅 `Pod ... has no logs yet` |
| Runtime metrics | 返回固定 CPU/内存/网络汇总，看起来仍是占位值 |

结论：

1. Heicode Manager 的 `/api/swarms` adapter 能接收用户态蜂群请求，并能通过当前 Runtime bridge 调 Agent Manager IP。
2. 当前生产链路实际走的是 Agent Manager `/api/agent/deployments`，不是 Agent Manager `/api/swarms`。
3. Manager stop 可以传递到 Agent Manager deployment stop。
4. 当前还没有真实蜂群 Runtime callback、task graph、artifact、SK、usage。
5. Agent Manager 如果要满足正式蜂群模式，仍需实现本文后续定义的 `/api/swarms`、`/api/swarms/{swarm_id}`、`/api/swarms/{swarm_id}/stop`、callback 和 usage 约束。

## 2. 总体调用链

```text
Heicode Desktop Client
  -> Heicode Manager
     POST /api/swarms 或 /api/agent/user/deployments
  -> Agent Manager / Swarm Runtime
     POST /api/swarms
  <- Runtime response
     runtime_deployment_id / swarm_id / status
  <- Runtime callback
     POST /api/agent/callbacks/swarm-events
  -> Runtime approval decision
     POST /api/swarms/{swarm_id}/approvals/{approval_id}
```

客户端到 Heicode Manager 的 `POST /api/swarms` 与普通 sub 用户态接口一样，必须支持 V2 body 加密：

```http
Content-Encoding: heicode-aead-v1
X-Heicode-Device-Id: <device_id>
X-Heicode-Timestamp: <unix_ms>
X-Heicode-Nonce: <nonce_hex>
X-Heicode-Fingerprint: <device_fingerprint>
X-Heicode-Eph-Pubkey: <base64_x25519_ephemeral_pubkey>
X-Heicode-Signature: <base64_ed25519_signature>
Content-Type: application/json
```

未加密 Web 控制台请求仍按 Manager session cookie + `New-Api-User` 兼容处理。Manager 调 Agent Manager / Swarm Runtime 的服务间请求不使用该客户端 body 加密协议，而使用 `Authorization: Bearer <service_token>` 和公共追踪 Header。

## 3. Agent Manager 必须提供的接口

| 优先级 | 方法 | 路径 | 必须 | 用途 |
|---|---|---|---:|---|
| P0 | `GET` | `/api/agent/health` | 是 | 健康检查 |
| P0 | `POST` | `/api/swarms` | 是 | 创建真实 Swarm Run |
| P0 | `POST` | `/api/swarms/{swarm_id}/stop` | 是 | 停止 Swarm Run |
| P0 | `POST` | `/api/swarms/{swarm_id}/approvals/{approval_id}` | 是 | 接收 Manager 审批决定 |
| P0 | callback | Manager `/api/agent/callbacks/swarm-events` | 是 | 回写状态、task、handoff、artifact、approval |
| P1 | `GET` | `/api/swarms/{swarm_id}` | 建议 | 查询 Runtime 详情 |
| P1 | `GET` | `/api/swarms/{swarm_id}/tasks` | 建议 | 查询 task graph |
| P1 | `GET` | `/api/swarms/{swarm_id}/logs` | 建议 | 查询日志 |
| P1 | `GET` | `/api/swarms/{swarm_id}/metrics` | 建议 | 查询指标 |

如果短期无法提供 `/api/swarms`，可以临时确认兼容路径，例如 `/tasks`。但这只能作为联调过渡，不作为最终生产契约。

## 4. 认证与公共 Header

Manager 调 Agent Manager 时携带：

```http
Authorization: Bearer <service_token>
X-User-ID: <manager_user_id>
X-Binding-Scope: <binding_scope>
X-Correlation-ID: <correlation_id>
X-Idempotency-Key: manager-<manager_deployment_id>
Content-Type: application/json
```

要求：

1. `Authorization` 用于服务间鉴权。
2. `X-Correlation-ID` 必须贯穿 create、callback、approval decision、logs、metrics。
3. `X-Idempotency-Key` 必须支持幂等；重复创建请求不能生成多个真实 Swarm Run。
4. Agent Manager 不得要求 Manager 传长期明文密钥。

## 5. `GET /api/agent/health`

### 响应

```json
{
  "success": true,
  "data": {
    "status": "healthy",
    "service": "agent-manager-swarm-runtime",
    "version": "1.0.0",
    "runtime": "aks",
    "time": "2026-05-28T10:00:00Z"
  }
}
```

验收：

- HTTP 200。
- `status` 为 `healthy` / `ok` / `up` 之一。
- 不返回密钥、Token、连接串。

## 6. `POST /api/swarms`

### 请求体

```json
{
  "orchestration_plan": {
    "intent_id": "task_123",
    "template_hint": "heicode-task",
    "objective": "完成本轮用户目标",
    "sub_mode": "agile",
    "risk_level": "medium",
    "budget": {
      "max_tokens": 120000,
      "max_cost_usd": 8,
      "max_duration_sec": 3600
    },
    "user_context": {
      "user_id": "22",
      "channel_id": "heicode",
      "binding_scope": "task-task-123"
    },
    "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"
    },
    "agile_context": {
      "iteration": "2026-05-28",
      "stage": "development",
      "checkpoint": "draft_created",
      "acceptance_criteria": [
        "接口返回成功",
        "artifact 可回写到 timeline",
        "不出现明文密钥"
      ],
      "next_action": "continue",
      "requires_user_approval": false
    },
    "agents": [
      {
        "role_template": "backend",
        "goal": "完成后端实现和测试",
        "default_model_id": "model_xxx",
        "resource_grants": []
      }
    ],
    "resource_grants": []
  },
  "agents": [
    {
      "role": "backend",
      "resource_grants": []
    }
  ],
  "resource_grants": [
    {
      "grant_id": "grant-task-123-git",
      "resource_id": "repo-main",
      "resource_type": "git",
      "permission_scope": ["repo:read", "repo:write:feature-branches"],
      "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main",
      "ref": "azkv://heicode-kv.vault.azure.net/secrets/repo-main",
      "target_role": "backend",
      "constraints": {
        "allowed_paths": "heicode/**"
      },
      "metadata": {
        "repo": "heicode-manager"
      }
    }
  ],
  "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.blocked",
      "task.retried",
      "task.failed",
      "task.completed",
      "handoff.requested",
      "handoff.completed",
      "approval.requested",
      "artifact.created",
      "timeline.updated",
      "budget.alert"
    ]
  },
  "metadata": {
    "manager_deployment_id": "dep_xxx",
    "heicode_deployment_id": "dep_xxx",
    "heicode_runtime_bridge": true,
    "correlation_id": "corr_xxx"
  }
}
```

### Agent Manager 必须消费的字段

| 字段 | 必须 | 说明 |
|---|---:|---|
| `orchestration_plan.objective` | 是 | 用户目标 |
| `orchestration_plan.sub_mode` | 是 | `agile` / `waterfall`；蜂群执行时也要保留此组织方式 |
| `orchestration_plan.risk_level` | 是 | 高危动作必须走审批 |
| `orchestration_plan.budget` | 是 | token / cost / duration 上限 |
| `billing_context.provider` | 是 | 当前为 `newapi` |
| `billing_context.secret_ref` | 是 | 模型网关密钥引用，只能是 `azkv://...` |
| `agents[].role` 或 `role_template` | 是 | 子 Agent 角色 |
| `resource_grants[]` | 是 | 资源授权清单 |
| `resource_grants[].secret_ref` | 凭据资源必填 | 只允许 Key Vault 引用，不允许明文 |
| `callback.url` | 是 | Runtime 回调 Manager 的地址 |
| `callback.signing_secret_ref` | 建议 | HMAC 签名密钥引用 |
| `metadata.manager_deployment_id` | 是 | Manager 侧 deployment id |
| `metadata.correlation_id` | 是 | 全链路追踪 |

### 响应

```json
{
  "success": true,
  "data": {
    "deployment_id": "runtime-dep-123",
    "swarm_id": "swarm-123",
    "status": "running",
    "created_at": "2026-05-28T10:00:00Z",
    "estimated_ready_at": "2026-05-28T10:02:00Z"
  }
}
```

兼容响应：

```json
{
  "deployment_id": "runtime-dep-123",
  "swarm_id": "swarm-123",
  "status": "running"
}
```

Manager 映射规则：

| Agent Manager 返回字段 | Manager 保存字段 |
|---|---|
| `data.deployment_id` / `deployment_id` / `id` | `runtime_deployment_id` |
| `data.swarm_id` / `swarm_id` / `runtime_swarm_id` | `runtime_swarm_id` |
| `data.status` / `status` / `runtime_status` | `runtime_state` |

## 7. Runtime 必须生成的 task graph

Agent Manager 创建 Swarm Run 后，必须在 Runtime 内部生成任务图，并通过 callback 回写。

每个 task 至少包含：

```json
{
  "task_id": "task-backend-1",
  "title": "实现后端接口",
  "description": "完成 API、校验和测试",
  "agent_role": "backend",
  "status": "pending",
  "depends_on": ["task-design-1"],
  "attempt": 1
}
```

状态建议：

| status | 说明 |
|---|---|
| `pending` | 等待执行 |
| `claimed` | 已被 Agent 领取 |
| `running` | 执行中 |
| `blocked` | 阻塞 |
| `handoff_requested` | 等待交接 |
| `retrying` | 重试中 |
| `completed` | 完成 |
| `failed` | 失败 |

## 8. Runtime 回调 Manager

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

HMAC 签名内容：

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

联调前可拉取 Manager 当前接受的事件 schema：

```http
GET https://code.xinghanlab.com/api/agent/callbacks/swarm-events/schema
```

### 通用 callback envelope

```json
{
  "event_id": "evt_123",
  "idempotency_key": "evt_123",
  "event_type": "task.claimed",
  "deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "agent_instance_id": "agent-backend-1",
  "task_id": "task-backend-1",
  "occurred_at": "2026-05-28T10:10:00Z",
  "correlation_id": "corr_xxx",
  "source": "agent-manager-runtime",
  "payload": {}
}
```

要求：

1. `event_id` 全局唯一。
2. 重试同一事件必须复用相同 `event_id` 或 `idempotency_key`。
3. `deployment_id` 优先使用 Manager deployment id。
4. 如果只知道 `swarm_id`，Manager 也会按 `runtime_swarm_id` 查找 deployment。
5. `source` 要能区分真实 Runtime，例如 `agent-manager-runtime`，不要写 `simulated`。

## 9. 必须回调的事件和字段

| event_type | 必填字段 | 说明 |
|---|---|---|
| `deployment.status_changed` | `payload.status` | Runtime 整体状态变化 |
| `task.created` | `task_id`, `payload.title` | 任务图新增任务 |
| `task.claimed` | `task_id`, `payload.agent_role` | Agent 领取任务 |
| `task.running` | `task_id`, `payload.agent_role` | Agent 开始执行 |
| `task.heartbeat` | `task_id`, `payload.agent_role` | Agent 心跳 |
| `task.blocked` | `task_id`, `payload.reason` | 任务阻塞 |
| `task.retried` | `task_id`, `payload.attempt` | 任务重试 |
| `task.failed` | `task_id`, `payload.reason` | 任务失败 |
| `task.completed` | `task_id` | 任务完成 |
| `handoff.requested` | `task_id`, `payload.from_role`, `payload.to_role` | 请求交接 |
| `handoff.completed` | `task_id`, `payload.from_role`, `payload.to_role` | 完成交接 |
| `artifact.created` | `artifact.artifact_id` 或 `payload.artifact_id` | 产物生成 |
| `approval.requested` | `payload.approval_id`, `payload.operation`, `payload.risk_level` | 高危审批 |
| `timeline.updated` | `payload.title` | 用户可见时间线 |
| `budget.alert` | `payload.threshold_pct` | 预算告警 |

## 10. artifact.created

Runtime 产生中间产物或最终交付物时回调：

```json
{
  "event_id": "evt_artifact_1",
  "event_type": "artifact.created",
  "deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "task_id": "task-backend-1",
  "source": "agent-manager-runtime",
  "artifact": {
    "artifact_id": "art_backend_patch_1",
    "artifact_type": "code_patch",
    "title": "Backend API patch",
    "summary": "新增任务创建和状态查询接口",
    "uri": "git://heicode-manager/branches/feature/task-api",
    "checksum": "sha256:abc123",
    "metadata": {
      "agent_role": "backend",
      "redacted": true
    }
  }
}
```

支持的 `artifact_type`：

| 类型 | 说明 |
|---|---|
| `code_patch` | 代码补丁或分支 |
| `document` | 文档 |
| `test_report` | 测试报告 |
| `deployment_manifest` | 部署清单 |
| `log_bundle` | 日志包 |
| `other` | 其他 |

要求：

1. 大文件不要内联到 callback body。
2. `summary` 可展示给用户，不得包含密钥。
3. `uri` 可以是 `git://`、`artifact://`、`azblob://`、`https://`。
4. metadata 必须脱敏。

## 11. approval.requested 与审批结果

高危动作前 Runtime 必须暂停，并回调：

```json
{
  "event_id": "evt_approval_1",
  "event_type": "approval.requested",
  "deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "task_id": "task-deploy-1",
  "source": "agent-manager-runtime",
  "payload": {
    "approval_id": "runtime-approval-1",
    "operation": "deploy.production",
    "resource_id": "prod-env",
    "resource_type": "azure",
    "resource_scope": "resource-group/heicode-prod",
    "target_role": "ops",
    "risk_level": "high",
    "requires_credential": true,
    "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/prod-deploy",
    "ttl_seconds": 600,
    "reason": "需要部署到生产环境"
  }
}
```

Manager / 客户端审批后，Manager 调 Runtime：

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

请求：

```json
{
  "approval_id": "runtime-approval-1",
  "decision": "approved",
  "reason": "用户已确认",
  "manager_deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "decided_by": "user:22",
  "decided_at": "2026-05-28T10:20:00Z",
  "credential_lease": {
    "lease_id": "lease_xxx",
    "credential_ref": "lease://runtime/runtime-approval-1",
    "expires_at": "2026-05-28T10:30:00Z"
  }
}
```

`decision` 枚举：

| decision | Runtime 行为 |
|---|---|
| `approved` | 继续原高危动作 |
| `rejected` | 停止该动作，回调 `timeline.updated` 或 `task.failed` |

要求：

1. Runtime 收到 `approved` 后才可以继续高危动作。
2. Runtime 收到 `rejected` 后不能继续执行该动作。
3. Runtime 不得把 `credential_ref` 展开写入日志或 artifact metadata。
4. Runtime 必须把审批结果后的状态继续通过 callback 回写。

## 12. 日志、指标和用量

### 日志

建议提供：

```http
GET /api/swarms/{swarm_id}/logs?limit=100&cursor=<cursor>
```

响应：

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "timestamp": "2026-05-28T10:21:00Z",
        "level": "info",
        "agent_role": "backend",
        "task_id": "task-backend-1",
        "message": "test completed",
        "redacted": true
      }
    ],
    "next_cursor": ""
  }
}
```

### 指标

建议提供：

```http
GET /api/swarms/{swarm_id}/metrics?window=15m&step=60s
```

响应：

```json
{
  "success": true,
  "data": {
    "swarm_id": "swarm-123",
    "agent_metrics": [
      {
        "agent_instance_id": "agent-backend-1",
        "agent_role": "backend",
        "task_id": "task-backend-1",
        "status": "running",
        "cpu_percent": 12.5,
        "memory_bytes": 268435456,
        "uptime_seconds": 300
      }
    ]
  }
}
```

### 用量

Runtime 调模型时必须带关联字段：

| 字段 | 说明 |
|---|---|
| `manager_deployment_id` | Manager deployment id |
| `swarm_id` | Runtime swarm id |
| `task_id` | 当前任务 |
| `agent_role` | Agent 角色 |
| `model_id` | 使用模型 |
| `correlation_id` | 全链路追踪 |

Runtime 可通过 `budget.alert` 或 `timeline.updated` 回传用量摘要。

## 13. 安全约束

必须遵守：

1. 禁止在请求、callback、日志、artifact metadata 中出现明文密码、Token、私钥、连接串、云 access key、模型 key。
2. 长期凭据只能通过 `azkv://<vault>/secrets/<name>` 传引用。
3. Runtime 可以把短期租约写成 `lease://...`，但不能写真实密钥。
4. `secret_ref`、`credential_ref` 只能作为引用使用，不能在用户可见内容中展开。
5. 所有 callback payload 必须脱敏。
6. 高危动作必须先 `approval.requested`，不能先执行后补审批。

## 14. 错误码建议

| HTTP | code | 场景 |
|---:|---|---|
| 401 | `UNAUTHORIZED` | service token 无效 |
| 403 | `FORBIDDEN` | 权限不足 |
| 404 | `SWARM_NOT_FOUND` | swarm 不存在 |
| 409 | `IDEMPOTENCY_CONFLICT` | 幂等键冲突 |
| 422 | `VALIDATION_ERROR` | 请求字段缺失 |
| 422 | `SECRET_REF_INVALID` | `secret_ref` 非 `azkv://...` |
| 422 | `POLICY_REJECTED` | 高危策略拒绝 |
| 500 | `INTERNAL_ERROR` | Runtime 内部错误 |

错误响应：

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "resource_grants[0].secret_ref is required",
    "request_id": "corr_xxx"
  }
}
```

## 15. 联调验收清单

| 步骤 | 操作 | 通过标准 |
|---:|---|---|
| 1 | Manager 调 `GET /api/agent/health` | 返回 healthy |
| 2 | Manager 调 `POST /api/swarms` | 返回真实 `deployment_id` 和 `swarm_id` |
| 3 | Runtime 回调 `deployment.status_changed` | Manager timeline 可见 |
| 4 | Runtime 回调 `task.created` | Manager task flow / Agent task map 可见 |
| 5 | Runtime 回调 `task.claimed` / `task.heartbeat` | Manager 可看到 Agent 领取和心跳 |
| 6 | Runtime 回调 `handoff.requested` / `handoff.completed` | Manager 可看到交接 |
| 7 | Runtime 回调 `artifact.created` | Manager artifact 列表可见 |
| 8 | Runtime 回调 `approval.requested` | Manager approval 列表出现 pending |
| 9 | 客户端 / Manager approve | Runtime 收到 decision 并继续 |
| 10 | 客户端 / Manager reject | Runtime 收到 decision 并停止对应动作 |
| 11 | Runtime 回传 logs / metrics / usage | Manager 可查询或 timeline 可见 |
| 12 | Runtime 回调最终 `deployment.status_changed=completed` | Manager 和客户端看到完成 |

## 16. 当前不能误报完成的项

以下项只有在 Agent Manager 真实实现并联调后才能算完成：

1. 真实 Swarm Run 创建成功。
2. 真实 task graph 生成。
3. 真实 Agent claim / heartbeat。
4. 真实 handoff / retry / blocked。
5. 真实 artifact 产出。
6. 审批后 Runtime 继续或停止。
7. Runtime 真实日志和指标。
8. 子 Agent 模型用量归属。
9. 最终交付物回到客户端。

Manager 本地模拟事件、测试桩、空态页面和 schema 校验只能证明 Manager 接收和展示能力，不能证明蜂群生产闭环完成。