heicode-mananger/docs/integration/AgentManager蜂群Runtime接口实现要求.md

Agent Manager 蜂群 Runtime 接口实现要求

更新时间：2026-05-28 面向对象：Agent Manager / HeiCode-Swarm Runtime 开发负责人 用途：Agent Manager 按本文实现接口、字段和回调后，Heicode Manager 可直接联调蜂群模式。

1. 结论

Heicode Manager 已负责控制面和记录面：

• 生成 deployment / swarm 创建请求。
• 传递 resource_grants、secret_ref、预算、模型网关上下文和 callback 地址。
• 保存 deployment_id <-> runtime_deployment_id <-> swarm_id 映射。
• 接收 Runtime callback，落库 artifact / approval / timeline / audit。
• 用户 approve/reject 后，把审批决定回传 Runtime。

Agent Manager / Swarm Runtime 需要负责执行层：

• 创建真实 Swarm Run。
• 生成真实 task graph。
• 管理 Agent claim / heartbeat / handoff / retry / blocked / failed 状态机。
• 真实执行任务并产出 artifact。
• 在高危动作前暂停并回调审批请求。
• 接收审批结果后继续或停止。
• 回传日志、指标、用量和最终结果。

1.1 2026-05-28 生产联调实测结论

使用测试用户 zsbgnw@gmail.com（Manager 用户 chenchen，user_id=22）在生产 Manager 上实测蜂群入口。

当前生产 Manager Runtime 配置实际为：

AGENT_RUNTIME_BASE_URL=http://20.212.121.126
AGENT_RUNTIME_CREATE_PATH=/api/agent/deployments
AGENT_RUNTIME_STOP_PATH=/api/agent/deployments/{deployment_id}/stop

实测结果：

项	结果
GET /api/agent/runtime/health	通过，远端 Agent Manager IP healthy
POST /api/swarms 使用 agent_runtime.platform=agent-swarm	失败，Manager 返回 agent_runtime.platform must be agent when runtime context is present
POST /api/swarms 使用 agent_runtime.platform=agent	通过
Manager deployment	dep_72cdc138b9c8
Manager 返回 swarm_id	dep_72cdc138b9c8，当前是 Manager 本地 deployment id
Runtime deployment	dep_77370f27186f
Manager events	deployment.accepted、runtime.sync.started、runtime.sync.accepted
Manager stop	通过
Runtime stop	通过，Agent Manager 侧 dep_77370f27186f 状态为 stopped
Runtime callback	未观察到，生产 Manager callback 表 0 条对应记录
artifact / timeline callback	未产出
SK / usage callback	未产出
Runtime logs	仅 Pod ... has no logs yet
Runtime metrics	返回固定 CPU/内存/网络汇总，看起来仍是占位值

结论：

1. Heicode Manager 的 /api/swarms adapter 能接收用户态蜂群请求，并能通过当前 Runtime bridge 调 Agent Manager IP。
2. 当前生产链路实际走的是 Agent Manager /api/agent/deployments，不是 Agent Manager /api/swarms。
3. Manager stop 可以传递到 Agent Manager deployment stop。
4. 当前还没有真实蜂群 Runtime callback、task graph、artifact、SK、usage。
5. Agent Manager 如果要满足正式蜂群模式，仍需实现本文后续定义的 /api/swarms、/api/swarms/{swarm_id}、/api/swarms/{swarm_id}/stop、callback 和 usage 约束。

2. 总体调用链

Heicode Desktop Client
  -> Heicode Manager
     POST /api/swarms 或 /api/agent/user/deployments
  -> Agent Manager / Swarm Runtime
     POST /api/swarms
  <- Runtime response
     runtime_deployment_id / swarm_id / status
  <- Runtime callback
     POST /api/agent/callbacks/swarm-events
  -> Runtime approval decision
     POST /api/swarms/{swarm_id}/approvals/{approval_id}

客户端到 Heicode Manager 的 POST /api/swarms 与普通 sub 用户态接口一样，必须支持 V2 body 加密：

