heicode/docs/integration/heicode-manager-swarm-runtime-env-template.md

# Heicode Manager 蜂群 Runtime 联调配置模板

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

## 一、标准 Agent Manager Runtime 配置

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

```bash
AGENT_RUNTIME_ENABLED=true
AGENT_RUNTIME_ASYNC=false
AGENT_RUNTIME_BASE_URL=http://<runtime-host>
AGENT_RUNTIME_SERVICE_TOKEN=<service-token>
AGENT_RUNTIME_HEALTH_PATH=/api/agent/health
AGENT_RUNTIME_CREATE_PATH=/api/swarms
AGENT_RUNTIME_STOP_PATH=/api/swarms/{swarm_id}/stop
AGENT_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
AGENT_RUNTIME_TIMEOUT_SECONDS=10
HEICODE_PUBLIC_BASE_URL=https://code.xinghanlab.com
AGENT_RUNTIME_CALLBACK_URL=https://code.xinghanlab.com/api/agent/callbacks/swarm-events
AGENT_CALLBACK_TOKEN=<callback-token>
```

说明：

1. `AGENT_RUNTIME_SERVICE_TOKEN` 是 Manager 调 Runtime 的 Bearer token。
2. `AGENT_CALLBACK_TOKEN` 是 Runtime 回调 Manager 时放在 `X-Agent-Service-Token` 的 token。
3. 两个 token 可以不同，不要写进前端或日志。
4. 如果 Runtime 返回 `swarm_id`，Manager 会保存到 `runtime_swarm_id`。
5. 如果 Runtime 返回 `deployment_id`，Manager 会保存到 `runtime_deployment_id`。

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

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

```bash
AGENT_RUNTIME_ENABLED=true
AGENT_RUNTIME_ASYNC=false
AGENT_RUNTIME_BASE_URL=http://52.139.240.116:8000
AGENT_RUNTIME_SERVICE_TOKEN=<optional-if-supported>
AGENT_RUNTIME_HEALTH_PATH=/health
AGENT_RUNTIME_CREATE_PATH=/tasks
AGENT_RUNTIME_STOP_PATH=/tasks/{runtime_deployment_id}/stop
AGENT_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
AGENT_RUNTIME_TIMEOUT_SECONDS=10
HEICODE_PUBLIC_BASE_URL=https://code.xinghanlab.com
AGENT_RUNTIME_CALLBACK_URL=https://code.xinghanlab.com/api/agent/callbacks/swarm-events
AGENT_CALLBACK_TOKEN=<callback-token>
```

注意：

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

## 三、Runtime 回调 Manager 的请求头

推荐使用 service token：

```http
POST /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：

```http
X-Agent-Event-Id: <event-id>
X-Agent-Timestamp: <unix-ms>
X-Agent-Signature: sha256=<hex>
X-Correlation-ID: <correlation-id>
Content-Type: application/json
```

签名内容：

```text
timestamp + "." + event_id + "." + raw_body
```

## 四、最小联调命令

健康检查：

```bash
curl -sS "$AGENT_RUNTIME_BASE_URL$AGENT_RUNTIME_HEALTH_PATH"
```

Manager 本地默认模拟链路：

```bash
curl -sS -X POST "https://code.xinghanlab.com/api/agent/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：

```bash
curl -sS -X POST "https://code.xinghanlab.com/api/agent/callbacks/swarm-events" \
  -H "Content-Type: application/json" \
  -H "X-Agent-Service-Token: $AGENT_CALLBACK_TOKEN" \
  -H "X-Agent-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"
    }
  }'
```

成功响应：

```json
{
  "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 中无长期明文密钥 |