zhanggangyong/agent_management
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Sync sub-mode runtime docs and k8s updates

Browse Source
This commit is contained in:
elipitc
2026-06-01 23:10:33 +08:00
parent 9bc172b22a
commit 1b49887819
19 changed files with 511 additions and 384 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/HEICODE_API_INTEGRATION.md
+66 -66
View File
@@ -23,7 +23,7 @@
- **当前 AKS 镜像 digest**: `sha256:b1931c1172fc23da8234e96dbdca34c4704644c2b2099391b362a48c47dc68f4`
- **Base URL（当前联调）**: `http://20.212.121.126`
- **Base URL（域名待切换）**: `https://agent-manager.taijiagnet.com`
- **主 API 前缀**: `/api/agnet`
- **主 API 前缀**: `/api/agent`
- **Runtime 兼容前缀**: `/api/swarms`
### 1.2 核心功能
@@ -50,7 +50,7 @@
▼
┌─────────────────────────────┐
│ Agent Manager API │
│ /api/agnet/* │
│ /api/agent/* │
└──────┬──────────────────────┘
│
▼
@@ -69,7 +69,7 @@
| 系统 | 职责 | 说明 |
|------|------|------|
| Heicode Manager | 用户、资源绑定、模型网关配置、审批、部署草稿、权限清单、回调持久化、artifact/timeline 展示 | 已有本地控制面和生产页面 |
| Agent Manager / Agnet Runtime | 接收 Manager 传入的部署计划，真实创建/调度子 Agent，执行任务，按回调协议回写状态、产物、用量和审批请求 | 需要支持本文定义的请求与回调字段 |
| Agent Manager / Agent Runtime | 接收 Manager 传入的部署计划，真实创建/调度子 Agent，执行任务，按回调协议回写状态、产物、用量和审批请求 | 需要支持本文定义的请求与回调字段 |
| Azure Key Vault | 长期密钥托管 | Manager/Runtime 只能使用 `azkv://...` 引用，不能传明文密钥 |
| NewAPI / CodeGW | 模型网关与计费入口 | Runtime 使用 Manager 提供的模型、预算和 `secret_ref` 上下文 |
@@ -89,7 +89,7 @@
| Callback HMAC 验签 | 已支持 | 支持 `X-Agnet-Signature` / `X-Agnet-Timestamp` / `X-Agnet-Event-Id` |
| Callback 旧认证兼容 | 已支持 | 过渡期仍接受 `X-Agnet-Service-Token` 或 `Authorization: Bearer` |
| Callback 幂等 | 已支持 | 优先读 `X-Agnet-Event-Id`，兼容 body `event_id` |
| Runtime 主动回调 | 已支持 | `/api/agnet/deployments` 与 `/api/swarms` 创建的 Runtime 执行阶段会主动推送 status/phase/timeline/agent/tool/artifact 事件 |
| Runtime 主动回调 | 已支持 | `/api/agent/sub-agile/deployments` 与 `/api/swarms` 创建的 Runtime 执行阶段会主动推送 status/phase/timeline/agent/tool/artifact 事件 |
| 普通 sub 真实 artifact 回调 | 已支持 | 普通 sub agent 真正执行后会生成 `artifact.created`，不再只返回 completed |
| Runtime artifact 内容读取 | 已支持 | Runtime 会优先用 K8s Secret 中的 Azure Blob 凭据上传完整产物；失败时回落本地 artifact store，metadata 中返回 URI、`content_hash` 和下载路径 |
| 普通 sub task 终态回调 | 已支持 | 新增 `task.completed` / `task.failed` / `task.blocked` 事件 |
@@ -103,7 +103,7 @@
| 顶层 `resource_grants` | 已支持 | 兼容 `agents[].resource_grants` 汇总 |
| legacy ResourceGrant 字段 | 已支持 | 兼容 `type / permissions / ref` 与 `resource_type / permission_scope / secret_ref` |
| artifact/timeline/SK snapshot 查询 | 已支持 | 从 callback 事件投影到用户态查询接口 |
| `approval.requested` / decision | 已支持 | callback 会持久化审批请求；Runtime 接收 `/api/swarms/{swarm_id}/approvals/{approval_id}` 与 `/api/agnet/deployments/{deployment_id}/approvals/{approval_id}` decision |
| `approval.requested` / decision | 已支持 | callback 会持久化审批请求；Runtime 接收 `/api/swarms/{swarm_id}/approvals/{approval_id}` 与 `/api/agent/sub-agile/deployments/{deployment_id}/approvals/{approval_id}` decision |
| `/api/swarms` 运行期查询 | 已支持 | 兼容 `status`、`stop`、`logs`、`events`、`metrics` 查询/控制路径 |
| `/api/swarms` 创建校验 | 已支持 | 缺少 `orchestration_plan` / `callback.url` / `sub_mode` / `user_context.user_id` 返回 422；`dry_run:true` 返回 422 且不创建真实 run |
| `/api/swarms` 幂等 | 已支持 | 同一个 `X-Idempotency-Key` 返回已有 run，不重复创建 |
@@ -124,14 +124,14 @@
| 场景 | 推荐接口 | 当前状态 |
|------|----------|----------|
| 健康检查 | `GET /api/agnet/health` | 已支持，无需业务 Header |
| 健康检查 | `GET /api/agent/health` | 已支持，无需业务 Header |
| 普通 sub 创建 Runtime run | `POST /api/swarms` | 已支持，要求结构化 `orchestration_plan` 和 `callback.url` |
| 旧版 Agent 部署创建 | `POST /api/agnet/deployments` | 已支持，可兼容结构化 sub plan |
| Runtime 主动事件回写 | `POST /api/agnet/callbacks/swarm-events` | 已支持 HMAC / 旧 token 过渡认证和幂等 |
| 旧版 Agent 部署创建 | `POST /api/agent/sub-agile/deployments` | 已支持，可兼容结构化 sub plan |
| Runtime 主动事件回写 | `POST /api/agent/callbacks/runtime-events` | 已支持 HMAC / 旧 token 过渡认证和幂等 |
| 查询 Runtime 状态 | `GET /api/swarms/{swarm_id}` 或 `/status` | 已支持，`deployment_id` 与 `swarm_id` 当前同值 |
| 查询产物 | `GET /api/agnet/user/deployments/{deployment_id}/artifacts` | 已支持，由 callback event 投影 |
| 查询时间线 | `GET /api/agnet/user/deployments/{deployment_id}/timeline` | 已支持，由 callback event 合并 |
| 查询 SK snapshot | `GET /api/agnet/user/deployments/{deployment_id}/sk-snapshots` | 已支持投影查询，独立解析接口待增强 |
| 查询产物 | `GET /api/agent/user/deployments/{deployment_id}/artifacts` | 已支持，由 callback event 投影 |
| 查询时间线 | `GET /api/agent/user/deployments/{deployment_id}/timeline` | 已支持，由 callback event 合并 |
| 查询 SK snapshot | `GET /api/agent/user/deployments/{deployment_id}/sk-snapshots` | 已支持投影查询，独立解析接口待增强 |
| 审批 decision | `POST /api/swarms/{swarm_id}/approvals/{approval_id}` | 已支持 `approved` / `rejected` |
当前实现边界：
@@ -149,8 +149,8 @@
1. 创建 Runtime run 后保存返回的 `deployment_id` / `swarm_id`。当前实现里二者同值。
2. 通过 callback 里的 `artifact.created` 事件，或轮询 `GET /api/swarms/{swarm_id}/status` 判断是否已有 artifact。
3. 调用 `GET /api/agnet/user/deployments/{deployment_id}/artifacts` 获取产物列表。
4. 从列表中取 `artifact_id`，调用 `GET /api/agnet/user/deployments/{deployment_id}/artifacts/{artifact_id}/content` 下载完整内容。
3. 调用 `GET /api/agent/user/deployments/{deployment_id}/artifacts` 获取产物列表。
4. 从列表中取 `artifact_id`，调用 `GET /api/agent/user/deployments/{deployment_id}/artifacts/{artifact_id}/content` 下载完整内容。
5. 如果 Manager 需要直接访问 Runtime 兼容层，也可以调用 `GET /api/swarms/{swarm_id}/artifacts/{artifact_id}/content`。
示例：
@@ -162,7 +162,7 @@ DEPLOYMENT_ID="swm_xxx"
curl -sS \
-H "Authorization: Bearer ${TOKEN}" \
"${BASE_URL}/api/agnet/user/deployments/${DEPLOYMENT_ID}/artifacts"
"${BASE_URL}/api/agent/user/deployments/${DEPLOYMENT_ID}/artifacts"
```
列表响应中的关键字段：
@@ -198,7 +198,7 @@ ARTIFACT_ID="art_backend_patch_001"
curl -L \
-H "Authorization: Bearer ${TOKEN}" \
-o "${ARTIFACT_ID}.txt" \
"${BASE_URL}/api/agnet/user/deployments/${DEPLOYMENT_ID}/artifacts/${ARTIFACT_ID}/content"
"${BASE_URL}/api/agent/user/deployments/${DEPLOYMENT_ID}/artifacts/${ARTIFACT_ID}/content"
```
生产环境产物存储规则：
@@ -256,7 +256,7 @@ Authorization: Bearer <HEICODE_SERVICE_TOKEN>
| `X-Idempotency-Key` | ⚪ | 幂等性键（推荐） | `idem_abc123` |
| `Content-Type` | ✅ | 内容类型 | `application/json` |
> `GET /api/agnet/health` 用于 K8s / LB 探活，不要求 `Authorization` 或业务追踪 Header。
> `GET /api/agent/health` 用于 K8s / LB 探活，不要求 `Authorization` 或业务追踪 Header。
### 2.3 获取 Service Token
@@ -268,13 +268,13 @@ Authorization: Bearer <HEICODE_SERVICE_TOKEN>
### 3.1 健康检查
#### `GET /api/agnet/health`
#### `GET /api/agent/health`
检查服务状态。
**请求示例**:
```bash
curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/health"
curl -X GET "https://agent-manager.taijiagnet.com/api/agent/health"
```
**响应示例**:
@@ -294,7 +294,7 @@ curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/health"
### 3.2 创建部署
#### `POST /api/agnet/deployments`
#### `POST /api/agent/sub-agile/deployments`
创建一个新的 Agent 部署。
@@ -332,7 +332,7 @@ curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/health"
}
],
"callback": {
"url": "https://code.xinghanlab.com/api/agnet/callbacks/swarm-events",
"url": "https://code.xinghanlab.com/api/agent/callbacks/runtime-events",
"signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agnet-callback-signing-key",
"subscribed_events": [
"phase.changed",
@@ -389,13 +389,13 @@ curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/health"
- `orchestration_plan.billing_context.default_model_id` / `allowed_model_ids` / `secret_ref` 会透传到 Runtime 配置。
- `resource_grants` 可放在顶层，也可放在 `agents[].resource_grants`，Runtime 会做兼容汇总。
- 如果请求包含 `callback`，Runtime 会按订阅事件主动回调 `deployment.status_changed`、`phase.changed`、`timeline.updated`、`agent.started`、`artifact.created`，并在需要审批时回调 `approval.requested`。
- `callback.url` 在 `/api/agnet/deployments` 中必须为 `https://`，`callback.signing_secret_ref` 必须为 `azkv://`。
- `callback.url` 在 `/api/agent/sub-agile/deployments` 中必须为 `https://`，`callback.signing_secret_ref` 必须为 `azkv://`。
---
### 3.3 列出部署
#### `GET /api/agnet/deployments`
#### `GET /api/agent/sub-agile/deployments`
获取部署列表，支持过滤和分页。
@@ -410,7 +410,7 @@ curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/health"
**请求示例**:
```bash
curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/deployments?user_id=user_123&status=running&limit=10" \
curl -X GET "https://agent-manager.taijiagnet.com/api/agent/sub-agile/deployments?user_id=user_123&status=running&limit=10" \
-H "Authorization: Bearer sk_xxx" \
-H "X-User-ID: user_123" \
-H "X-Binding-Scope: workspace_abc" \
@@ -445,7 +445,7 @@ curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/deployments?user_id=
### 3.4 获取部署详情
#### `GET /api/agnet/deployments/{deployment_id}`
#### `GET /api/agent/sub-agile/deployments/{deployment_id}`
获取指定部署的详细信息。
@@ -454,7 +454,7 @@ curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/deployments?user_id=
**请求示例**:
```bash
curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2c3d4e5f6" \
curl -X GET "https://agent-manager.taijiagnet.com/api/agent/sub-agile/deployments/dep_a1b2c3d4e5f6" \
-H "Authorization: Bearer sk_xxx" \
-H "X-User-ID: user_123" \
-H "X-Binding-Scope: workspace_abc" \
@@ -510,7 +510,7 @@ curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2
### 3.5 停止部署
#### `POST /api/agnet/deployments/{deployment_id}/stop`
#### `POST /api/agent/sub-agile/deployments/{deployment_id}/stop`
停止一个正在运行的部署。
@@ -527,7 +527,7 @@ curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2
**请求示例**:
```bash
curl -X POST "https://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2c3d4e5f6/stop" \
curl -X POST "https://agent-manager.taijiagnet.com/api/agent/sub-agile/deployments/dep_a1b2c3d4e5f6/stop" \
-H "Authorization: Bearer sk_xxx" \
-H "X-User-ID: user_123" \
-H "X-Binding-Scope: workspace_abc" \
@@ -551,7 +551,7 @@ curl -X POST "https://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b
### 3.6 获取部署日志
#### `GET /api/agnet/deployments/{deployment_id}/logs`
#### `GET /api/agent/sub-agile/deployments/{deployment_id}/logs`
获取部署的实时日志。
@@ -567,7 +567,7 @@ curl -X POST "https://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b
**请求示例**:
```bash
curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2c3d4e5f6/logs?limit=50" \
curl -X GET "https://agent-manager.taijiagnet.com/api/agent/sub-agile/deployments/dep_a1b2c3d4e5f6/logs?limit=50" \
-H "Authorization: Bearer sk_xxx" \
-H "X-User-ID: user_123" \
-H "X-Binding-Scope: workspace_abc" \
@@ -604,7 +604,7 @@ curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2
### 3.7 获取部署事件
#### `GET /api/agnet/deployments/{deployment_id}/events`
#### `GET /api/agent/sub-agile/deployments/{deployment_id}/events`
获取部署的事件历史。
@@ -629,7 +629,7 @@ curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2
**请求示例**:
```bash
curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2c3d4e5f6/events" \
curl -X GET "https://agent-manager.taijiagnet.com/api/agent/sub-agile/deployments/dep_a1b2c3d4e5f6/events" \
-H "Authorization: Bearer sk_xxx" \
-H "X-User-ID: user_123" \
-H "X-Binding-Scope: workspace_abc" \
@@ -670,7 +670,7 @@ curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2
### 3.8 获取资源指标
#### `GET /api/agnet/deployments/{deployment_id}/metrics`
#### `GET /api/agent/sub-agile/deployments/{deployment_id}/metrics`
获取部署的资源使用指标。
@@ -679,7 +679,7 @@ curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2
**请求示例**:
```bash
curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2c3d4e5f6/metrics" \
curl -X GET "https://agent-manager.taijiagnet.com/api/agent/sub-agile/deployments/dep_a1b2c3d4e5f6/metrics" \
-H "Authorization: Bearer sk_xxx" \
-H "X-User-ID: user_123" \
-H "X-Binding-Scope: workspace_abc" \
@@ -730,11 +730,11 @@ curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2
### 3.9 Runtime Callback 回写
#### `POST /api/agnet/callbacks/swarm-events`
#### `POST /api/agent/callbacks/runtime-events`
Agent Manager / Runtime 使用该接口向 Heicode Manager 回写 sub 模式事件、阶段变化、产物、预算告警、审批请求和 SK 工具调用结果。该接口是反向通知协议，不能仅依赖 `/events` 轮询替代。
#### `GET /api/agnet/callbacks/swarm-events/schema`
#### `GET /api/agent/callbacks/runtime-events/schema`
联调前可读取 callback schema。该接口只返回事件类型、分类、必填字段、阶段枚举和 artifact 类型，不返回 token、secret 或任何明文密钥。
@@ -826,7 +826,7 @@ Runtime 发送端签名密钥解析顺序：
| 触发时机 | 事件 |
|----------|------|
| `/api/agnet/deployments` 创建 accepted/running | `deployment.status_changed`、`phase.changed`、`timeline.updated`、`agent.started`、`artifact.created` |
| `/api/agent/sub-agile/deployments` 创建 accepted/running | `deployment.status_changed`、`phase.changed`、`timeline.updated`、`agent.started`、`artifact.created` |
| Swarm 初始化 / 运行 / 完成 / 失败 / 停止 | `deployment.status_changed` |
| 规划、实现、检查、完成等阶段变化 | `phase.changed`、`timeline.updated` |
| Agent 可运行 | `agent.started` |
@@ -879,22 +879,22 @@ Runtime 发送端签名密钥解析顺序：
| 方法 | 路径 | 调用方 | 用途 |
|------|------|--------|------|
| `POST` | `/api/agnet/user/tasks/{task_id}/deployment-draft` | Heicode 客户端 / Manager 前端 | 从任务卡生成 Agnet deployment draft |
| `POST` | `/api/agnet/user/deployments` | Heicode 客户端 / Manager 前端 | 用户态创建部署记录 |
| `GET` | `/api/agnet/user/deployments` | Heicode 客户端 / Manager 前端 | 用户态部署列表 |
| `GET` | `/api/agnet/user/deployments/{deployment_id}` | Heicode 客户端 / Manager 前端 | 用户态部署详情 |
| `POST` | `/api/agent/user/tasks/{task_id}/deployment-draft` | Heicode 客户端 / Manager 前端 | 从任务卡生成 Agent deployment draft |
| `POST` | `/api/agent/user/deployments` | Heicode 客户端 / Manager 前端 | 用户态创建部署记录 |
| `GET` | `/api/agent/user/deployments` | Heicode 客户端 / Manager 前端 | 用户态部署列表 |
| `GET` | `/api/agent/user/deployments/{deployment_id}` | Heicode 客户端 / Manager 前端 | 用户态部署详情 |
| `POST` | `/api/swarms` | Runtime 对接适配 / Manager | 创建 Swarm Run 的兼容入口，目前映射到 Manager 本地部署控制面 |
| `POST` | `/api/agnet/callbacks/swarm-events` | Agent Manager / Runtime | Runtime 回写状态、事件、artifact |
| `GET` | `/api/agnet/user/deployments/{deployment_id}/artifacts` | Heicode 客户端 / Manager 前端 | 查询部署产物 |
| `GET` | `/api/agnet/user/deployments/{deployment_id}/artifacts/{artifact_id}/content` | Heicode 客户端 / Manager 前端 | 下载完整产物内容 |
| `GET` | `/api/agnet/user/deployments/{deployment_id}/sk-snapshots` | Heicode 客户端 / Manager 前端 | 查询 SK 快照 |
| `GET` | `/api/agnet/user/deployments/{deployment_id}/timeline` | Heicode 客户端 / Manager 前端 | 查询合并时间线 |
| `POST` | `/api/agent/callbacks/runtime-events` | Agent Manager / Runtime | Runtime 回写状态、事件、artifact |
| `GET` | `/api/agent/user/deployments/{deployment_id}/artifacts` | Heicode 客户端 / Manager 前端 | 查询部署产物 |
| `GET` | `/api/agent/user/deployments/{deployment_id}/artifacts/{artifact_id}/content` | Heicode 客户端 / Manager 前端 | 下载完整产物内容 |
| `GET` | `/api/agent/user/deployments/{deployment_id}/sk-snapshots` | Heicode 客户端 / Manager 前端 | 查询 SK 快照 |
| `GET` | `/api/agent/user/deployments/{deployment_id}/timeline` | Heicode 客户端 / Manager 前端 | 查询合并时间线 |
说明：
1. `POST /api/swarms` 当前返回 `deployment_id` 和 `swarm_id`；当前二者同值，均可用于 Runtime 查询和停止。
2. 后续如果 Runtime 返回自己的真实 `swarm_id`，Manager 需要保存 `deployment_id <-> swarm_id` 映射。
3. Runtime 侧不能只支持 `/api/agnet/deployments`，否则无法覆盖 Heicode 用户态任务流。
3. Runtime 侧不能只支持 `/api/agent/sub-agile/deployments`，否则无法覆盖 Heicode 用户态任务流。
#### `POST /api/swarms`
@@ -951,7 +951,7 @@ Heicode sub 模式兼容入口。该接口接受结构化 `orchestration_plan`
"resource_grants": []
},
"callback": {
"url": "https://code.xinghanlab.com/api/agnet/callbacks/swarm-events",
"url": "https://code.xinghanlab.com/api/agent/callbacks/runtime-events",
"signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agnet-callback-signing-key"
}
}
@@ -980,7 +980,7 @@ Heicode sub 模式兼容入口。该接口接受结构化 `orchestration_plan`
}
},
"callback": {
"url": "https://code.xinghanlab.com/api/agnet/callbacks/swarm-events",
"url": "https://code.xinghanlab.com/api/agent/callbacks/runtime-events",
"signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agnet-callback-signing-key"
}
}
@@ -1039,7 +1039,7 @@ Heicode sub 模式兼容入口。该接口接受结构化 `orchestration_plan`
如果普通 sub 不走 `/api/swarms`，也支持：
```http
POST /api/agnet/deployments/{deployment_id}/approvals/{approval_id}
POST /api/agent/sub-agile/deployments/{deployment_id}/approvals/{approval_id}
```
**响应示例**：
@@ -1087,7 +1087,7 @@ POST /api/agnet/deployments/{deployment_id}/approvals/{approval_id}
}
```
#### `GET /api/agnet/user/deployments/{deployment_id}/artifacts`
#### `GET /api/agent/user/deployments/{deployment_id}/artifacts`
查询 Runtime 通过 `artifact.created` callback 回写的产物。当前 Manager 从 callback event payload 投影生成响应；大文件只返回 `uri`、摘要、大小和 hash 信息，完整内容需要继续调用 artifact content 接口读取。完整操作流程见 [1.7 产物获取速查](#17-产物获取速查)。
@@ -1119,7 +1119,7 @@ POST /api/agnet/deployments/{deployment_id}/approvals/{approval_id}
}
```
#### `GET /api/agnet/user/deployments/{deployment_id}/artifacts/{artifact_id}/content`
#### `GET /api/agent/user/deployments/{deployment_id}/artifacts/{artifact_id}/content`
读取 Runtime artifact 的完整内容。该接口是 Manager / 前端获取产物正文的推荐入口，要求携带 `Authorization: Bearer <HEICODE_SERVICE_TOKEN>`。
@@ -1138,7 +1138,7 @@ Azure Blob 凭据来自 `RUNTIME_ARTIFACT_BLOB_SECRET_NAMESPACE` / `RUNTIME_ARTI
curl -L \
-H "Authorization: Bearer <HEICODE_SERVICE_TOKEN>" \
-o artifact-output.txt \
"https://agent-manager.taijiagnet.com/api/agnet/user/deployments/{deployment_id}/artifacts/{artifact_id}/content"
"https://agent-manager.taijiagnet.com/api/agent/user/deployments/{deployment_id}/artifacts/{artifact_id}/content"
```
如果调用方已经持有 Runtime `swarm_id`，也可以直接使用兼容接口：
@@ -1150,7 +1150,7 @@ curl -L \
"https://agent-manager.taijiagnet.com/api/swarms/{swarm_id}/artifacts/{artifact_id}/content"
```
#### `GET /api/agnet/user/deployments/{deployment_id}/timeline`
#### `GET /api/agent/user/deployments/{deployment_id}/timeline`
查询合并时间线。当前 Manager 会合并 `timeline.updated`、阶段变化、Agent 状态、预算告警、审批请求、artifact 与 SK 工具事件。
@@ -1180,7 +1180,7 @@ curl -L \
}
```
#### `GET /api/agnet/user/deployments/{deployment_id}/sk-snapshots`
#### `GET /api/agent/user/deployments/{deployment_id}/sk-snapshots`
查询 Runtime 回写的 SK snapshot。当前 Manager 从 `sk_tool.called/completed/failed` 和包含 `sk_snapshot` 的 artifact 事件投影生成响应。
@@ -1322,7 +1322,7 @@ Heicode sub 模式使用扩展 Resource Grant 表达任务资源授权。Runtime
### 4.8 Artifact 回写模型
Runtime 通过 `/api/agnet/callbacks/swarm-events` 回写产物事件，Manager 将其持久化后供用户态接口查询。
Runtime 通过 `/api/agent/callbacks/runtime-events` 回写产物事件，Manager 将其持久化后供用户态接口查询。
```json
{
@@ -1458,7 +1458,7 @@ create_payload = {
}
response = requests.post(
f"{BASE_URL}/api/agnet/deployments",
f"{BASE_URL}/api/agent/sub-agile/deployments",
headers=headers,
json=create_payload
)
@@ -1471,7 +1471,7 @@ time.sleep(120) # 等待 2 分钟
# 3. 获取部署详情
response = requests.get(
f"{BASE_URL}/api/agnet/deployments/{deployment_id}",
f"{BASE_URL}/api/agent/sub-agile/deployments/{deployment_id}",
headers=headers
)
details = response.json()
@@ -1479,7 +1479,7 @@ print(f"📊 部署状态: {details['status']}")
# 4. 获取实时日志
response = requests.get(
f"{BASE_URL}/api/agnet/deployments/{deployment_id}/logs?limit=20",
f"{BASE_URL}/api/agent/sub-agile/deployments/{deployment_id}/logs?limit=20",
headers=headers
)
logs = response.json()
@@ -1487,7 +1487,7 @@ print(f"📝 最新日志: {len(logs['logs'])} 条")
# 5. 获取资源指标
response = requests.get(
f"{BASE_URL}/api/agnet/deployments/{deployment_id}/metrics",
f"{BASE_URL}/api/agent/sub-agile/deployments/{deployment_id}/metrics",
headers=headers
)
metrics = response.json()
@@ -1499,7 +1499,7 @@ stop_payload = {
"reason": "Task completed successfully"
}
response = requests.post(
f"{BASE_URL}/api/agnet/deployments/{deployment_id}/stop",
f"{BASE_URL}/api/agent/sub-agile/deployments/{deployment_id}/stop",
headers=headers,
json=stop_payload
)
@@ -1527,14 +1527,14 @@ headers = {
# 第一次请求
response1 = requests.post(
f"{BASE_URL}/api/agnet/deployments",
f"{BASE_URL}/api/agent/sub-agile/deployments",
headers=headers,
json=create_payload
)
# 重复请求（使用相同的 idempotency_key）
response2 = requests.post(
f"{BASE_URL}/api/agnet/deployments",
f"{BASE_URL}/api/agent/sub-agile/deployments",
headers=headers,
json=create_payload
)
@@ -1589,7 +1589,7 @@ payload = {
]
},
"callback": {
"url": "https://code.xinghanlab.com/api/agnet/callbacks/swarm-events",
"url": "https://code.xinghanlab.com/api/agent/callbacks/runtime-events",
"signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agnet-callback-signing-key"
}
}
@@ -1604,7 +1604,7 @@ status.raise_for_status()
print(status.json()["status"])
timeline = requests.get(
f"{BASE_URL}/api/agnet/user/deployments/{run['deployment_id']}/timeline",
f"{BASE_URL}/api/agent/user/deployments/{run['deployment_id']}/timeline",
headers={"Authorization": f"Bearer {TOKEN}"}
)
timeline.raise_for_status()
@@ -1655,7 +1655,7 @@ print(len(timeline.json()["timeline"]))
```python
try:
response = requests.post(
f"{BASE_URL}/api/agnet/deployments",
f"{BASE_URL}/api/agent/sub-agile/deployments",
headers=headers,
json=create_payload
)
@@ -1763,7 +1763,7 @@ except requests.exceptions.HTTPError as e:
| v2.1.6 | 2026-05-29 | 修复普通 sub 真实执行后缺失 `artifact.created` 的问题，新增 `task.completed` / `task.failed` / `task.blocked` 事件，修复 deployment 与 agents 终态不一致，`/api/swarms/{id}/logs` 改为返回 Runtime 聚合摘要；部署镜像更新为 `heicode-v2-20260529120632` |
| v2.1.5 | 2026-05-28 | 文档修订：新增 v2.1.4 联调速查，补充 `/api/swarms` 最小请求、校验失败、状态响应和普通 sub 联调示例；修正 callback 当前实现为失败只记录 warning，重试/死信/replay 为后续增强 |
| v2.1.4 | 2026-05-28 | 按普通 sub 联调整改要求补齐 `/api/swarms` 参数校验、`dry_run` 拒绝、`deployment_id` 返回、detail 根路径、幂等创建和 usage/cost callback 字段；当前联调 Base URL 明确为 `http://20.212.121.126`，部署镜像更新为 `heicode-v2-20260528164612` |
| v2.1.3 | 2026-05-28 | 按普通 sub 敏捷模式任务清单补齐 `/api/agnet/deployments` 主动回调、`role_template` 兼容、callback schema、`/api/swarms/{id}` stop/status/logs/events/metrics、approval decision 接收路径，部署镜像更新为 `heicode-v2-20260528161931` |
| v2.1.3 | 2026-05-28 | 按普通 sub 敏捷模式任务清单补齐 `/api/agent/sub-agile/deployments` 主动回调、`role_template` 兼容、callback schema、`/api/swarms/{id}` stop/status/logs/events/metrics、approval decision 接收路径，部署镜像更新为 `heicode-v2-20260528161931` |
| v2.1.2 | 2026-05-28 | Agent Manager Runtime 支持按 callback 配置主动推送 status/phase/timeline/agent/tool/artifact 事件，补充发送端签名密钥解析顺序和失败策略，部署镜像更新为 `heicode-v2-20260528144233` |
| v2.1.1 | 2026-05-27 | 同步 Manager 当前实现状态：callback HMAC/旧 token 兼容、payload 投影、默认 subscribed_events、artifact/timeline/SK snapshot 查询示例、部署镜像版本 |
| v2.1.0 | 2026-05-26 | 补充 Heicode sub 模式敏捷开发契约、`/api/swarms` 兼容入口、`azkv://` secret_ref、artifact/timeline/SK snapshot 模型 |