heicode-mananger/docs/integration/AgentManager蜂群Runtime联调待确认与补充要求.md

# Agent Manager 蜂群 Runtime 联调待确认与补充要求

更新时间：2026-05-29  
发给：Agent Manager / HeiCode-Swarm Runtime 负责人  
范围：仅针对蜂群模式，不包含普通 sub 敏捷模式。

## 1. 先明确边界

普通 sub 模式和蜂群模式是两套不同的运行时部署，不能混用。

| 模式 | Runtime | 当前已知地址 | 说明 |
|---|---|---|---|
| 普通 sub 敏捷模式 | Agent Manager / Agent Runtime | `http://20.212.121.126` | 用于普通子 Agent 敏捷开发流程 |
| 蜂群模式 | HeiCode-Swarm Orchestrator | `http://52.139.240.116:8000` | 用于蜂群任务图、Agent 协作、handoff、task graph |

注意：两套服务可能都提供 `/api/swarms` 这类路径，但业务含义不同。Heicode Manager 后续需要按模式分别配置，不应只用一套 `AGENT_RUNTIME_BASE_URL` 混跑。

## 2. 本次读取到的蜂群 Runtime 新能力

根据 HeiCode-Swarm 最新 `蜂群对接文档.md` 和代码，蜂群 Runtime 已经补充以下接口：

| 能力 | 路径 | 当前判断 |
|---|---|---|
| 健康检查 | `GET /api/agent/health` | 已提供 |
| 创建蜂群 run | `POST /api/swarms` | 已提供 |
| 兼容创建入口 | `POST /api/agent/deployments` | 已提供 |
| 查询 swarm 详情 | `GET /api/swarms/{swarm_id}` | 已提供 |
| 查询任务图 | `GET /api/swarms/{swarm_id}/tasks` | 已提供 |
| 查询日志 | `GET /api/swarms/{swarm_id}/logs` | 已提供 |
| 查询指标 | `GET /api/swarms/{swarm_id}/metrics` | 已提供 |
| 停止 swarm | `POST /api/swarms/{swarm_id}/stop` | 已提供 |
| 审批结果回传 | `POST /api/swarms/{swarm_id}/approvals/{approval_id}` | 已提供 |
| callback token / HMAC | Runtime callback Manager | 代码支持 |
| `azkv://` 校验 | 请求体 secret 引用 | 代码支持 |
| 幂等创建 | `X-Idempotency-Key` | 代码支持 |

本地契约测试也已确认通过：

```text
python3 scripts/test-runtime-contract.py
runtime contract checks passed
```

## 3. 实测结果

### 3.1 健康检查通过

请求：

```bash
curl http://52.139.240.116:8000/api/agent/health
```

返回核心内容：

```json
{
  "success": true,
  "data": {
    "status": "healthy",
    "service": "heicode-swarm-runtime",
    "version": "1.0.0",
    "runtime": "aks",
    "capabilities": [
      "swarm.create",
      "task.flow",
      "handoff.events",
      "artifact.events",
      "approval.pause_resume",
      "deployment.stop",
      "runtime.tasks.query",
      "runtime.logs.query",
      "runtime.metrics.query"
    ]
  }
}
```

### 3.2 创建接口鉴权已通过

Agent Manager / 蜂群 Runtime 已提供当前部署认可的 Runtime Bearer token。使用该 token 后，`POST /api/swarms` 不再返回 401。

```bash
curl -X POST http://52.139.240.116:8000/api/swarms \
  -H "Authorization: Bearer <runtime-service-token>" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-Id: corr_token_check_local" \
  -H "X-Idempotency-Key: codex-swarm-token-check" \
  -d '<valid-swarm-create-body>'
```

返回：

```json
{
  "success": true,
  "data": {
    "deployment_id": "runtime-dep-e9ef617146fd",
    "runtime_deployment_id": "runtime-dep-e9ef617146fd",
    "manager_deployment_id": "dep_token_check_local",
    "swarm_id": "swarm-64004a6aaf67",
    "status": "running",
    "created": true
  }
}
```

结论：Runtime token 阻塞已解决。具体 token 不写入 Markdown 或 Git。

### 3.3 查询和停止接口已通过

对 `swarm-64004a6aaf67` 查询结果：

| 接口 | 结果 |
|---|---|
| `GET /api/swarms/{swarm_id}` | 成功，返回 Runtime run 详情 |
| `GET /api/swarms/{swarm_id}/tasks` | 成功 |
| `GET /api/swarms/{swarm_id}/logs` | 成功，返回 Runtime event 列表 |
| `GET /api/swarms/{swarm_id}/metrics` | 成功，返回任务数、运行时长、Agent 数等轻量指标 |
| `POST /api/swarms/{swarm_id}/stop` | 成功，状态变为 `stopped` |

