From ed9136d29dbf8cca8cf3eaadd6360fdf4fc53dfd Mon Sep 17 00:00:00 2001 From: gongzhiyong Date: Thu, 28 May 2026 21:56:17 +0800 Subject: [PATCH] docs: list remaining agent manager sub requirements --- .../AgentManager普通sub剩余补充要求.md | 246 ++++++++++++++++++ 1 file changed, 246 insertions(+) create mode 100644 docs/integration/AgentManager普通sub剩余补充要求.md diff --git a/docs/integration/AgentManager普通sub剩余补充要求.md b/docs/integration/AgentManager普通sub剩余补充要求.md new file mode 100644 index 00000000..4ca7bbc9 --- /dev/null +++ b/docs/integration/AgentManager普通sub剩余补充要求.md @@ -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 仍应修正自身状态 | +