Content-Encoding: heicode-aead-v1
X-Heicode-Device-Id: <device_id>
X-Heicode-Timestamp: <unix_ms>
X-Heicode-Nonce: <nonce_hex>
X-Heicode-Fingerprint: <device_fingerprint>
X-Heicode-Eph-Pubkey: <base64_x25519_ephemeral_pubkey>
X-Heicode-Signature: <base64_ed25519_signature>
Content-Type: application/json

未加密 Web 控制台请求仍按 Manager session cookie + New-Api-User 兼容处理。Manager 调 Agent Manager / Swarm Runtime 的服务间请求不使用该客户端 body 加密协议，而使用 Authorization: Bearer <service_token> 和公共追踪 Header。

3. Agent Manager 必须提供的接口

优先级	方法	路径	必须	用途
P0	GET	/api/agent/health	是	健康检查
P0	POST	/api/swarms	是	创建真实 Swarm Run
P0	POST	/api/swarms/{swarm_id}/stop	是	停止 Swarm Run
P0	POST	/api/swarms/{swarm_id}/approvals/{approval_id}	是	接收 Manager 审批决定
P0	callback	Manager /api/agent/callbacks/swarm-events	是	回写状态、task、handoff、artifact、approval
P1	GET	/api/swarms/{swarm_id}	建议	查询 Runtime 详情
P1	GET	/api/swarms/{swarm_id}/tasks	建议	查询 task graph
P1	GET	/api/swarms/{swarm_id}/logs	建议	查询日志
P1	GET	/api/swarms/{swarm_id}/metrics	建议	查询指标

如果短期无法提供 /api/swarms，可以临时确认兼容路径，例如 /tasks。但这只能作为联调过渡，不作为最终生产契约。

4. 认证与公共 Header

Manager 调 Agent Manager 时携带：

Authorization: Bearer <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

要求：

1. Authorization 用于服务间鉴权。
2. X-Correlation-ID 必须贯穿 create、callback、approval decision、logs、metrics。
3. X-Idempotency-Key 必须支持幂等；重复创建请求不能生成多个真实 Swarm Run。
4. Agent Manager 不得要求 Manager 传长期明文密钥。

5. GET /api/agent/health

响应

{
  "success": true,
  "data": {
    "status": "healthy",
    "service": "agent-manager-swarm-runtime",
    "version": "1.0.0",
    "runtime": "aks",
    "time": "2026-05-28T10:00:00Z"
  }
}

验收：

• HTTP 200。
• status 为 healthy / ok / up 之一。
• 不返回密钥、Token、连接串。

6. POST /api/swarms

请求体

{
  "orchestration_plan": {
    "intent_id": "task_123",
    "template_hint": "heicode-task",
    "objective": "完成本轮用户目标",
    "sub_mode": "agile",
    "risk_level": "medium",
    "budget": {
      "max_tokens": 120000,
      "max_cost_usd": 8,
      "max_duration_sec": 3600
    },
    "user_context": {
      "user_id": "22",
      "channel_id": "heicode",
      "binding_scope": "task-task-123"
    },
    "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"
    },
    "agile_context": {
      "iteration": "2026-05-28",
      "stage": "development",
      "checkpoint": "draft_created",
      "acceptance_criteria": [
        "接口返回成功",
        "artifact 可回写到 timeline",
        "不出现明文密钥"
      ],
      "next_action": "continue",
      "requires_user_approval": false
    },
    "agents": [
      {
        "role_template": "backend",
        "goal": "完成后端实现和测试",
        "default_model_id": "model_xxx",
        "resource_grants": []
      }
    ],
    "resource_grants": []
  },
  "agents": [
    {
      "role": "backend",
      "resource_grants": []
    }
  ],
  "resource_grants": [
    {
      "grant_id": "grant-task-123-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": "backend",
      "constraints": {
        "allowed_paths": "heicode/**"
      },
      "metadata": {
        "repo": "heicode-manager"
      }
    }
  ],
  "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.heartbeat",
      "task.blocked",
      "task.retried",
      "task.failed",
      "task.completed",
      "handoff.requested",
      "handoff.completed",
      "approval.requested",
      "artifact.created",
      "timeline.updated",
      "budget.alert"
    ]
  },
  "metadata": {
    "manager_deployment_id": "dep_xxx",
    "heicode_deployment_id": "dep_xxx",
    "heicode_runtime_bridge": true,
    "correlation_id": "corr_xxx"
  }
}

