xiaohei/heicode
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8075891770ee7fa859fc6ac6566de05fb57a59e1
heicode/docs/integration/AgentManager蜂群Runtime接口实现要求.md
T

18 KiB
Raw Blame History

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。
  • 在高危动作前暂停并回调审批请求。
  • 接收审批结果后继续或停止。
  • 回传日志、指标、用量和最终结果。

2. 总体调用链

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

3. Agent Manager 必须提供的接口

优先级 方法 路径 必须 用途
P0 GET /api/agnet/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/agnet/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/agnet/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/agnet/callbacks/swarm-events",
    "signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agnet-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/agnet/callbacks/swarm-events
X-Agnet-Service-Token: <callback_token>
X-Agnet-Event-Id: <event_id>
X-Correlation-ID: <correlation_id>
Content-Type: application/json

也支持 HMAC：

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

HMAC 签名内容：

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

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

GET https://code.xinghanlab.com/api/agnet/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/agnet/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 接收和展示能力，不能证明蜂群生产闭环完成。

Reference in New Issue View Git Blame Copy Permalink