heicode/docs/integration/AgentManager普通sub剩余补充要求.md

Agent Manager 普通 sub 剩余补充要求

更新时间：2026-05-28
发给：Agent Manager / Agnet Runtime 负责人
范围：普通 sub 敏捷开发模式，不包含蜂群模式完整 task graph。

1. 当前已验证事实

Heicode Manager 生产版本 1.4.19 已完成并验证以下链路：

项目	状态	生产验证
Manager 创建普通 sub run	已跑通	POST https://code.xinghanlab.com/api/swarms 返回 dep_*
Manager 调 Agent Manager	已跑通	Agent Manager 返回 runtime_swarm_id=swm_*
Agent Manager 自动 callback	已跑通	Manager events/timeline 可查到 callback
callback HMAC fallback	已跑通	生产 callback 可验签入库
Manager 状态反写	已跑通	callback 后 deployment.status/phase/runtime_state/agent_instances 会更新
billing_context 字段透传	已跑通	default_model_id/allowed_model_ids/secret_ref 已保留

最新生产烟测样例：

字段	值
Manager deployment	dep_be665a25f6bc
Runtime swarm	swm_4c471d60972f
Manager detail status	completed
Manager detail phase	deploy
Manager runtime_state	completed
Manager agent state	completed
Manager callback 数	9
Manager event 数	12

因此，当前剩余问题主要不在 Manager 接收链路，而在 Agent Manager 真实执行数据、状态一致性、产物和用量回传。

2. Agent Manager 必须补充的 P0

优先级	缺口	当前实测表现	Agent Manager 需要补什么	验收标准
P0	Runtime 状态一致性	直连 GET /api/swarms/{swarm_id}/status 返回整体 completed，但 agents[].status 仍是 running	整体完成时同步更新 agent 状态，或发送 agent.completed callback	status 接口中整体和 agent 状态一致；Manager 不再需要兜底收敛
P0	真实 artifact 回传	Manager 收到 callback，但 /artifacts 仍为 []	执行完成时回调 artifact.created，至少包含摘要型交付物	Manager /artifacts 至少有 1 条真实 artifact
P0	真实 usage / cost 回传	tokens_used=0，budget callback 中 token/cost/runtime 多为 0	回传模型 token、模型成本、runtime 秒数、资源使用	Manager timeline 中能看到非 0 或明确的真实 usage 字段
P0	真实日志	/logs 返回占位文本 Logs will be fetched from K8s in Phase 2	接入真实 Pod/Runtime 日志或回调日志摘要	GET /logs 返回真实执行日志或明确失败原因
P0	阶段推进语义	callback 有 phase/timeline，但当前非常短，直接 completed	普通 sub 应按需求、设计、开发、测试、部署阶段推进	至少能看到 requirements/design/development/testing/deploy 中的真实阶段变化
P0	失败原因回传	当前成功场景没有问题，但失败链路未验证	失败时回调 deployment.status_changed + agent.crashed 或 sk_tool.failed	Manager detail 出现 failed 和可读 failure_reason

3. Agent Manager 应补充的 P1

优先级	缺口	要求	验收标准
P1	SK 工具调用展示	回调 sk_tool.called/completed/failed，参数和结果必须脱敏	Manager /sk-snapshots 或 timeline 能看到工具调用记录
P1	高危审批闭环	高危动作回调 approval.requested，等待 Manager/客户端 approve/reject 后继续或停止	approve 后 Runtime 继续，reject 后 Runtime 停止或跳过高危动作
P1	stop 后真实停止	Manager stop 会调用 Runtime stop	stop 后 status 为 stopped，不再继续发 running/completed callback
P1	幂等创建稳定性	同一个 X-Idempotency-Key 不重复创建	重放创建请求返回同一个 run
P1	callback 重试/死信	文档写了重试/死信，但也写失败只 warning	明确当前真实策略；失败后至少可人工重放
P1	runtime_id 字段稳定	当前 Manager 可兼容 deployment_id=swm_*	后续响应和 callback 统一携带 deployment_id、swarm_id、correlation_id

4. Callback 最低要求

Manager callback 地址：

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

创建 run 后，Agent Manager 至少需要主动回调这些事件：