Agent Manager 必须消费的字段

字段	必须	说明
orchestration_plan.objective	是	用户目标
orchestration_plan.sub_mode	是	agile / waterfall；蜂群执行时也要保留此组织方式
orchestration_plan.risk_level	是	高危动作必须走审批
orchestration_plan.budget	是	token / cost / duration 上限
billing_context.provider	是	当前为 newapi
billing_context.secret_ref	是	模型网关密钥引用，只能是 azkv://...
agents[].role 或 role_template	是	子 Agent 角色
resource_grants[]	是	资源授权清单
resource_grants[].secret_ref	凭据资源必填	只允许 Key Vault 引用，不允许明文
callback.url	是	Runtime 回调 Manager 的地址
callback.signing_secret_ref	建议	HMAC 签名密钥引用
metadata.manager_deployment_id	是	Manager 侧 deployment id
metadata.correlation_id	是	全链路追踪

响应

{
  "success": true,
  "data": {
    "deployment_id": "runtime-dep-123",
    "swarm_id": "swarm-123",
    "status": "running",
    "created_at": "2026-05-28T10:00:00Z",
    "estimated_ready_at": "2026-05-28T10:02:00Z"
  }
}

兼容响应：

{
  "deployment_id": "runtime-dep-123",
  "swarm_id": "swarm-123",
  "status": "running"
}

Manager 映射规则：

Agent Manager 返回字段	Manager 保存字段
data.deployment_id / deployment_id / id	runtime_deployment_id
data.swarm_id / swarm_id / runtime_swarm_id	runtime_swarm_id
data.status / status / runtime_status	runtime_state

7. Runtime 必须生成的 task graph

Agent Manager 创建 Swarm Run 后，必须在 Runtime 内部生成任务图，并通过 callback 回写。

每个 task 至少包含：

{
  "task_id": "task-backend-1",
  "title": "实现后端接口",
  "description": "完成 API、校验和测试",
  "agent_role": "backend",
  "status": "pending",
  "depends_on": ["task-design-1"],
  "attempt": 1
}

状态建议：

status	说明
pending	等待执行
claimed	已被 Agent 领取
running	执行中
blocked	阻塞
handoff_requested	等待交接
retrying	重试中
completed	完成
failed	失败

8. Runtime 回调 Manager

Manager 回调地址：

POST https://code.xinghanlab.com/api/agent/callbacks/swarm-events
X-Agent-Service-Token: <callback_token>
X-Agent-Event-Id: <event_id>
X-Correlation-ID: <correlation_id>
Content-Type: application/json

也支持 HMAC：

X-Agent-Timestamp: <unix_ms>
X-Agent-Signature: sha256=<hex>

HMAC 签名内容：

timestamp + "." + event_id + "." + raw_body

联调前可拉取 Manager 当前接受的事件 schema：

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

通用 callback envelope

{
  "event_id": "evt_123",
  "idempotency_key": "evt_123",
  "event_type": "task.claimed",
  "deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "agent_instance_id": "agent-backend-1",
  "task_id": "task-backend-1",
  "occurred_at": "2026-05-28T10:10:00Z",
  "correlation_id": "corr_xxx",
  "source": "agent-manager-runtime",
  "payload": {}
}

要求：

1. event_id 全局唯一。
2. 重试同一事件必须复用相同 event_id 或 idempotency_key。
3. deployment_id 优先使用 Manager deployment id。
4. 如果只知道 swarm_id，Manager 也会按 runtime_swarm_id 查找 deployment。
5. source 要能区分真实 Runtime，例如 agent-manager-runtime，不要写 simulated。

9. 必须回调的事件和字段

