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	代码支持

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

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

3. 实测结果

3.1 健康检查通过

请求：

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

返回核心内容：

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

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

返回：

{
  "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：

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

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

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

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

{
  "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。创建成功：

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

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

{
  "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 行为不一致

已检查项目地址：

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

当前 main commit：

802bbe97ca278d2da3c70a3e471219db62c01c98 对接文档

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

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

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

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

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

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 地址：

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

callback schema 查询：

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：

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

请求体建议：

{
  "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 当前正式约束建议使用：

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

例如：

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

HeiCode-Swarm 文档中示例为：

azkv://heicode/git-write-token

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

7. Manager 侧后续配置建议

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

# 普通 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 的生产证据。