docs: list remaining agent manager sub requirements

2026-05-28 21:56:17 +08:00
parent fecb365e87
commit ed9136d29d
1 changed files with 246 additions and 0 deletions
@@ -0,0 +1,246 @@
+# 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 地址：
+
+```text
+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：
+
+```json
+{
+  "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 能区分预算和真实消耗。
+
+```json
+{
+  "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
+    }
+  }
+}
+```
+
+如果当前测试任务确实没有模型调用，也需要明确回传：
+
+```json
+{
+  "model_tokens": 0,
+  "model_cost_usd": 0,
+  "runtime_seconds": 42,
+  "billing_source": "runtime_no_model_call"
+}
+```
+
+不能只返回全 0 又没有解释。
+
+## 7. 状态一致性要求
+
+当前实测中 Agent Manager 状态存在矛盾：
+
+```json
+{
+  "status": "completed",
+  "agents": [
+    {
+      "status": "running"
+    }
+  ],
+  "tokens_used": 0,
+  "artifacts": []
+}
+```
+
+需要改为：
+
+```json
+{
+  "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 都要能表达失败：
+
+```json
+{
+  "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 仍应修正自身状态 |
+