event_type	必填字段	说明
deployment.status_changed	payload.status	Runtime 整体状态变化
task.created	task_id, payload.title	任务图新增任务
task.claimed	task_id, payload.agent_role	Agent 领取任务
task.running	task_id, payload.agent_role	Agent 开始执行
task.heartbeat	task_id, payload.agent_role	Agent 心跳
task.blocked	task_id, payload.reason	任务阻塞
task.retried	task_id, payload.attempt	任务重试
task.failed	task_id, payload.reason	任务失败
task.completed	task_id	任务完成
handoff.requested	task_id, payload.from_role, payload.to_role	请求交接
handoff.completed	task_id, payload.from_role, payload.to_role	完成交接
artifact.created	artifact.artifact_id 或 payload.artifact_id	产物生成
approval.requested	payload.approval_id, payload.operation, payload.risk_level	高危审批
timeline.updated	payload.title	用户可见时间线
budget.alert	payload.threshold_pct	预算告警

10. artifact.created

Runtime 产生中间产物或最终交付物时回调：

{
  "event_id": "evt_artifact_1",
  "event_type": "artifact.created",
  "deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "task_id": "task-backend-1",
  "source": "agent-manager-runtime",
  "artifact": {
    "artifact_id": "art_backend_patch_1",
    "artifact_type": "code_patch",
    "title": "Backend API patch",
    "summary": "新增任务创建和状态查询接口",
    "uri": "git://heicode-manager/branches/feature/task-api",
    "checksum": "sha256:abc123",
    "metadata": {
      "agent_role": "backend",
      "redacted": true
    }
  }
}

支持的 artifact_type：

类型	说明
code_patch	代码补丁或分支
document	文档
test_report	测试报告
deployment_manifest	部署清单
log_bundle	日志包
other	其他

要求：

1. 大文件不要内联到 callback body。
2. summary 可展示给用户，不得包含密钥。
3. uri 可以是 git://、artifact://、azblob://、https://。
4. metadata 必须脱敏。

11. approval.requested 与审批结果

高危动作前 Runtime 必须暂停，并回调：

{
  "event_id": "evt_approval_1",
  "event_type": "approval.requested",
  "deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "task_id": "task-deploy-1",
  "source": "agent-manager-runtime",
  "payload": {
    "approval_id": "runtime-approval-1",
    "operation": "deploy.production",
    "resource_id": "prod-env",
    "resource_type": "azure",
    "resource_scope": "resource-group/heicode-prod",
    "target_role": "ops",
    "risk_level": "high",
    "requires_credential": true,
    "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/prod-deploy",
    "ttl_seconds": 600,
    "reason": "需要部署到生产环境"
  }
}

Manager / 客户端审批后，Manager 调 Runtime：

POST /api/swarms/{swarm_id}/approvals/{approval_id}
Authorization: Bearer <service_token>
X-Correlation-ID: <correlation_id>
X-Idempotency-Key: approval-decision-<approval_id>-<decision>
Content-Type: application/json

请求：

{
  "approval_id": "runtime-approval-1",
  "decision": "approved",
  "reason": "用户已确认",
  "manager_deployment_id": "dep_xxx",
  "swarm_id": "swarm-123",
  "decided_by": "user:22",
  "decided_at": "2026-05-28T10:20:00Z",
  "credential_lease": {
    "lease_id": "lease_xxx",
    "credential_ref": "lease://runtime/runtime-approval-1",
    "expires_at": "2026-05-28T10:30:00Z"
  }
}

decision 枚举：

decision	Runtime 行为
approved	继续原高危动作
rejected	停止该动作，回调 timeline.updated 或 task.failed

要求：

1. Runtime 收到 approved 后才可以继续高危动作。
2. Runtime 收到 rejected 后不能继续执行该动作。
3. Runtime 不得把 credential_ref 展开写入日志或 artifact metadata。
4. Runtime 必须把审批结果后的状态继续通过 callback 回写。

12. 日志、指标和用量

日志

建议提供：

GET /api/swarms/{swarm_id}/logs?limit=100&cursor=<cursor>

