Add template agent lifecycle compatibility APIs
This commit is contained in:
elipitc
@@ -31,6 +31,7 @@
|
||||
- ✅ 多 Agent 编排部署
|
||||
- ✅ Heicode sub 模式敏捷开发对接（agile / waterfall）
|
||||
- ✅ `/api/swarms` Runtime 适配入口
|
||||
- ✅ 模板 Agent `/agents` 生命周期兼容接口
|
||||
- ✅ 预算控制和计费管理
|
||||
- ✅ 风险等级评估（low/medium/high）
|
||||
- ✅ Azure Key Vault `secret_ref` 引用
|
||||
@@ -110,6 +111,7 @@
|
||||
| usage / cost 回传 | 已支持 | `budget.alert` payload 带 `model_id`、token、成本、运行时长、资源秒、`billing_source` 和预算摘要 |
|
||||
| `/api/swarms/{id}/logs` 日志兜底 | 已支持 | 返回 Runtime 聚合日志摘要，不再只是固定占位文本 |
|
||||
| 空产物终态兜底 | 已支持 | 普通 sub terminal run 若未存储 concrete artifact，会生成 Runtime summary/failure artifact，并在 `/api/swarms/{id}`、`events`、`metrics` 中可见 |
|
||||
| 模板 Agent `/agents` 生命周期兼容 | 已支持 | `POST /agents` 响应补充 `runtime_id` / `agent_id` / `id` / `runtime_status` / `state` / `subdomain`，并新增 `GET /agents/{id}`、`POST /agents/{id}/stop` |
|
||||
|
||||
仍属于后续增强或 Runtime 侧职责：
|
||||
|
||||
@@ -133,6 +135,7 @@
|
||||
| 查询时间线 | `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` |
|
||||
| 模板 Agent 生命周期 | `POST /agents`、`GET /agents/{id}`、`POST /agents/{id}/stop`、`DELETE /agents/{id}` | 已支持，适合 HM 模板 Agent 联调 |
|
||||
|
||||
当前实现边界：
|
||||
|
||||
@@ -1213,6 +1216,104 @@ curl -L \
|
||||
|
||||
---
|
||||
|
||||
### 3.11 模板 Agent Runtime 兼容接口
|
||||
|
||||
除 sub-mode runtime 外，当前仓库也保留了模板 Agent 的旧版统一入口 `POST /agents`。为对齐 HM 的模板 Agent 联调，本节补充这组接口的生命周期兼容契约。
|
||||
|
||||
#### 生命周期接口列表
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| `POST` | `/agents` | 创建模板 Agent；返回 HM 可直接解析的实例标识和访问地址别名字段 |
|
||||
| `GET` | `/agents/{agent_name}` | 查询模板 Agent 生命周期状态；返回平铺 `status` / `runtime_status` / `state` |
|
||||
| `POST` | `/agents/{agent_name}/stop` | 幂等停止模板 Agent；停止运行 Pod，但保留数据库记录 |
|
||||
| `DELETE` | `/agents/{agent_name}` | 删除模板 Agent 运行资源和数据库记录 |
|
||||
| `GET` | `/agents/{agent_name}/status` | 查询详细 Pod/容器状态与访问信息，适合排障 |
|
||||
| `GET` | `/agents/{agent_name}/metrics` | 查询模板 Agent 资源使用信息 |
|
||||
|
||||
#### `POST /agents`
|
||||
|
||||
请求示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "dep-b5fab27e9255",
|
||||
"template": "coding_a2a_agent",
|
||||
"framework": "A2A",
|
||||
"config": {
|
||||
"user_id": "22",
|
||||
"manager_deployment_id": "dep_b5fab27e9255",
|
||||
"callback_url": "https://code.xinghanlab.com/api/agent/callbacks/runtime-events"
|
||||
},
|
||||
"env": {
|
||||
"AGENT_ROLE_NAME": "architect",
|
||||
"AGENT_INSTRUCTION_TEXT": "---\nname: architect\n---\n<Agent_Prompt>...</Agent_Prompt>",
|
||||
"OPENAI_BASE_URL": "https://code.xinghanlab.com/v1",
|
||||
"OPENAI_API_KEY": "sk-xxxx",
|
||||
"MODEL_NAME": "gpt-5.4"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
响应示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "dep-b5fab27e9255",
|
||||
"runtime_id": "dep-b5fab27e9255",
|
||||
"agent_id": "dep-b5fab27e9255",
|
||||
"id": "dep-b5fab27e9255",
|
||||
"namespace": "agent-dep-b5fab27e9255",
|
||||
"status": "running",
|
||||
"runtime_status": "running",
|
||||
"state": "running",
|
||||
"framework": "A2A",
|
||||
"subdomain": "dep-b5fab27e9255.taijiagnet.com",
|
||||
"access_token": null,
|
||||
"access_info": {
|
||||
"domain": "dep-b5fab27e9255.taijiagnet.com",
|
||||
"domain_url": "http://dep-b5fab27e9255.taijiagnet.com",
|
||||
"external_ip": "20.212.121.126"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
字段兼容约定：
|
||||
|
||||
- `runtime_id` / `agent_id` / `id` 当前都等于 Agent 名称，可直接作为后续生命周期调用的实例标识。
|
||||
- `subdomain` 取自 `access_info.domain`，若 DNS 尚未就绪则回退到 `access_info.external_ip`。
|
||||
- `runtime_status` / `state` 是对 Pod 生命周期的兼容投影；当前可能值为 `pending`、`running`、`stopped`、`failed`。
|
||||
|
||||
#### `GET /agents/{agent_name}`
|
||||
|
||||
用于 HM 轮询模板 Agent 生命周期。返回体与 `POST /agents` 的核心生命周期字段保持一致，便于 HM 复用同一套解析逻辑。
|
||||
|
||||
#### `POST /agents/{agent_name}/stop`
|
||||
|
||||
响应示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"message": "Agent dep-b5fab27e9255 已停止"
|
||||
}
|
||||
```
|
||||
|
||||
约定：
|
||||
|
||||
- 该接口为幂等停止接口。
|
||||
- 停止动作会删除当前运行 Pod，并将数据库中的 Agent 状态收敛为 `stopped`。
|
||||
- 若要彻底清理实例，请在停止后继续调用 `DELETE /agents/{agent_name}`。
|
||||
|
||||
#### `DELETE /agents/{agent_name}`
|
||||
|
||||
说明：
|
||||
|
||||
- 删除接口当前已修复模板 Agent 场景下的数据库变量引用问题，不再出现此前的 `UnboundLocalError` 500。
|
||||
- 删除动作会清理 DNS、K8s namespace 以及数据库中的 Agent 记录。
|
||||
|
||||
---
|
||||
|
||||
## 4. 数据模型
|
||||
|
||||
### 4.1 部署状态 (DeploymentStatus)
|
||||
@@ -1756,6 +1857,7 @@ except requests.exceptions.HTTPError as e:
|
||||
|
||||
| 版本 | 日期 | 更新内容 |
|
||||
|------|------|----------|
|
||||
| v2.1.11 | 2026-06-04 | 补充模板 Agent `/agents` 生命周期兼容文档：新增 `GET /agents/{id}`、`POST /agents/{id}/stop`、`DELETE /agents/{id}`、`GET /agents/{id}/status` 的联调说明；同步说明 `POST /agents` 额外返回 `runtime_id` / `agent_id` / `id` / `runtime_status` / `state` / `subdomain`，并记录删除接口 500 bug 已修复 |
|
||||
| v2.1.10 | 2026-05-30 | 文档补充生产环境产物获取路径：先查 artifact 列表，再用用户态 content 代理接口下载完整内容；明确 `azblob://` / `runtime://` 存储规则、Blob Secret 配置和排障提示 |
|
||||
| v2.1.9 | 2026-05-29 | Runtime artifact store 支持从 K8s Secret 读取 Azure Blob 凭据并上传完整产物，上传成功返回 `azblob://...` URI；内容读取接口支持 Runtime-local 与 AzBlob 两种来源 |
|
||||
| v2.1.8 | 2026-05-29 | 新增 Runtime-local artifact store：完整 agent 产物落盘保存，`artifact.created` 只回传摘要、URI、大小和 `content_hash`；新增 `/api/swarms/{id}/artifacts/{artifact_id}/content` 与用户态 artifact content 读取接口 |
|
||||
@@ -1771,6 +1873,6 @@ except requests.exceptions.HTTPError as e:
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: v2.1.10
|
||||
**最后更新**: 2026-05-30
|
||||
**文档版本**: v2.1.11
|
||||
**最后更新**: 2026-06-04
|
||||
**维护者**: Agent Manager Team
|
||||
|
||||
Reference in New Issue
Block a user