事件	何时发送	payload 最低字段
deployment.status_changed	accepted/running/completed/failed/stopped	status
phase.changed	普通 sub 阶段变化	stage、checkpoint、summary
timeline.updated	用户可读进度	title、summary、stage、checkpoint
agent.started	子 Agent 开始	agent_role、status
agent.completed	子 Agent 完成	agent_role、status
agent.crashed	子 Agent 异常	agent_role、reason
artifact.created	产生中间或最终交付物	artifact_id、artifact_type、title、summary、uri
budget.alert	用量更新或预算告警	model_tokens、model_cost_usd、runtime_seconds、consumed_usd
sk_tool.completed	SK 工具成功	tool_name、tool_invocation_id、summary
sk_tool.failed	SK 工具失败	tool_name、tool_invocation_id、reason
approval.requested	需要高危审批	approval_id、operation、risk_level、reason

5. Artifact 最低格式

普通 sub 完成时至少回写一个 artifact：

{
  "event_type": "artifact.created",
  "deployment_id": "dep_xxx",
  "swarm_id": "swm_xxx",
  "agent_instance_id": "agi_backend_001",
  "payload": {
    "artifact_id": "art_dep_xxx_summary",
    "artifact_type": "test_report",
    "title": "普通 sub 执行结果",
    "summary": "本轮任务完成了哪些内容、测试结果、剩余风险",
    "uri": "azblob://heicode-artifacts/dep_xxx/report.json",
    "stage": "deploy",
    "checkpoint": "completed",
    "metadata": {
      "agent_role": "backend",
      "redacted": true
    }
  }
}

要求：

• summary 可直接展示给用户。
• 不允许出现明文 token、password、secret、private key、connection string。
• 大文件只传 URI 和摘要，不在 callback body 内联完整内容。

6. Usage / Cost 最低格式

Agent Manager 需要让 Manager 能区分预算和真实消耗。

{
  "event_type": "budget.alert",
  "deployment_id": "dep_xxx",
  "swarm_id": "swm_xxx",
  "payload": {
    "billing_source": "newapi",
    "model_id": "model-runtime-smoke",
    "prompt_tokens": 1200,
    "completion_tokens": 800,
    "model_tokens": 2000,
    "model_cost_usd": 0.012,
    "runtime_seconds": 42,
    "cpu_core_seconds": 21,
    "memory_mb_seconds": 86016,
    "consumed_usd": 0.012,
    "budget": {
      "max_cost_usd": 0.05,
      "remaining_usd": 0.038
    }
  }
}

如果当前测试任务确实没有模型调用，也需要明确回传：

{
  "model_tokens": 0,
  "model_cost_usd": 0,
  "runtime_seconds": 42,
  "billing_source": "runtime_no_model_call"
}

不能只返回全 0 又没有解释。

7. 状态一致性要求

当前实测中 Agent Manager 状态存在矛盾：

{
  "status": "completed",
  "agents": [
    {
      "status": "running"
    }
  ],
  "tokens_used": 0,
  "artifacts": []
}

需要改为：

{
  "status": "completed",
  "phase": "deploy",
  "progress": 100,
  "agents": [
    {
      "status": "completed"
    }
  ],
  "metrics": {
    "tokens_used": 2000,
    "elapsed_seconds": 42
  },
  "artifacts": [
    {
      "artifact_id": "art_xxx",
      "artifact_type": "test_report"
    }
  ]
}

如果执行失败，则整体和 agent 都要能表达失败：

{
  "status": "failed",
  "error_message": "模型调用失败或资源授权不足",
  "agents": [
    {
      "status": "failed",
      "error_message": "具体失败原因"
    }
  ]
}

8. 联调验收步骤

Agent Manager 补完后，按以下步骤验收：

1. Heicode Manager 通过 POST /api/swarms 创建普通 sub run。
2. Manager 返回 deployment_id=dep_*。
3. Runtime 返回并持久化 runtime_swarm_id=swm_*。
4. Agent Manager 主动 callback：
   • deployment.status_changed
   • phase.changed
   • timeline.updated
   • agent.started
   • agent.completed
   • artifact.created
   • budget.alert
5. Manager 查询：
   • /api/agnet/user/deployments/{deployment_id}
   • /events
   • /timeline
   • /artifacts
   • /sk-snapshots
6. 期望结果：
   • detail 状态为真实 Runtime 状态。
   • timeline 有阶段推进。
   • artifacts 有真实产物。
   • usage 有可解释的真实消耗。
   • 不出现明文密钥。

9. 当前非阻塞但需记录

项目	当前状态	说明
Agent Manager 域名	暂未作为联调依赖	当前统一使用 http://20.212.121.126
Azure Key Vault	Manager 侧 VM Managed Identity 未正式配好	当前 callback 使用 HMAC fallback 已跑通；正式 Key Vault 需后续云资源配置
Manager 状态兜底	已完成	Manager 1.4.19 会根据 callback 收敛 detail 状态，但 Runtime 仍应修正自身状态