响应：

{
  "success": true,
  "data": {
    "items": [
      {
        "timestamp": "2026-05-28T10:21:00Z",
        "level": "info",
        "agent_role": "backend",
        "task_id": "task-backend-1",
        "message": "test completed",
        "redacted": true
      }
    ],
    "next_cursor": ""
  }
}

指标

建议提供：

GET /api/swarms/{swarm_id}/metrics?window=15m&step=60s

响应：

{
  "success": true,
  "data": {
    "swarm_id": "swarm-123",
    "agent_metrics": [
      {
        "agent_instance_id": "agent-backend-1",
        "agent_role": "backend",
        "task_id": "task-backend-1",
        "status": "running",
        "cpu_percent": 12.5,
        "memory_bytes": 268435456,
        "uptime_seconds": 300
      }
    ]
  }
}

用量

Runtime 调模型时必须带关联字段：

字段	说明
manager_deployment_id	Manager deployment id
swarm_id	Runtime swarm id
task_id	当前任务
agent_role	Agent 角色
model_id	使用模型
correlation_id	全链路追踪

Runtime 可通过 budget.alert 或 timeline.updated 回传用量摘要。

13. 安全约束

必须遵守：

1. 禁止在请求、callback、日志、artifact metadata 中出现明文密码、Token、私钥、连接串、云 access key、模型 key。
2. 长期凭据只能通过 azkv://<vault>/secrets/<name> 传引用。
3. Runtime 可以把短期租约写成 lease://...，但不能写真实密钥。
4. secret_ref、credential_ref 只能作为引用使用，不能在用户可见内容中展开。
5. 所有 callback payload 必须脱敏。
6. 高危动作必须先 approval.requested，不能先执行后补审批。

14. 错误码建议

HTTP	code	场景
401	UNAUTHORIZED	service token 无效
403	FORBIDDEN	权限不足
404	SWARM_NOT_FOUND	swarm 不存在
409	IDEMPOTENCY_CONFLICT	幂等键冲突
422	VALIDATION_ERROR	请求字段缺失
422	SECRET_REF_INVALID	secret_ref 非 azkv://...
422	POLICY_REJECTED	高危策略拒绝
500	INTERNAL_ERROR	Runtime 内部错误

错误响应：

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "resource_grants[0].secret_ref is required",
    "request_id": "corr_xxx"
  }
}

15. 联调验收清单

步骤	操作	通过标准
1	Manager 调 GET /api/agent/health	返回 healthy
2	Manager 调 POST /api/swarms	返回真实 deployment_id 和 swarm_id
3	Runtime 回调 deployment.status_changed	Manager timeline 可见
4	Runtime 回调 task.created	Manager task flow / Agent task map 可见
5	Runtime 回调 task.claimed / task.heartbeat	Manager 可看到 Agent 领取和心跳
6	Runtime 回调 handoff.requested / handoff.completed	Manager 可看到交接
7	Runtime 回调 artifact.created	Manager artifact 列表可见
8	Runtime 回调 approval.requested	Manager approval 列表出现 pending
9	客户端 / Manager approve	Runtime 收到 decision 并继续
10	客户端 / Manager reject	Runtime 收到 decision 并停止对应动作
11	Runtime 回传 logs / metrics / usage	Manager 可查询或 timeline 可见
12	Runtime 回调最终 deployment.status_changed=completed	Manager 和客户端看到完成

16. 当前不能误报完成的项

以下项只有在 Agent Manager 真实实现并联调后才能算完成：

1. 真实 Swarm Run 创建成功。
2. 真实 task graph 生成。
3. 真实 Agent claim / heartbeat。
4. 真实 handoff / retry / blocked。
5. 真实 artifact 产出。
6. 审批后 Runtime 继续或停止。
7. Runtime 真实日志和指标。
8. 子 Agent 模型用量归属。
9. 最终交付物回到客户端。

Manager 本地模拟事件、测试桩、空态页面和 schema 校验只能证明 Manager 接收和展示能力，不能证明蜂群生产闭环完成。