### 3.4 新发现：线上蜂群 Runtime 仍只生成单任务

2026-05-29 已按 `HeiCode-Swarm/蜂群对接文档.md` 的结构真实请求线上蜂群 Runtime：

```text
POST http://52.139.240.116:8000/api/swarms
Authorization: Bearer <runtime-service-token>
```

第一组使用文档中的单 Agent 结构，`agents` 放在 `orchestration_plan.agents`，角色为 `backend`。创建成功：

```json
{
  "success": true,
  "data": {
    "runtime_deployment_id": "runtime-dep-fc99510eb2c5",
    "manager_deployment_id": "dep_doc_single",
    "swarm_id": "swarm-004f1ae3a114",
    "status": "running"
  }
}
```

但查询任务后，线上 Runtime 没有保留文档请求中的 `backend` 角色，而是生成 `general` 单任务：

```json
{
  "task_id": "swarm-004f1ae3a114-task-1",
  "title": "Swarm objective",
  "agent_role": "general",
  "context": {
    "workflow_mode": "single_agent",
    "allow_handoff": false
  }
}
```

第二组使用同样文档结构，但传入 3 个 agents：`planner`、`builder`、`reviewer`。创建成功：

```json
{
  "success": true,
  "data": {
    "runtime_deployment_id": "runtime-dep-ba9de6fe1df3",
    "manager_deployment_id": "dep_doc_multi",
    "swarm_id": "swarm-ee319f1d4705",
    "status": "running"
  }
}
```

但查询任务后仍只生成 1 个 `general` 任务：

```json
{
  "tasks": [
    {
      "title": "Swarm objective",
      "agent_role": "general",
      "status": "pending",
      "task_graph_id": "task-1",
      "context": {
        "workflow_mode": "single_agent",
        "allow_handoff": false
      }
    }
  ]
}
```

两组测试的日志均只出现 `Created 1 task(s)`，停止接口均返回 `status=stopped`。

这与蜂群设计要求的“动态任务图、能力编队、handoff、协作任务链”仍有差距。当前线上 Runtime 看起来仍是 single-agent fallback 路径，尚未按请求中的 3 个 planner/builder/reviewer 任务生成真实 task graph。

### 3.5 Gitee main 与线上 Runtime 行为不一致

已检查项目地址：

```text
http://gitee.ath.cx:3000/taijibaga/HeiCode-Swarm
```

当前 main commit：

```text
802bbe97ca278d2da3c70a3e471219db62c01c98 对接文档
```

仓库 main 中 `orchestrator/swarm_runtime.py` 的 `build_task_descriptions()` 逻辑会读取：

```python
agents = plan.get("agents") or body.get("agents") or []
```

如果请求里传入 3 个 agents，本地按同样 payload 测试该函数，结果会生成 3 个任务：

```text
plan-1   planner
build-1  builder
verify-1 reviewer
count=3
```

但线上 `http://52.139.240.116:8000` 对同样结构只生成：

```text
task-1 general
workflow_mode=single_agent
allow_handoff=false
```

另外，线上返回中的 `workflow_mode`、`allow_handoff`、`required_capabilities`、`source=runtime_bridge` 等字段，在当前 Gitee main 的 `orchestrator/swarm_runtime.py` 中没有对应代码。

因此当前判断是：

1. 线上 `52.139.240.116:8000` 运行的镜像/代码不是 Gitee main 当前代码；或
2. 线上部署使用了未提交到 Gitee main 的分支/镜像；或
3. 线上通过环境变量或另一套 runtime bridge 强制走 single-agent fallback。

请 Agent Manager / HeiCode-Swarm 负责人确认线上部署的镜像 tag、代码 commit、分支，以及是否启用了 single-agent fallback 配置。

## 4. Agent Manager / 蜂群 Runtime 需要提供或确认

### P0 必须先提供

| 项 | 需要提供 / 确认 | 原因 |
|---|---|---|
| 蜂群 Runtime 调用 token | 已提供并验证可用；后续需要通过安全渠道配置到 Manager，不写入 Git | Manager 调 `POST /api/swarms` 需要 Bearer 鉴权 |
| callback 凭据配置 | Runtime 配置 Manager 认可的 `AGENT_CALLBACK_SERVICE_TOKEN` 或 `AGENT_CALLBACK_SIGNING_SECRET` | Runtime 回调 Manager 必须通过鉴权 |
| 两套部署边界 | 明确普通 sub 继续走 `20.212.121.126`，蜂群走 `52.139.240.116:8000` | 防止普通 sub 和蜂群混用 |
| 创建响应字段 | `deployment_id`、`runtime_deployment_id`、`swarm_id`、`status` 字段保持稳定 | Manager 需要保存映射 |
| callback deployment id 规则 | callback 中 `deployment_id` 应为 Manager deployment id，`runtime_deployment_id` 为 Runtime id，`swarm_id` 为 Runtime swarm id | Manager 根据这些字段落库和展示 |

