Heicode Manager 蜂群 Runtime 联调配置模板

更新时间：2026-05-27 适用范围：Heicode Manager 调用 Agent Manager / HeiCode-Swarm Runtime。

一、标准 Agent Manager Runtime 配置

当 Runtime 提供正式 POST /api/swarms 时，Manager 建议配置：

AGNET_RUNTIME_ENABLED=true
AGNET_RUNTIME_ASYNC=false
AGNET_RUNTIME_BASE_URL=http://<runtime-host>
AGNET_RUNTIME_SERVICE_TOKEN=<service-token>
AGNET_RUNTIME_HEALTH_PATH=/api/agnet/health
AGNET_RUNTIME_CREATE_PATH=/api/swarms
AGNET_RUNTIME_STOP_PATH=/api/swarms/{swarm_id}/stop
AGNET_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
AGNET_RUNTIME_TIMEOUT_SECONDS=10
HEICODE_PUBLIC_BASE_URL=https://code.xinghanlab.com
AGNET_RUNTIME_CALLBACK_URL=https://code.xinghanlab.com/api/agnet/callbacks/swarm-events
AGNET_CALLBACK_TOKEN=<callback-token>

说明：

AGNET_RUNTIME_SERVICE_TOKEN 是 Manager 调 Runtime 的 Bearer token。
AGNET_CALLBACK_TOKEN 是 Runtime 回调 Manager 时放在 X-Agnet-Service-Token 的 token。
两个 token 可以不同，不要写进前端或日志。
如果 Runtime 返回 swarm_id，Manager 会保存到 runtime_swarm_id。
如果 Runtime 返回 deployment_id，Manager 会保存到 runtime_deployment_id。

二、当前 HeiCode-Swarm Orchestrator 兼容配置

如果短期只用现有 Orchestrator 的 /health 和 /tasks 先做连通性测试，可以临时配置：

AGNET_RUNTIME_ENABLED=true
AGNET_RUNTIME_ASYNC=false
AGNET_RUNTIME_BASE_URL=http://52.139.240.116:8000
AGNET_RUNTIME_SERVICE_TOKEN=<optional-if-supported>
AGNET_RUNTIME_HEALTH_PATH=/health
AGNET_RUNTIME_CREATE_PATH=/tasks
AGNET_RUNTIME_STOP_PATH=/tasks/{runtime_deployment_id}/stop
AGNET_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
AGNET_RUNTIME_TIMEOUT_SECONDS=10
HEICODE_PUBLIC_BASE_URL=https://code.xinghanlab.com
AGNET_RUNTIME_CALLBACK_URL=https://code.xinghanlab.com/api/agnet/callbacks/swarm-events
AGNET_CALLBACK_TOKEN=<callback-token>

注意：

/tasks 不是最终生产契约，只能做临时兼容测试。
当前 /tasks 字段不足以完整表达 resource_grants、secret_ref、approval_policy、budget。
若 Orchestrator 不支持 stop 和 approval decision，Manager 会记录回传失败审计，但用户审批记录仍会保存。

三、Runtime 回调 Manager 的请求头

推荐使用 service token：

POST /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-Event-Id: <event-id>
X-Agnet-Timestamp: <unix-ms>
X-Agnet-Signature: sha256=<hex>
X-Correlation-ID: <correlation-id>
Content-Type: application/json

签名内容：

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

四、最小联调命令

健康检查：

curl -sS "$AGNET_RUNTIME_BASE_URL$AGNET_RUNTIME_HEALTH_PATH"

Manager 本地默认模拟链路：

curl -sS -X POST "https://code.xinghanlab.com/api/agnet/user/deployments/<manager-deployment-id>/simulate-events" \
  -H "Authorization: Bearer <manager-user-token>" \
  -H "Content-Type: application/json" \
  -d '{}'

该命令用于 Manager 自测，不代表真实 Runtime 已执行。默认模拟会落 callback、artifact、approval、timeline 记录，并用于检查页面展示和 secret_ref 脱敏。

模拟 Runtime 回调 Manager：

curl -sS -X POST "https://code.xinghanlab.com/api/agnet/callbacks/swarm-events" \
  -H "Content-Type: application/json" \
  -H "X-Agnet-Service-Token: $AGNET_CALLBACK_TOKEN" \
  -H "X-Agnet-Event-Id: evt-smoke-001" \
  -H "X-Correlation-ID: corr-smoke-001" \
  -d '{
    "event_id": "evt-smoke-001",
    "event_type": "timeline.updated",
    "deployment_id": "<manager-deployment-id>",
    "swarm_id": "<runtime-swarm-id>",
    "occurred_at": "2026-05-27T10:00:00Z",
    "source": "heicode-swarm-runtime",
    "payload": {
      "title": "Runtime callback received",
      "summary": "Manager callback pipeline is reachable",
      "severity": "info"
    }
  }'

成功响应：

{
  "success": true,
  "data": {
    "event_id": "evt-smoke-001",
    "inserted": true,
    "deduplicated": false,
    "deployment_id": "<manager-deployment-id>"
  }
}

五、上线前必须确认

项	标准
create	Manager 能拿到 `runtime_deployment_id` 和 `runtime_swarm_id`
callback	Runtime 至少回调 `deployment.status_changed`、`task.completed`、`artifact.created`
approval	Runtime 发 `approval.requested`，Manager 用户审批后 Runtime 收到 decision
artifact	Manager artifacts 页面能看到 artifact 类型、标题、摘要和 URI
timeline	Manager timeline 能区分 `manager`、`runtime`、`simulated` 来源
secret	请求、响应、日志、artifact metadata 中无长期明文密钥

4.9 KiB Raw Blame History Unescape Escape