callback 地址：

```text
https://code.xinghanlab.com/api/agent/callbacks/swarm-events
```

callback schema 查询：

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

说明：具体 token / signing secret 不应写入 Markdown 或 Git，请通过安全渠道提供。

### P0 端到端能力

| 能力 | 当前情况 | 需要补充或证明 |
|---|---|---|
| Manager 创建蜂群 run | Runtime 直连创建已跑通；Manager 生产尚未切蜂群专用配置 | 将 Runtime token 安全配置到 Manager 后跑真实 Manager 创建 |
| 动态任务图 | 当前线上 Runtime 只生成 1 个 `general` 任务，`workflow_mode=single_agent` | 至少根据目标生成 2-3 个可追踪任务，并回调多条 `task.created` |
| Agent claim / running / heartbeat | 代码里有 dispatch 和事件能力 | 需要真实 Agent 连接、claim、running、heartbeat 证据 |
| handoff | 事件类型和部分逻辑存在 | 需要真实 `handoff.requested` / `handoff.completed` 场景 |
| 失败回流 | 有 `task.blocked`、`task.failed`、`task.retried` 事件类型 | 需要一次真实失败、重试或 blocked 证据 |
| artifact | Agent 返回 `git_branch` 时会发 artifact | 需要真实 `artifact.created` 回 Manager，带 `uri`、`summary`、`artifact_type` |
| 审批暂停 / 恢复 | high risk 会 `waiting_approval`，支持 decision 接口 | 需要真实 `approval.requested` -> Manager approve/reject -> Runtime 继续/阻塞 |
| 日志 | `/logs` 当前主要来自 Runtime 事件 | 需要说明是否提供真实 Agent / Pod 日志，或至少返回可排障日志摘要 |
| 指标 | `/metrics` 返回轻量聚合 | 需要补充真实运行时长、任务耗时、Agent 数、失败数、资源用量 |
| 用量 / 成本 | 只有 Agent result 带 `usage` 时才回传 | 需要真实 NewAPI token、model_cost_usd、runtime_seconds 或明确暂无 |
| callback 可靠性 | 当前代码 callback 失败记录 warning | 需要确认是否有重试、死信、人工重放；没有则列为未完成 |

## 5. 建议双方统一的蜂群创建请求

Heicode Manager 调蜂群 Runtime：

```http
POST http://52.139.240.116:8000/api/swarms
Authorization: Bearer <runtime-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
```

请求体建议：

```json
{
  "orchestration_plan": {
    "intent_id": "task_xxx",
    "objective": "完成本轮用户目标",
    "sub_mode": "goal_driven_swarm",
    "risk_level": "medium",
    "budget": {
      "duration_seconds": 3600,
      "token_limit": 20000,
      "max_cost_usd": 8
    },
    "user_context": {
      "user_id": "22",
      "channel_id": "heicode",
      "binding_scope": "task-task-xxx"
    },
    "agents": [
      {
        "task_id": "plan-1",
        "role": "planner",
        "title": "目标理解与任务生成",
        "description": "整理用户目标、资源约束和验收标准",
        "depends_on": []
      },
      {
        "task_id": "build-1",
        "role": "builder",
        "title": "代码或文档变更",
        "description": "根据目标生成可验证交付物",
        "depends_on": ["plan-1"]
      },
      {
        "task_id": "verify-1",
        "role": "reviewer",
        "title": "验证与交付整理",
        "description": "检查交付物并形成验收摘要",
        "depends_on": ["build-1"]
      }
    ]
  },
  "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.running",
      "task.heartbeat",
      "task.blocked",
      "task.retried",
      "task.failed",
      "task.completed",
      "handoff.requested",
      "handoff.completed",
      "approval.requested",
      "artifact.created",
      "budget.alert",
      "timeline.updated"
    ]
  },
  "metadata": {
    "manager_deployment_id": "dep_xxx",
    "heicode_deployment_id": "dep_xxx",
    "correlation_id": "corr_xxx",
    "heicode_runtime_bridge": true,
    "runtime_mode": "swarm"
  },
  "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"
  },
  "resource_grants": [
    {
      "grant_id": "grant-task-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": "builder"
    }
  ]
}
```

## 6. Secret 引用格式需要统一

Heicode Manager 当前正式约束建议使用：

```text
azkv://<vault>/secrets/<name>
```

例如：

```text
azkv://heicode-kv.vault.azure.net/secrets/repo-main
azkv://heicode-kv.vault.azure.net/secrets/model-gateway-key
```

HeiCode-Swarm 文档中示例为：

```text
azkv://heicode/git-write-token
```

建议 Agent Manager / 蜂群 Runtime 确认是否可以接受标准 Key Vault 形式，并在示例文档中同步，避免后续联调时因为 `secret_ref` 格式不一致失败。

## 7. Manager 侧后续配置建议

Heicode Manager 需要保留普通 sub 和蜂群两套 Runtime 配置。建议后续拆成：

```text
# 普通 sub 敏捷模式
AGENT_RUNTIME_BASE_URL=http://20.212.121.126
AGENT_RUNTIME_CREATE_PATH=/api/swarms

# 蜂群模式
SWARM_RUNTIME_BASE_URL=http://52.139.240.116:8000
SWARM_RUNTIME_CREATE_PATH=/api/swarms
SWARM_RUNTIME_STOP_PATH=/api/swarms/{swarm_id}/stop
SWARM_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
SWARM_RUNTIME_SERVICE_TOKEN=<runtime-service-token>
```

如果短期 Manager 还只有一套 `AGENT_RUNTIME_*`，只能临时切换到蜂群 Runtime 做专项联调，不能同时代表普通 sub 和蜂群都在线。

## 8. 蜂群 MVP 验收口径

根据蜂群设计文档和 Heicode 产品资料包，蜂群 MVP 不是“接口能创建一个 run”就完成。最小验收应至少满足：

| 验收项 | 成功标准 |
|---|---|
| 创建 | Manager 调 `POST /api/swarms` 成功，Runtime 返回真实 `swarm_id` |
| 任务图 | Runtime 至少生成 2 个可追踪任务，并可通过 `/tasks` 查询 |
| Agent 执行 | 至少一个真实 Agent claim、running、completed |
| 交接或失败回流 | 至少出现一次 handoff，或一次失败/blocked/retry 并可解释 |
| artifact | 至少 1 个真实 artifact 回 Manager，可在 Manager 查询 |
| 审批 | high risk 流程能 `approval.requested`，Manager approve/reject 后 Runtime 状态变化 |
| 日志 | Manager 或 Runtime 能查到可排障日志，不只是空占位 |
| 指标 | 能看到任务数、状态、耗时、Agent 数、失败数等真实指标 |
| 用量 | 能回传 token、模型成本或明确当前未接真实模型成本 |
| 安全 | 请求、callback、日志、artifact metadata 不出现明文长期密钥 |
| 幂等 | 同一个 `X-Idempotency-Key` 重试不会创建重复 swarm |
| 停止 | Manager stop 后 Runtime 状态为 `stopped`，不继续执行 |

## 9. 建议下一次联调步骤

1. Heicode Manager 新增或临时配置蜂群 Runtime base URL 和 Runtime Bearer token。
2. Agent Manager / 蜂群 Runtime 确认 callback token 或 HMAC secret 已和 Heicode Manager 生产端一致。
3. 使用测试用户通过 Manager 创建蜂群 run。
4. 验证 Manager 保存 `runtime_deployment_id` 和 `runtime_swarm_id`。
5. 验证 Runtime 不再只生成 single-agent fallback，而是生成多任务 task graph。
6. 验证 Runtime 主动 callback：
   - `deployment.status_changed`
   - `task.created`
   - `task.claimed`
   - `task.running`
   - `task.completed`
   - `artifact.created`
   - `timeline.updated`
7. 验证查询：
   - `GET /api/swarms/{swarm_id}`
   - `GET /api/swarms/{swarm_id}/tasks`
   - `GET /api/swarms/{swarm_id}/logs`
   - `GET /api/swarms/{swarm_id}/metrics`
8. 验证 high risk 审批：
   - Runtime 回调 `approval.requested`
   - Manager approve
   - Runtime 收到 decision 并继续
9. 验证 stop：
   - Manager stop
   - Runtime stopped
   - 不再继续发 running/completed callback

## 10. 当前结论

蜂群 Runtime 当前已经具备可联调的接口骨架和一部分运行时能力，但还没有完成 Heicode 产品设计要求的完整蜂群 MVP 生产验收。

当前最优先阻塞项是：

1. 将已验证可用的蜂群 Runtime Bearer token 通过安全渠道配置到 Heicode Manager。
2. 确认 Runtime 回调 Manager 的 callback token 或 HMAC secret 已生效。
3. 修正线上 Runtime 只生成 1 个 `general` 任务的问题，使其按目标生成真实多任务 task graph。
4. 确认线上镜像/代码 commit 与 Gitee main 是否一致；如果不一致，需要先部署包含多任务 task graph 逻辑的版本。
5. 跑通一次真实 Manager -> 蜂群 Runtime -> Manager callback 的端到端链路。
6. 补齐真实 Agent 执行、handoff/失败回流、artifact、日志、指标、usage/cost 的生产证据。