1777 lines
61 KiB
Markdown
1777 lines
61 KiB
Markdown
# Heicode Agent Manager API 对接文档
|
||
|
||
## 📋 目录
|
||
|
||
- [1. 概述](#1-概述)
|
||
- [2. 认证方式](#2-认证方式)
|
||
- [3. API 端点](#3-api-端点)
|
||
- [4. 数据模型](#4-数据模型)
|
||
- [5. 使用示例](#5-使用示例)
|
||
- [6. 错误处理](#6-错误处理)
|
||
- [7. 最佳实践](#7-最佳实践)
|
||
- [8. 附录](#8-附录)
|
||
|
||
---
|
||
|
||
## 1. 概述
|
||
|
||
### 1.1 服务信息
|
||
|
||
- **服务名称**: Agent Manager - Heicode Integration API
|
||
- **版本**: v2.1.9 (heicode-v2)
|
||
- **当前部署镜像**: `agnettaiji.azurecr.io/ai-agents/agent-manager:heicode-v2-20260529232620`
|
||
- **当前 AKS 镜像 digest**: `sha256:b1931c1172fc23da8234e96dbdca34c4704644c2b2099391b362a48c47dc68f4`
|
||
- **Base URL（当前联调）**: `http://20.212.121.126`
|
||
- **Base URL（域名待切换）**: `https://agent-manager.taijiagnet.com`
|
||
- **主 API 前缀**: `/api/agnet`
|
||
- **Runtime 兼容前缀**: `/api/swarms`
|
||
|
||
### 1.2 核心功能
|
||
|
||
- ✅ 多 Agent 编排部署
|
||
- ✅ Heicode sub 模式敏捷开发对接（agile / waterfall）
|
||
- ✅ `/api/swarms` Runtime 适配入口
|
||
- ✅ 预算控制和计费管理
|
||
- ✅ 风险等级评估（low/medium/high）
|
||
- ✅ Azure Key Vault `secret_ref` 引用
|
||
- ✅ 实时日志和事件追踪
|
||
- ✅ Callback / artifact / timeline / SK snapshot 对接
|
||
- ✅ 资源监控和指标统计
|
||
- ✅ 幂等性保证
|
||
|
||
### 1.3 架构说明
|
||
|
||
```
|
||
┌─────────────┐
|
||
│ Heicode │
|
||
│ Platform │
|
||
└──────┬──────┘
|
||
│ HTTPS + Token Auth
|
||
▼
|
||
┌─────────────────────────────┐
|
||
│ Agent Manager API │
|
||
│ /api/agnet/* │
|
||
└──────┬──────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────┐
|
||
│ Kubernetes Cluster (AKS) │
|
||
│ - Namespace 隔离 │
|
||
│ - Pod 管理 │
|
||
│ - ConfigMap/Secret │
|
||
└─────────────────────────────┘
|
||
```
|
||
|
||
### 1.4 Heicode sub 模式对接边界
|
||
|
||
本文件同时补充 Heicode Manager 当前 sub 模式敏捷开发所需的 Runtime 对接契约。
|
||
|
||
| 系统 | 职责 | 说明 |
|
||
|------|------|------|
|
||
| Heicode Manager | 用户、资源绑定、模型网关配置、审批、部署草稿、权限清单、回调持久化、artifact/timeline 展示 | 已有本地控制面和生产页面 |
|
||
| Agent Manager / Agnet Runtime | 接收 Manager 传入的部署计划，真实创建/调度子 Agent，执行任务，按回调协议回写状态、产物、用量和审批请求 | 需要支持本文定义的请求与回调字段 |
|
||
| Azure Key Vault | 长期密钥托管 | Manager/Runtime 只能使用 `azkv://...` 引用，不能传明文密钥 |
|
||
| NewAPI / CodeGW | 模型网关与计费入口 | Runtime 使用 Manager 提供的模型、预算和 `secret_ref` 上下文 |
|
||
|
||
重要边界：
|
||
|
||
1. `sub_mode` 是 Heicode 的任务组织方式，不等于 Agent Manager 内部固定执行引擎。
|
||
2. `agile` 和 `waterfall` 都属于 sub 模式；当前优先验证 `agile`。
|
||
3. 蜂群模式和 sub 模式不是同一个概念。`/api/swarms` 是为了对齐 Runtime 创建入口的适配层，不代表 Manager 把所有 sub 流程改成蜂群模式。
|
||
4. 所有凭据只能通过 `secret_ref` 传递，禁止在请求、回调、日志、artifact metadata 中出现明文密码、Token、私钥、连接串。
|
||
|
||
### 1.5 当前 Manager / Runtime v2.1 落地状态
|
||
|
||
截至 `heicode-v2-20260529232620`，Manager / Runtime 已按本文 v2.1 契约落地以下兼容能力：
|
||
|
||
| 能力 | 当前状态 | 说明 |
|
||
|------|----------|------|
|
||
| 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 事件 |
|
||
| 普通 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` 事件 |
|
||
| deployment/agent 状态一致性 | 已支持 | deployment 进入终态时，`agents[].status` 会同步收敛到终态 |
|
||
| 普通 sub agent 字段兼容 | 已支持 | `agents[].role_template` / `default_model_id` 会规范化为 Runtime `role` / `model` |
|
||
| `payload.*` 格式 | 已支持 | `artifact.created` 等事件按 `payload` 解析；旧顶层 `artifact` 也兼容 |
|
||
| `swarm_id` / `occurred_at` / `agent_instance_id` | 已支持 | 事件持久化时保留，并用于时间线与 Agent 实例展示 |
|
||
| `agile_context` 透传 | 已支持 | 写入 Runtime 配置上下文，保留 stage/checkpoint/验收标准 |
|
||
| `callback.signing_secret_ref` | 已支持 | 创建部署时保存；Runtime 发送 callback 时用它解析 HMAC secret |
|
||
| 默认 `subscribed_events` | 已支持 | 未传时自动订阅 v2.1 标准事件集 |
|
||
| 顶层 `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 |
|
||
| `/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，不重复创建 |
|
||
| 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` 中可见 |
|
||
|
||
仍属于后续增强或 Runtime 侧职责：
|
||
|
||
1. `/logs`、`/events`、`/metrics` 当前提供 Runtime/Swarm 本地聚合与轮询兜底；其中 `/logs` 已不再返回固定占位文本，后续仍可接入真实 Pod 指标和日志后端。
|
||
2. Runtime callback 重试、死信队列和人工重放；当前发送失败只记录 warning，不阻塞任务执行。
|
||
3. credential lease 的真实凭证兑换由 Manager / Vault 链路负责，Runtime 只消费 `credential_ref`。
|
||
4. artifact 独立表字段化存储；当前查询结果由 callback event payload 投影生成。
|
||
|
||
### 1.6 v2.1.4 联调速查
|
||
|
||
本节给联调同学快速定位当前可用路径；详细字段定义见后续 API 端点和数据模型章节。
|
||
|
||
| 场景 | 推荐接口 | 当前状态 |
|
||
|------|----------|----------|
|
||
| 健康检查 | `GET /api/agnet/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 过渡认证和幂等 |
|
||
| 查询 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` | 已支持投影查询，独立解析接口待增强 |
|
||
| 审批 decision | `POST /api/swarms/{swarm_id}/approvals/{approval_id}` | 已支持 `approved` / `rejected` |
|
||
|
||
当前实现边界：
|
||
|
||
1. `/api/swarms` 的 `dry_run:true` 会返回 422，不创建真实 run。
|
||
2. Runtime callback 发送失败当前只记录 warning，不阻塞执行；重试队列、死信队列和 replay 属于后续增强。
|
||
3. `/api/swarms/{id}/logs`、`events`、`metrics` 是本地聚合兜底，不等同于完整日志/指标后端。
|
||
4. 所有 secret 都必须以引用形式传递，正式示例统一使用 `azkv://<vault>/secrets/<name>`。
|
||
|
||
### 1.7 产物获取速查
|
||
|
||
普通 sub Runtime 完成后，Manager 前端或服务端不要从 callback body 里直接读取完整产物。标准流程是：先查询 artifact 列表拿到 `artifact_id`、`uri`、摘要和大小，再通过 content 代理接口下载完整内容。
|
||
|
||
推荐调用顺序：
|
||
|
||
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` 下载完整内容。
|
||
5. 如果 Manager 需要直接访问 Runtime 兼容层，也可以调用 `GET /api/swarms/{swarm_id}/artifacts/{artifact_id}/content`。
|
||
|
||
示例：
|
||
|
||
```bash
|
||
BASE_URL="https://agent-manager.taijiagnet.com"
|
||
TOKEN="<HEICODE_SERVICE_TOKEN>"
|
||
DEPLOYMENT_ID="swm_xxx"
|
||
|
||
curl -sS \
|
||
-H "Authorization: Bearer ${TOKEN}" \
|
||
"${BASE_URL}/api/agnet/user/deployments/${DEPLOYMENT_ID}/artifacts"
|
||
```
|
||
|
||
列表响应中的关键字段：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"deployment_id": "swm_xxx",
|
||
"artifacts": [
|
||
{
|
||
"artifact_id": "art_backend_patch_001",
|
||
"artifact_type": "code_patch",
|
||
"title": "Backend API patch",
|
||
"summary": "新增 deployment draft 到 Runtime 的桥接逻辑",
|
||
"uri": "azblob://heicode-artifacts/runtime-artifacts/swm_xxx/art_backend_patch_001.patch",
|
||
"mime_type": "text/x-diff",
|
||
"size_bytes": 18420,
|
||
"metadata": {
|
||
"content_hash": "sha256:abc123...",
|
||
"download_path": "/api/swarms/swm_xxx/artifacts/art_backend_patch_001/content"
|
||
},
|
||
"created_at": "2026-05-27T10:40:00Z"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
下载完整内容：
|
||
|
||
```bash
|
||
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"
|
||
```
|
||
|
||
生产环境产物存储规则：
|
||
|
||
- `RUNTIME_ARTIFACT_BACKEND=azblob` 时，Runtime 优先把完整产物上传到 Azure Blob，并在 artifact 列表中返回 `azblob://<container>/<blob-name>`。
|
||
- 如果 Azure Blob 上传失败，Runtime 会回落到本地 artifact store，并返回 `runtime://<swarm_id>/artifacts/<artifact_id>`。
|
||
- 无论 `uri` 是 `azblob://` 还是 `runtime://`，Manager / 前端都优先使用 content 代理接口读取；不要把 Blob 凭据、SAS URL 或明文连接串暴露给用户端。
|
||
- callback 的 `payload.summary` 只用于展示摘要；完整内容以 content 接口返回的文件为准。
|
||
|
||
生产环境 Blob 配置要求：
|
||
|
||
| 环境变量 | 说明 | 默认值 |
|
||
|----------|------|--------|
|
||
| `RUNTIME_ARTIFACT_BACKEND` | artifact 后端，生产建议使用 `azblob` | `azblob` |
|
||
| `RUNTIME_ARTIFACT_BLOB_SECRET_NAME` | 保存 Blob 凭据的 K8s Secret 名称 | `agent-manager-secret` |
|
||
| `RUNTIME_ARTIFACT_BLOB_SECRET_NAMESPACE` | Secret namespace；为空时使用 `NAMESPACE` 或 `agent-manager` | 空 |
|
||
| `RUNTIME_ARTIFACT_BLOB_CONTAINER` | 默认容器名 | `heicode-artifacts` |
|
||
| `RUNTIME_ARTIFACT_BLOB_PREFIX` | Blob 路径前缀 | `runtime-artifacts` |
|
||
|
||
K8s Secret 支持两种凭据格式：
|
||
|
||
- `AZURE_STORAGE_CONNECTION_STRING`
|
||
- 或 `AZURE_STORAGE_ACCOUNT` + `AZURE_STORAGE_KEY`
|
||
|
||
可选覆盖项：
|
||
|
||
- `AZURE_BLOB_CONTAINER`：覆盖默认容器名。
|
||
|
||
排障提示：
|
||
|
||
- artifact 列表为空：先确认 run 已进入 terminal 状态，或 callback 订阅包含 `artifact.created`。
|
||
- 列表有记录但 content 返回 404：检查 `uri` 是否为 `runtime://` / `azblob://`，以及 Runtime 本地文件或 Blob Secret 是否仍可访问。
|
||
- 下载内容与摘要不一致：以 content 接口返回的完整文件为准，并用 `metadata.content_hash` 做完整性校验。
|
||
|
||
---
|
||
|
||
## 2. 认证方式
|
||
|
||
### 2.1 Service Token 认证
|
||
|
||
除健康检查外，所有 API 请求必须在 HTTP Header 中携带服务令牌：
|
||
|
||
```http
|
||
Authorization: Bearer <HEICODE_SERVICE_TOKEN>
|
||
```
|
||
|
||
### 2.2 必需的 HTTP Headers
|
||
|
||
| Header | 必需 | 说明 | 示例 |
|
||
|--------|------|------|------|
|
||
| `Authorization` | ✅ | 服务令牌 | `Bearer sk_xxx` |
|
||
| `X-User-ID` | ✅ | 用户标识 | `user_12345` |
|
||
| `X-Binding-Scope` | ✅ | 绑定范围 | `workspace_abc` |
|
||
| `X-Correlation-ID` | ✅ | 请求追踪 ID | `req_xyz789` |
|
||
| `X-Idempotency-Key` | ⚪ | 幂等性键（推荐） | `idem_abc123` |
|
||
| `Content-Type` | ✅ | 内容类型 | `application/json` |
|
||
|
||
> `GET /api/agnet/health` 用于 K8s / LB 探活，不要求 `Authorization` 或业务追踪 Header。
|
||
|
||
### 2.3 获取 Service Token
|
||
|
||
请联系系统管理员获取 `HEICODE_SERVICE_TOKEN`。
|
||
|
||
---
|
||
|
||
## 3. API 端点
|
||
|
||
### 3.1 健康检查
|
||
|
||
#### `GET /api/agnet/health`
|
||
|
||
检查服务状态。
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/health"
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"status": "healthy",
|
||
"service": "agent-manager-agnet",
|
||
"version": "1.0.0",
|
||
"phase": "2-deployments"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.2 创建部署
|
||
|
||
#### `POST /api/agnet/deployments`
|
||
|
||
创建一个新的 Agent 部署。
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"orchestration_plan": "multi-agent-workflow",
|
||
"risk_level": "medium",
|
||
"approval_token": "optional_for_high_risk",
|
||
"budget": {
|
||
"max_usd": 100.0,
|
||
"alert_threshold_pct": 80
|
||
},
|
||
"billing_context": {
|
||
"provider": "newapi",
|
||
"default_model_id": "gpt-4",
|
||
"allowed_model_ids": ["gpt-4", "gpt-3.5-turbo"],
|
||
"secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/model-gateway-key"
|
||
},
|
||
"agents": [
|
||
{
|
||
"role": "researcher",
|
||
"image": "agnettaiji.azurecr.io/ai-agents/search-agent:v1.2.0"
|
||
},
|
||
{
|
||
"role": "writer",
|
||
"image": "agnettaiji.azurecr.io/ai-agents/doc-creator:v1.2.0"
|
||
}
|
||
],
|
||
"resource_grants": [
|
||
{
|
||
"type": "database",
|
||
"ref": "azkv://heicode-kv.vault.azure.net/secrets/db-credentials",
|
||
"permissions": ["read"]
|
||
}
|
||
],
|
||
"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": [
|
||
"phase.changed",
|
||
"sk_tool.called",
|
||
"sk_tool.completed",
|
||
"sk_tool.failed",
|
||
"approval.requested",
|
||
"budget.alert",
|
||
"deployment.status_changed",
|
||
"agent.crashed"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"deployment_id": "dep_a1b2c3d4e5f6",
|
||
"swarm_id": "dep_a1b2c3d4e5f6",
|
||
"status": "pending",
|
||
"agent_instances": [
|
||
{
|
||
"agent_instance_id": "agi_123abc",
|
||
"role": "researcher",
|
||
"status": "pending",
|
||
"phase": null
|
||
},
|
||
{
|
||
"agent_instance_id": "agi_456def",
|
||
"role": "writer",
|
||
"status": "pending",
|
||
"phase": null
|
||
}
|
||
],
|
||
"created_at": "2026-05-27T10:30:00Z",
|
||
"estimated_ready_at": "2026-05-27T10:32:00Z",
|
||
"data": {
|
||
"deployment_id": "dep_a1b2c3d4e5f6",
|
||
"swarm_id": "dep_a1b2c3d4e5f6",
|
||
"status": "pending",
|
||
"estimated_ready_at": "2026-05-27T10:32:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
普通 sub 敏捷兼容：
|
||
|
||
- `orchestration_plan` 可传字符串，也可传 Heicode sub 结构化对象。
|
||
- `budget.max_usd` 和 `budget.max_cost_usd` 双向兼容；缺失预算会被拒绝。
|
||
- `orchestration_plan.agents[].role_template` 会规范化为 Runtime `role`。
|
||
- `orchestration_plan.agents[].target_role` 也可作为 `role` 兼容来源。
|
||
- `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://`。
|
||
|
||
---
|
||
|
||
### 3.3 列出部署
|
||
|
||
#### `GET /api/agnet/deployments`
|
||
|
||
获取部署列表，支持过滤和分页。
|
||
|
||
**查询参数**:
|
||
| 参数 | 类型 | 必需 | 说明 |
|
||
|------|------|------|------|
|
||
| `user_id` | string | ⚪ | 按用户过滤 |
|
||
| `binding_scope` | string | ⚪ | 按绑定范围过滤 |
|
||
| `status` | string | ⚪ | 按状态过滤 (pending/running/stopped/failed) |
|
||
| `limit` | integer | ⚪ | 每页数量 (默认 50, 最大 200) |
|
||
| `cursor` | string | ⚪ | 分页游标 |
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/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" \
|
||
-H "X-Correlation-ID: req_list_001"
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"deployments": [
|
||
{
|
||
"deployment_id": "dep_a1b2c3d4e5f6",
|
||
"status": "running",
|
||
"risk_level": "medium",
|
||
"budget": {
|
||
"max_usd": 100.0,
|
||
"consumed_usd": 23.5,
|
||
"remaining_usd": 76.5
|
||
},
|
||
"created_at": "2026-05-12T10:30:00Z",
|
||
"agent_instances_count": 2
|
||
}
|
||
],
|
||
"pagination": {
|
||
"next_cursor": null,
|
||
"has_more": false
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.4 获取部署详情
|
||
|
||
#### `GET /api/agnet/deployments/{deployment_id}`
|
||
|
||
获取指定部署的详细信息。
|
||
|
||
**路径参数**:
|
||
- `deployment_id`: 部署 ID
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2c3d4e5f6" \
|
||
-H "Authorization: Bearer sk_xxx" \
|
||
-H "X-User-ID: user_123" \
|
||
-H "X-Binding-Scope: workspace_abc" \
|
||
-H "X-Correlation-ID: req_get_001"
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"deployment_id": "dep_a1b2c3d4e5f6",
|
||
"user_id": "user_123",
|
||
"binding_scope": "workspace_abc",
|
||
"status": "running",
|
||
"phase": "executing",
|
||
"orchestration_plan": "multi-agent-workflow",
|
||
"risk_level": "medium",
|
||
"budget": {
|
||
"max_usd": 100.0,
|
||
"consumed_usd": 23.5,
|
||
"remaining_usd": 76.5
|
||
},
|
||
"billing_context": {
|
||
"provider": "newapi",
|
||
"default_model_id": "gpt-4",
|
||
"allowed_model_ids": ["gpt-4", "gpt-3.5-turbo"]
|
||
},
|
||
"agent_instances": [
|
||
{
|
||
"agent_instance_id": "agi_123abc",
|
||
"role": "researcher",
|
||
"status": "running",
|
||
"phase": "searching"
|
||
},
|
||
{
|
||
"agent_instance_id": "agi_456def",
|
||
"role": "writer",
|
||
"status": "running",
|
||
"phase": "writing"
|
||
}
|
||
],
|
||
"resource_grants": [
|
||
{
|
||
"type": "database",
|
||
"ref": "azkv://heicode-kv.vault.azure.net/secrets/db-credentials"
|
||
}
|
||
],
|
||
"created_at": "2026-05-12T10:30:00Z",
|
||
"updated_at": "2026-05-12T10:35:00Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.5 停止部署
|
||
|
||
#### `POST /api/agnet/deployments/{deployment_id}/stop`
|
||
|
||
停止一个正在运行的部署。
|
||
|
||
**路径参数**:
|
||
- `deployment_id`: 部署 ID
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"reason": "User requested stop",
|
||
"approval_token": "optional_for_high_risk"
|
||
}
|
||
```
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl -X POST "https://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2c3d4e5f6/stop" \
|
||
-H "Authorization: Bearer sk_xxx" \
|
||
-H "X-User-ID: user_123" \
|
||
-H "X-Binding-Scope: workspace_abc" \
|
||
-H "X-Correlation-ID: req_stop_001" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"reason": "Task completed"
|
||
}'
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"deployment_id": "dep_a1b2c3d4e5f6",
|
||
"status": "stopped",
|
||
"stopped_at": "2026-05-12T11:00:00Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.6 获取部署日志
|
||
|
||
#### `GET /api/agnet/deployments/{deployment_id}/logs`
|
||
|
||
获取部署的实时日志。
|
||
|
||
**路径参数**:
|
||
- `deployment_id`: 部署 ID
|
||
|
||
**查询参数**:
|
||
| 参数 | 类型 | 必需 | 说明 |
|
||
|------|------|------|------|
|
||
| `agent_instance_id` | string | ⚪ | 按 Agent 实例过滤 |
|
||
| `since` | datetime | ⚪ | 起始时间 (ISO 8601) |
|
||
| `limit` | integer | ⚪ | 日志条数 (默认 100) |
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2c3d4e5f6/logs?limit=50" \
|
||
-H "Authorization: Bearer sk_xxx" \
|
||
-H "X-User-ID: user_123" \
|
||
-H "X-Binding-Scope: workspace_abc" \
|
||
-H "X-Correlation-ID: req_logs_001"
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"deployment_id": "dep_a1b2c3d4e5f6",
|
||
"logs": [
|
||
{
|
||
"timestamp": "2026-05-12T10:31:00Z",
|
||
"agent_instance_id": "agi_123abc",
|
||
"level": "info",
|
||
"message": "Starting search task...",
|
||
"source": "stdout"
|
||
},
|
||
{
|
||
"timestamp": "2026-05-12T10:31:05Z",
|
||
"agent_instance_id": "agi_123abc",
|
||
"level": "info",
|
||
"message": "Found 10 relevant documents",
|
||
"source": "stdout"
|
||
}
|
||
],
|
||
"pagination": {
|
||
"has_more": false
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.7 获取部署事件
|
||
|
||
#### `GET /api/agnet/deployments/{deployment_id}/events`
|
||
|
||
获取部署的事件历史。
|
||
|
||
**路径参数**:
|
||
- `deployment_id`: 部署 ID
|
||
|
||
**查询参数**:
|
||
| 参数 | 类型 | 必需 | 说明 |
|
||
|------|------|------|------|
|
||
| `event_type` | string | ⚪ | 事件类型过滤 |
|
||
| `since` | datetime | ⚪ | 起始时间 (ISO 8601) |
|
||
| `limit` | integer | ⚪ | 事件条数 (默认 100) |
|
||
|
||
**事件类型**:
|
||
- `deployment.accepted` - 部署已接受
|
||
- `deployment.started` - 部署已启动
|
||
- `deployment.stopped` - 部署已停止
|
||
- `deployment.failed` - 部署失败
|
||
- `agent.started` - Agent 启动
|
||
- `agent.completed` - Agent 完成
|
||
- `budget.alert` - 预算告警
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2c3d4e5f6/events" \
|
||
-H "Authorization: Bearer sk_xxx" \
|
||
-H "X-User-ID: user_123" \
|
||
-H "X-Binding-Scope: workspace_abc" \
|
||
-H "X-Correlation-ID: req_events_001"
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"deployment_id": "dep_a1b2c3d4e5f6",
|
||
"events": [
|
||
{
|
||
"event_id": "evt_abc123",
|
||
"event_type": "deployment.accepted",
|
||
"agent_instance_id": null,
|
||
"occurred_at": "2026-05-12T10:30:00Z",
|
||
"payload": {
|
||
"risk_level": "medium"
|
||
}
|
||
},
|
||
{
|
||
"event_id": "evt_def456",
|
||
"event_type": "agent.started",
|
||
"agent_instance_id": "agi_123abc",
|
||
"occurred_at": "2026-05-12T10:31:00Z",
|
||
"payload": {
|
||
"role": "researcher"
|
||
}
|
||
}
|
||
],
|
||
"pagination": {
|
||
"has_more": false
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.8 获取资源指标
|
||
|
||
#### `GET /api/agnet/deployments/{deployment_id}/metrics`
|
||
|
||
获取部署的资源使用指标。
|
||
|
||
**路径参数**:
|
||
- `deployment_id`: 部署 ID
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl -X GET "https://agent-manager.taijiagnet.com/api/agnet/deployments/dep_a1b2c3d4e5f6/metrics" \
|
||
-H "Authorization: Bearer sk_xxx" \
|
||
-H "X-User-ID: user_123" \
|
||
-H "X-Binding-Scope: workspace_abc" \
|
||
-H "X-Correlation-ID: req_metrics_001"
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"deployment_id": "dep_a1b2c3d4e5f6",
|
||
"timestamp": "2026-05-12T10:35:00Z",
|
||
"agent_metrics": [
|
||
{
|
||
"agent_instance_id": "agi_123abc",
|
||
"role": "researcher",
|
||
"status": "running",
|
||
"resources": {
|
||
"cpu_usage_cores": 0.25,
|
||
"memory_usage_mb": 256.0,
|
||
"network_rx_bytes": 1048576,
|
||
"network_tx_bytes": 524288
|
||
},
|
||
"uptime_seconds": 300
|
||
},
|
||
{
|
||
"agent_instance_id": "agi_456def",
|
||
"role": "writer",
|
||
"status": "running",
|
||
"resources": {
|
||
"cpu_usage_cores": 0.15,
|
||
"memory_usage_mb": 128.0,
|
||
"network_rx_bytes": 524288,
|
||
"network_tx_bytes": 262144
|
||
},
|
||
"uptime_seconds": 300
|
||
}
|
||
],
|
||
"total_resources": {
|
||
"cpu_usage_cores": 0.40,
|
||
"memory_usage_mb": 384.0,
|
||
"network_rx_bytes": 1572864,
|
||
"network_tx_bytes": 786432
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.9 Runtime Callback 回写
|
||
|
||
#### `POST /api/agnet/callbacks/swarm-events`
|
||
|
||
Agent Manager / Runtime 使用该接口向 Heicode Manager 回写 sub 模式事件、阶段变化、产物、预算告警、审批请求和 SK 工具调用结果。该接口是反向通知协议，不能仅依赖 `/events` 轮询替代。
|
||
|
||
#### `GET /api/agnet/callbacks/swarm-events/schema`
|
||
|
||
联调前可读取 callback schema。该接口只返回事件类型、分类、必填字段、阶段枚举和 artifact 类型，不返回 token、secret 或任何明文密钥。
|
||
|
||
响应字段：
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `event_types` | 支持的 `deployment.status_changed`、`phase.changed`、`timeline.updated`、`artifact.created`、`approval.requested`、`sk_tool.*`、`budget.alert` 等事件 |
|
||
| `body_required_fields` | callback envelope 必填字段 |
|
||
| `headers` | HMAC、幂等、追踪相关 Header 约定 |
|
||
| `stages` | 普通 sub 敏捷阶段：`planning/design/development/testing/fixing/deployment/review/done/failed` |
|
||
| `artifact_types` | `code_patch/document/test_report/deployment_manifest/log_bundle/other` |
|
||
|
||
**请求 Header**:
|
||
|
||
| Header | 必需 | 说明 |
|
||
|--------|------|------|
|
||
| `X-Agnet-Event-Id` | 是 | 全局唯一事件 ID，用于幂等去重 |
|
||
| `X-Agnet-Signature` | 是 | HMAC-SHA256 签名，格式为 `sha256=<hex>` |
|
||
| `X-Agnet-Timestamp` | 是 | Unix 毫秒时间戳，接收方应校验时间窗口 |
|
||
| `X-Correlation-ID` | 推荐 | 全链路追踪 ID；缺失时 Manager 会使用 body `correlation_id` 或 deployment 记录兜底 |
|
||
| `Content-Type` | 是 | `application/json` |
|
||
|
||
过渡兼容：当前 Manager v2.1 仍接受旧版 `X-Agnet-Service-Token` 或 `Authorization: Bearer <HEICODE_SERVICE_TOKEN>` callback 认证。Agent Manager / Runtime 新实现必须优先使用 HMAC。
|
||
|
||
**签名规范**:
|
||
|
||
```text
|
||
signature_payload = timestamp + "." + event_id + "." + raw_body
|
||
signature = HMAC_SHA256(callback_signing_secret, signature_payload)
|
||
```
|
||
|
||
其中 `timestamp` 取 `X-Agnet-Timestamp`，`event_id` 取 `X-Agnet-Event-Id`，`raw_body` 必须使用 HTTP 请求原始 body 字节，不应在验签前重新格式化 JSON。
|
||
|
||
`callback_signing_secret` 不在请求中明文传输。创建部署或 `/api/swarms` 时通过 `callback.signing_secret_ref` 指向 Azure Key Vault。Manager 当前按 5 分钟时间窗校验 `X-Agnet-Timestamp`，超出窗口返回 `401 UNAUTHORIZED`。
|
||
|
||
Runtime 发送端签名密钥解析顺序：
|
||
|
||
1. 优先读取与 `signing_secret_ref` secret name 对应的环境变量。例如 `azkv://.../secrets/agnet-callback-signing-key` 会先查 `AGNET_CALLBACK_SIGNING_KEY`。
|
||
2. 其次读取通用环境变量：`HEICODE_CALLBACK_SIGNING_SECRET`、`CALLBACK_SIGNING_SECRET`。
|
||
3. 如果是 `azkv://` 引用且配置了 `AZURE_TENANT_ID`、`AZURE_CLIENT_ID`、`AZURE_CLIENT_SECRET`，Runtime 会使用 client credentials 从 Azure Key Vault 拉取 secret value。
|
||
4. 如果仍无法解析，Runtime 会使用 `HEICODE_SERVICE_TOKEN` 作为过渡期 fallback，并记录 warning。生产环境应配置明确的 callback signing secret。
|
||
|
||
**事件 Envelope**:
|
||
|
||
```json
|
||
{
|
||
"event_id": "evt_01HX...",
|
||
"event_type": "phase.changed",
|
||
"deployment_id": "dep_a1b2c3d4",
|
||
"swarm_id": "dep_a1b2c3d4",
|
||
"agent_instance_id": "agi_backend_001",
|
||
"occurred_at": "2026-05-27T10:40:00Z",
|
||
"correlation_id": "req_xxx",
|
||
"payload": {}
|
||
}
|
||
```
|
||
|
||
字段兼容：
|
||
|
||
- `event_id` 优先取 Header `X-Agnet-Event-Id`，body `event_id` 作为兼容字段。
|
||
- `deployment_id` 为主关联键；如果 Runtime 只传 `swarm_id`，Manager 当前会兼容用 `swarm_id` 查 deployment。
|
||
- `payload` 是标准业务载荷；旧版顶层 `artifact` 会被兼容合并到 `payload`。
|
||
- `occurred_at` 使用 Runtime 真实发生时间；解析失败时 Manager 使用接收时间兜底。
|
||
|
||
**标准事件类型**:
|
||
|
||
| 事件类型 | 说明 |
|
||
|----------|------|
|
||
| `deployment.status_changed` | 部署整体状态变化 |
|
||
| `phase.changed` | 7 阶段进度变化 |
|
||
| `agent.started` | Agent 启动 |
|
||
| `agent.completed` | Agent 完成 |
|
||
| `agent.crashed` | Agent 异常退出或 Pod OOMKilled |
|
||
| `task.completed` | 普通 sub 子任务完成 |
|
||
| `task.failed` | 普通 sub 子任务失败 |
|
||
| `task.blocked` | 普通 sub 子任务被阻塞 |
|
||
| `sk_tool.called` | SK 工具开始调用，参数必须脱敏 |
|
||
| `sk_tool.completed` | SK 工具调用成功，包含耗时、摘要和产物引用 |
|
||
| `sk_tool.failed` | SK 工具调用失败，包含脱敏错误原因 |
|
||
| `approval.requested` | 高危操作等待 Heicode / 桌面客户端审批 |
|
||
| `budget.alert` | 预算告警 |
|
||
| `artifact.created` | 产物已生成 |
|
||
| `timeline.updated` | Runtime 时间线事件 |
|
||
|
||
默认订阅事件：创建部署时如果 `callback.subscribed_events` 为空，Manager 默认订阅上表中的 v2.1 标准事件集。
|
||
|
||
当前 Runtime 主动发送节点：
|
||
|
||
| 触发时机 | 事件 |
|
||
|----------|------|
|
||
| `/api/agnet/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` |
|
||
| Agent 任务完成 | `agent.completed` |
|
||
| 普通 sub 子任务结束 | `task.completed`、`task.failed`、`task.blocked` |
|
||
| Agent 任务派发 | `sk_tool.called` |
|
||
| Agent 任务成功 | `sk_tool.completed` |
|
||
| Agent 任务失败 | `sk_tool.failed` |
|
||
| Swarm/普通 sub 产物生成 | `artifact.created` |
|
||
| `agile_context.requires_user_approval=true` 或高风险任务 | `approval.requested` |
|
||
| 设置成本预算 | `budget.alert` |
|
||
|
||
发送失败策略：当前 Runtime callback 发送失败只记录 warning，不阻塞 Agent 执行。指数退避、死信队列和人工重放属于后续增强项。
|
||
|
||
**7 阶段枚举**:
|
||
|
||
| 阶段 | 说明 |
|
||
|------|------|
|
||
| `requirements` | 需求 |
|
||
| `design` | 设计 |
|
||
| `backend` | 后端 |
|
||
| `frontend` | 前端 |
|
||
| `review` | 检查 |
|
||
| `test` | 测试 |
|
||
| `deploy` | 部署 |
|
||
|
||
**重试与幂等**:
|
||
|
||
1. Heicode Manager 按 `X-Agnet-Event-Id` 或 body `event_id` 去重；重复事件必须返回 2xx。
|
||
2. 重复事件仍需先通过认证校验；通过后返回 `deduplicated: true`。
|
||
3. 当前 Agent Manager Runtime 推送失败只记录 warning，不阻塞 Agent 执行。
|
||
4. 指数退避、死信队列和人工重放是后续增强目标；建议目标延迟为 1s、5s、30s、2m、10m，最多重试 12 小时。
|
||
5. 同一 `deployment_id` 内事件按 `occurred_at` 尽力有序；跨 deployment 不保证顺序。
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"event_id": "evt_01HX...",
|
||
"deduplicated": false
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.10 Heicode Manager 用户态接口边界
|
||
|
||
以下接口由 Heicode Manager 提供或作为 Manager 前端边界使用。Agent Manager 文档需要明确这些接口不全由 Runtime 实现；Runtime 主要调用 callback 接口、消费部署计划，并可实现 `/api/swarms` 兼容入口。
|
||
|
||
| 方法 | 路径 | 调用方 | 用途 |
|
||
|------|------|--------|------|
|
||
| `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/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 前端 | 查询合并时间线 |
|
||
|
||
说明：
|
||
|
||
1. `POST /api/swarms` 当前返回 `deployment_id` 和 `swarm_id`；当前二者同值，均可用于 Runtime 查询和停止。
|
||
2. 后续如果 Runtime 返回自己的真实 `swarm_id`，Manager 需要保存 `deployment_id <-> swarm_id` 映射。
|
||
3. Runtime 侧不能只支持 `/api/agnet/deployments`，否则无法覆盖 Heicode 用户态任务流。
|
||
|
||
#### `POST /api/swarms`
|
||
|
||
Heicode sub 模式兼容入口。该接口接受结构化 `orchestration_plan`，用于 agile / waterfall 任务流创建 Runtime run。
|
||
|
||
当前联调约束：
|
||
|
||
- 缺少 `orchestration_plan`、`callback.url`、`orchestration_plan.sub_mode`、`orchestration_plan.user_context.user_id` 时返回 422。
|
||
- `dry_run:true` 当前返回 422，且不会创建真实 swarm；后续如果支持 dry-run，需要返回校验结果但不落库、不启动 Runtime。
|
||
- 同一个 `X-Idempotency-Key` 重复请求返回同一个 run。
|
||
- `sub_mode=agile` 默认使用 hybrid orchestration；`sub_mode=waterfall` 使用 sequential orchestration。
|
||
- `budget.max_duration_sec` 会换算为 Runtime timeout minutes，默认兜底为 1800 秒。
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"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": "123",
|
||
"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-27~2026-05-28",
|
||
"stage": "development",
|
||
"checkpoint": "ready_for_test",
|
||
"acceptance_criteria": [
|
||
"接口返回成功",
|
||
"Manager 前端可点击验证",
|
||
"artifact 可回写到 timeline",
|
||
"不出现明文密钥"
|
||
],
|
||
"next_action": "submit_test_result",
|
||
"requires_user_approval": false
|
||
},
|
||
"agents": [],
|
||
"resource_grants": []
|
||
},
|
||
"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"
|
||
}
|
||
}
|
||
```
|
||
|
||
**最小有效请求示例**：
|
||
|
||
```json
|
||
{
|
||
"orchestration_plan": {
|
||
"intent_id": "task_123",
|
||
"objective": "完成本轮任务目标",
|
||
"sub_mode": "agile",
|
||
"user_context": {
|
||
"user_id": "123",
|
||
"binding_scope": "task-task-123"
|
||
},
|
||
"budget": {
|
||
"max_cost_usd": 8
|
||
},
|
||
"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"
|
||
}
|
||
},
|
||
"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"
|
||
}
|
||
}
|
||
```
|
||
|
||
**校验失败示例**：
|
||
|
||
```json
|
||
{
|
||
"detail": "callback.url is required"
|
||
}
|
||
```
|
||
|
||
**dry-run 拒绝示例**：
|
||
|
||
```json
|
||
{
|
||
"detail": "dry_run is not supported by Runtime create; no swarm was created"
|
||
}
|
||
```
|
||
|
||
#### `/api/swarms` 运行期兼容接口
|
||
|
||
普通 sub 敏捷模式不要求完整蜂群 task graph，但 Runtime 需要提供 Manager 可调用的停止、审批和排障接口。当前 Agent Manager 在 `/api/swarms` 下支持以下兼容路径：
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| `GET` | `/api/swarms/{swarm_id}` | 查询 Runtime run 详情，等价于 status 详情 |
|
||
| `GET` | `/api/swarms/{swarm_id}/status` | 查询 Runtime run 状态、阶段、进度、Agent 和 artifact 摘要 |
|
||
| `POST` | `/api/swarms/{swarm_id}/stop` | 停止 Runtime run；幂等返回 `stopped` |
|
||
| `GET` | `/api/swarms/{swarm_id}/logs` | 查询 Runtime/Agent 日志聚合兜底 |
|
||
| `GET` | `/api/swarms/{swarm_id}/events` | 查询 Runtime message/event 兜底 |
|
||
| `GET` | `/api/swarms/{swarm_id}/metrics` | 查询基础用量、耗时、artifact 数量等指标 |
|
||
| `GET` | `/api/swarms/{swarm_id}/artifacts/{artifact_id}/content` | 读取 Runtime-local 或 Azure Blob 中的完整 artifact 内容 |
|
||
| `POST` | `/api/swarms/{swarm_id}/approvals/{approval_id}` | 接收 Manager 审批 decision，支持 `approved` / `rejected` |
|
||
|
||
审批 decision 请求示例：
|
||
|
||
```json
|
||
{
|
||
"approval_id": "appr_runtime_1",
|
||
"decision": "approved",
|
||
"manager_deployment_id": "dep_xxx",
|
||
"runtime_deployment_id": "runtime-dep-123",
|
||
"operation": "git.write",
|
||
"resource_id": "repo-main",
|
||
"resource_type": "git",
|
||
"target_role": "backend",
|
||
"requires_credential": true,
|
||
"credential_ref": "lease://agnet/lease_xxx",
|
||
"lease_id": "lease_xxx",
|
||
"lease_expires_at": 1779850900000
|
||
}
|
||
```
|
||
|
||
如果普通 sub 不走 `/api/swarms`，也支持：
|
||
|
||
```http
|
||
POST /api/agnet/deployments/{deployment_id}/approvals/{approval_id}
|
||
```
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"deployment_id": "swm_a1b2c3d4e5f6",
|
||
"swarm_id": "swm_a1b2c3d4e5f6",
|
||
"status": "initializing",
|
||
"agents": [],
|
||
"created_at": "2026-05-27T10:30:00Z",
|
||
"estimated_ready_at": "2026-05-27T10:32:00Z"
|
||
}
|
||
```
|
||
|
||
**状态响应示例**：
|
||
|
||
```json
|
||
{
|
||
"deployment_id": "swm_a1b2c3d4e5f6",
|
||
"swarm_id": "swm_a1b2c3d4e5f6",
|
||
"status": "running",
|
||
"phase": "planning",
|
||
"progress": 10,
|
||
"agents": [
|
||
{
|
||
"agent_id": "agi_backend_12345678",
|
||
"role": "backend",
|
||
"status": "running",
|
||
"namespace": "swarm-swm-a1b2c3d4e5f6",
|
||
"service_url": null,
|
||
"current_task": null,
|
||
"output": null
|
||
}
|
||
],
|
||
"metrics": {
|
||
"total_messages": 1,
|
||
"tokens_used": 0,
|
||
"elapsed_seconds": 30
|
||
},
|
||
"artifacts": [],
|
||
"error_message": null,
|
||
"created_at": "2026-05-28T10:30:00Z",
|
||
"updated_at": "2026-05-28T10:30:30Z"
|
||
}
|
||
```
|
||
|
||
#### `GET /api/agnet/user/deployments/{deployment_id}/artifacts`
|
||
|
||
查询 Runtime 通过 `artifact.created` callback 回写的产物。当前 Manager 从 callback event payload 投影生成响应；大文件只返回 `uri`、摘要、大小和 hash 信息，完整内容需要继续调用 artifact content 接口读取。完整操作流程见 [1.7 产物获取速查](#17-产物获取速查)。
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"deployment_id": "dep_a1b2c3d4",
|
||
"artifacts": [
|
||
{
|
||
"event_id": "evt_art_001",
|
||
"artifact_id": "art_backend_patch_001",
|
||
"artifact_type": "code_patch",
|
||
"title": "Backend API patch",
|
||
"summary": "新增 deployment draft 到 Runtime 的桥接逻辑",
|
||
"uri": "azblob://heicode-artifacts/task-123/backend.patch",
|
||
"mime_type": "text/x-diff",
|
||
"size_bytes": 18420,
|
||
"stage": "development",
|
||
"checkpoint": "artifact_ready",
|
||
"metadata": {
|
||
"agent_role": "backend",
|
||
"redacted": true
|
||
},
|
||
"created_at": "2026-05-27T10:40:00Z"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### `GET /api/agnet/user/deployments/{deployment_id}/artifacts/{artifact_id}/content`
|
||
|
||
读取 Runtime artifact 的完整内容。该接口是 Manager / 前端获取产物正文的推荐入口，要求携带 `Authorization: Bearer <HEICODE_SERVICE_TOKEN>`。
|
||
|
||
该接口支持两类 URI：
|
||
|
||
- `runtime://<swarm_id>/artifacts/<artifact_id>`：从 Runtime 本地 artifact store 返回文件内容。
|
||
- `azblob://<container>/<blob-name>`：使用 Runtime 从 K8s Secret 读取到的 Azure Blob 凭据代理读取内容。
|
||
|
||
Azure Blob 凭据来自 `RUNTIME_ARTIFACT_BLOB_SECRET_NAMESPACE` / `RUNTIME_ARTIFACT_BLOB_SECRET_NAME` 指定的 K8s Secret。Runtime 优先读取 `AZURE_STORAGE_CONNECTION_STRING`；若为空，则读取 `AZURE_STORAGE_ACCOUNT` + `AZURE_STORAGE_KEY`。容器名优先读取 Secret 中的 `AZURE_BLOB_CONTAINER`，否则使用 `RUNTIME_ARTIFACT_BLOB_CONTAINER`。
|
||
|
||
响应是原始文件内容，不再包一层 JSON。Runtime 会按存储记录或 Blob 属性设置 `Content-Type`，并通过 `Content-Disposition` 给出下载文件名。
|
||
|
||
**请求示例**：
|
||
|
||
```bash
|
||
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"
|
||
```
|
||
|
||
如果调用方已经持有 Runtime `swarm_id`，也可以直接使用兼容接口：
|
||
|
||
```bash
|
||
curl -L \
|
||
-H "Authorization: Bearer <HEICODE_SERVICE_TOKEN>" \
|
||
-o artifact-output.txt \
|
||
"https://agent-manager.taijiagnet.com/api/swarms/{swarm_id}/artifacts/{artifact_id}/content"
|
||
```
|
||
|
||
#### `GET /api/agnet/user/deployments/{deployment_id}/timeline`
|
||
|
||
查询合并时间线。当前 Manager 会合并 `timeline.updated`、阶段变化、Agent 状态、预算告警、审批请求、artifact 与 SK 工具事件。
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"deployment_id": "dep_a1b2c3d4",
|
||
"timeline": [
|
||
{
|
||
"event_id": "evt_tl_001",
|
||
"event_type": "timeline.updated",
|
||
"occurred_at": "2026-05-27T10:41:00Z",
|
||
"agent_instance_id": "agi_backend_001",
|
||
"title": "后端实现完成",
|
||
"summary": "backend agent 已生成 API patch，等待测试",
|
||
"stage": "development",
|
||
"checkpoint": "ready_for_test",
|
||
"severity": "info",
|
||
"next_action": "submit_test_result",
|
||
"payload": {
|
||
"agent_role": "backend"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### `GET /api/agnet/user/deployments/{deployment_id}/sk-snapshots`
|
||
|
||
查询 Runtime 回写的 SK snapshot。当前 Manager 从 `sk_tool.called/completed/failed` 和包含 `sk_snapshot` 的 artifact 事件投影生成响应。
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"deployment_id": "dep_a1b2c3d4",
|
||
"sk_snapshots": [
|
||
{
|
||
"event_id": "evt_tool_001",
|
||
"snapshot_id": "sks_task_123_backend_001",
|
||
"deployment_id": "dep_a1b2c3d4",
|
||
"agent_instance_id": "agi_backend_001",
|
||
"agent_role": "backend",
|
||
"source_type": "git",
|
||
"source_ref": "git:https://example.com/heicode-tools.git#main:backend",
|
||
"content_hash": "sha256:abc123...",
|
||
"tool_name": "repo_write",
|
||
"tool_invocation_id": "inv_abc123",
|
||
"created_at": "2026-05-27T10:35:00Z",
|
||
"metadata": {
|
||
"redacted": true
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 数据模型
|
||
|
||
### 4.1 部署状态 (DeploymentStatus)
|
||
|
||
| 状态 | 说明 |
|
||
|------|------|
|
||
| `pending` | 等待启动 |
|
||
| `running` | 运行中 |
|
||
| `stopped` | 已停止 |
|
||
| `failed` | 失败 |
|
||
|
||
### 4.2 风险等级 (RiskLevel)
|
||
|
||
| 等级 | 说明 | 审批要求 |
|
||
|------|------|----------|
|
||
| `low` | 低风险 | 无需审批 |
|
||
| `medium` | 中风险 | 无需审批 |
|
||
| `high` | 高风险 | 需要 approval_token |
|
||
|
||
### 4.3 计费提供商 (BillingProvider)
|
||
|
||
| 提供商 | 说明 |
|
||
|--------|------|
|
||
| `newapi` | Heicode NewAPI Gateway |
|
||
| `litellm` | LiteLLM Proxy |
|
||
|
||
### 4.4 资源授权类型 (ResourceGrantType)
|
||
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| `database` | 数据库访问 |
|
||
| `storage` | 存储访问 |
|
||
| `api` | API 访问 |
|
||
| `git` | 代码仓库访问 |
|
||
| `custom` | 自定义资源 |
|
||
|
||
### 4.5 sub 模式 (SubMode)
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| `agile` | 敏捷迭代模式，当前优先验证 |
|
||
| `waterfall` | 瀑布模式，按阶段顺序执行 |
|
||
|
||
缺省策略：如果请求未传 `sub_mode`，Runtime 按 `agile` 处理。
|
||
|
||
### 4.6 敏捷上下文 (AgileContext)
|
||
|
||
```json
|
||
{
|
||
"iteration": "2026-05-27~2026-05-28",
|
||
"stage": "development",
|
||
"checkpoint": "ready_for_test",
|
||
"acceptance_criteria": [
|
||
"接口返回成功",
|
||
"Manager 前端可点击验证",
|
||
"artifact 可回写到 timeline",
|
||
"不出现明文密钥"
|
||
],
|
||
"next_action": "submit_test_result",
|
||
"requires_user_approval": false
|
||
}
|
||
```
|
||
|
||
建议枚举：
|
||
|
||
| 字段 | 建议值 |
|
||
|------|--------|
|
||
| `stage` | `planning`、`development`、`testing`、`deployment`、`review`、`done` |
|
||
| `checkpoint` | `draft_created`、`runtime_accepted`、`agent_running`、`artifact_ready`、`ready_for_test`、`approval_required`、`completed`、`failed` |
|
||
| `next_action` | `continue`、`request_approval`、`submit_artifact`、`submit_test_result`、`stop` |
|
||
|
||
### 4.7 Resource Grant 与 secret_ref
|
||
|
||
Heicode sub 模式使用扩展 Resource Grant 表达任务资源授权。Runtime 必须接受 `resource_type / permission_scope / secret_ref` 形式，并可兼容旧字段 `type / permissions / ref`。
|
||
|
||
```json
|
||
{
|
||
"grant_id": "grant-task-123-backend-1",
|
||
"resource_id": "res_git_main",
|
||
"resource_type": "git",
|
||
"user_id": "123",
|
||
"binding_scope": "task-task-123",
|
||
"target_role": "backend",
|
||
"target_agent_ref": "agent-backend-1",
|
||
"permission_scope": ["read", "write"],
|
||
"constraints": {
|
||
"path_prefix": "heicode/"
|
||
},
|
||
"metadata": {
|
||
"repo": "heicode-manager"
|
||
},
|
||
"status": "active",
|
||
"secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/user-123-repo-main",
|
||
"audit": {
|
||
"source": "heicode-manager"
|
||
}
|
||
}
|
||
```
|
||
|
||
安全规则：
|
||
|
||
1. 凭据型资源必须有 `secret_ref`。
|
||
2. `secret_ref` 必须使用 `azkv://<vault>/secrets/<name>` 格式。
|
||
3. `azkv://` 是引用，不是明文密钥；Runtime 不应把它展开写入日志、回调或 artifact metadata。
|
||
4. `metadata`、`constraints`、`audit` 中禁止出现明文 `password`、`token`、`secret`、`private_key`、`connection_string`、`access_key`。
|
||
5. `vault:heicode/...` 仅作为旧版兼容，不再作为正式示例。
|
||
|
||
### 4.8 Artifact 回写模型
|
||
|
||
Runtime 通过 `/api/agnet/callbacks/swarm-events` 回写产物事件，Manager 将其持久化后供用户态接口查询。
|
||
|
||
```json
|
||
{
|
||
"event_type": "artifact.created",
|
||
"deployment_id": "dep_a1b2c3d4",
|
||
"swarm_id": "dep_a1b2c3d4",
|
||
"occurred_at": "2026-05-27T10:40:00Z",
|
||
"payload": {
|
||
"artifact_id": "art_backend_patch_001",
|
||
"artifact_type": "code_patch",
|
||
"title": "Backend API patch",
|
||
"summary": "新增 deployment draft 到 Runtime 的桥接逻辑",
|
||
"uri": "azblob://heicode-artifacts/task-123/backend.patch",
|
||
"mime_type": "text/x-diff",
|
||
"size_bytes": 18420,
|
||
"stage": "development",
|
||
"checkpoint": "artifact_ready",
|
||
"metadata": {
|
||
"agent_role": "backend",
|
||
"redacted": true
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
约束：
|
||
|
||
- `payload.summary` 可展示给用户；不得包含密钥、Token、连接串。
|
||
- 大文件只传 `uri`、摘要和大小，不在 callback body 中内联完整内容。
|
||
- Runtime 上传成功时产物使用 `azblob://<container>/<blob-name>`；上传失败时回落到 `runtime://<swarm_id>/artifacts/<artifact_id>`。完整内容通过 `/api/swarms/{swarm_id}/artifacts/{artifact_id}/content` 或用户态 artifact content 代理接口读取。
|
||
- `artifact_type` 建议值：`code_patch`、`document`、`test_report`、`deployment_manifest`、`log_bundle`、`other`。
|
||
|
||
### 4.9 Timeline 事件模型
|
||
|
||
Runtime 事件需要能合并进 Manager 时间线。除 callback 契约中的标准事件外，sub 模式事件建议带上以下字段：
|
||
|
||
```json
|
||
{
|
||
"event_type": "timeline.updated",
|
||
"deployment_id": "dep_a1b2c3d4",
|
||
"occurred_at": "2026-05-27T10:41:00Z",
|
||
"payload": {
|
||
"title": "后端实现完成",
|
||
"summary": "backend agent 已生成 API patch，等待测试",
|
||
"stage": "development",
|
||
"checkpoint": "ready_for_test",
|
||
"agent_role": "backend",
|
||
"severity": "info",
|
||
"next_action": "submit_test_result"
|
||
}
|
||
}
|
||
```
|
||
|
||
`severity` 建议值：`info`、`warning`、`error`、`success`。
|
||
|
||
### 4.10 SK Snapshot 模型
|
||
|
||
SK snapshot 用于追踪工具/技能来源、快照版本和执行上下文。Runtime 应在调用 SK 工具或生成 artifact 时回写快照引用。
|
||
|
||
```json
|
||
{
|
||
"snapshot_id": "sks_task_123_backend_001",
|
||
"deployment_id": "dep_a1b2c3d4",
|
||
"agent_instance_id": "agi_backend_001",
|
||
"agent_role": "backend",
|
||
"source_type": "git",
|
||
"source_ref": "git:https://example.com/heicode-tools.git#main:backend",
|
||
"content_hash": "sha256:abc123...",
|
||
"tool_name": "repo_write",
|
||
"tool_invocation_id": "inv_abc123",
|
||
"created_at": "2026-05-27T10:35:00Z",
|
||
"metadata": {
|
||
"redacted": true
|
||
}
|
||
}
|
||
```
|
||
|
||
约束：
|
||
|
||
- `source_ref` 不得包含账号密码、Token 或临时签名 URL。
|
||
- `metadata` 只允许放脱敏后的上下文。
|
||
- `tool_invocation_id` 应能与 `sk_tool.called/completed/failed` 事件关联。
|
||
|
||
---
|
||
|
||
## 5. 使用示例
|
||
|
||
### 5.1 完整工作流示例
|
||
|
||
```python
|
||
import requests
|
||
import time
|
||
|
||
# 配置
|
||
BASE_URL = "https://agent-manager.taijiagnet.com"
|
||
TOKEN = "sk_your_service_token"
|
||
USER_ID = "user_123"
|
||
BINDING_SCOPE = "workspace_abc"
|
||
|
||
headers = {
|
||
"Authorization": f"Bearer {TOKEN}",
|
||
"X-User-ID": USER_ID,
|
||
"X-Binding-Scope": BINDING_SCOPE,
|
||
"X-Correlation-ID": f"req_{int(time.time())}",
|
||
"Content-Type": "application/json"
|
||
}
|
||
|
||
# 1. 创建部署
|
||
create_payload = {
|
||
"orchestration_plan": "research-and-write",
|
||
"risk_level": "medium",
|
||
"budget": {
|
||
"max_usd": 50.0,
|
||
"alert_threshold_pct": 80
|
||
},
|
||
"billing_context": {
|
||
"provider": "newapi",
|
||
"default_model_id": "gpt-4",
|
||
"allowed_model_ids": ["gpt-4", "gpt-3.5-turbo"],
|
||
"secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/model-gateway-key"
|
||
},
|
||
"agents": [
|
||
{
|
||
"role": "researcher",
|
||
"image": "agnettaiji.azurecr.io/ai-agents/search-agent:v1.2.0"
|
||
},
|
||
{
|
||
"role": "writer",
|
||
"image": "agnettaiji.azurecr.io/ai-agents/doc-creator:v1.2.0"
|
||
}
|
||
],
|
||
"resource_grants": []
|
||
}
|
||
|
||
response = requests.post(
|
||
f"{BASE_URL}/api/agnet/deployments",
|
||
headers=headers,
|
||
json=create_payload
|
||
)
|
||
deployment = response.json()
|
||
deployment_id = deployment["deployment_id"]
|
||
print(f"✅ 部署创建成功: {deployment_id}")
|
||
|
||
# 2. 等待部署就绪
|
||
time.sleep(120) # 等待 2 分钟
|
||
|
||
# 3. 获取部署详情
|
||
response = requests.get(
|
||
f"{BASE_URL}/api/agnet/deployments/{deployment_id}",
|
||
headers=headers
|
||
)
|
||
details = response.json()
|
||
print(f"📊 部署状态: {details['status']}")
|
||
|
||
# 4. 获取实时日志
|
||
response = requests.get(
|
||
f"{BASE_URL}/api/agnet/deployments/{deployment_id}/logs?limit=20",
|
||
headers=headers
|
||
)
|
||
logs = response.json()
|
||
print(f"📝 最新日志: {len(logs['logs'])} 条")
|
||
|
||
# 5. 获取资源指标
|
||
response = requests.get(
|
||
f"{BASE_URL}/api/agnet/deployments/{deployment_id}/metrics",
|
||
headers=headers
|
||
)
|
||
metrics = response.json()
|
||
print(f"💻 CPU 使用: {metrics['total_resources']['cpu_usage_cores']} cores")
|
||
print(f"💾 内存使用: {metrics['total_resources']['memory_usage_mb']} MB")
|
||
|
||
# 6. 停止部署
|
||
stop_payload = {
|
||
"reason": "Task completed successfully"
|
||
}
|
||
response = requests.post(
|
||
f"{BASE_URL}/api/agnet/deployments/{deployment_id}/stop",
|
||
headers=headers,
|
||
json=stop_payload
|
||
)
|
||
result = response.json()
|
||
print(f"🛑 部署已停止: {result['stopped_at']}")
|
||
```
|
||
|
||
### 5.2 幂等性示例
|
||
|
||
使用 `X-Idempotency-Key` 确保请求幂等性：
|
||
|
||
```python
|
||
import uuid
|
||
|
||
idempotency_key = f"idem_{uuid.uuid4().hex}"
|
||
|
||
headers = {
|
||
"Authorization": f"Bearer {TOKEN}",
|
||
"X-User-ID": USER_ID,
|
||
"X-Binding-Scope": BINDING_SCOPE,
|
||
"X-Correlation-ID": f"req_{int(time.time())}",
|
||
"X-Idempotency-Key": idempotency_key, # 幂等性键
|
||
"Content-Type": "application/json"
|
||
}
|
||
|
||
# 第一次请求
|
||
response1 = requests.post(
|
||
f"{BASE_URL}/api/agnet/deployments",
|
||
headers=headers,
|
||
json=create_payload
|
||
)
|
||
|
||
# 重复请求（使用相同的 idempotency_key）
|
||
response2 = requests.post(
|
||
f"{BASE_URL}/api/agnet/deployments",
|
||
headers=headers,
|
||
json=create_payload
|
||
)
|
||
|
||
# response1 和 response2 返回相同的结果
|
||
assert response1.json()["deployment_id"] == response2.json()["deployment_id"]
|
||
```
|
||
|
||
### 5.3 普通 sub Runtime 联调示例
|
||
|
||
以下示例使用 `/api/swarms` 入口创建普通 sub 敏捷 Runtime run，并查询状态与时间线。
|
||
|
||
```python
|
||
import requests
|
||
import time
|
||
import uuid
|
||
|
||
BASE_URL = "http://20.212.121.126"
|
||
TOKEN = "sk_your_service_token"
|
||
|
||
headers = {
|
||
"Authorization": f"Bearer {TOKEN}",
|
||
"X-Correlation-ID": f"req_{int(time.time())}",
|
||
"X-Idempotency-Key": f"idem_{uuid.uuid4().hex}",
|
||
"Content-Type": "application/json"
|
||
}
|
||
|
||
payload = {
|
||
"orchestration_plan": {
|
||
"intent_id": "task_123",
|
||
"objective": "完成本轮任务目标",
|
||
"sub_mode": "agile",
|
||
"user_context": {
|
||
"user_id": "123",
|
||
"binding_scope": "task-task-123"
|
||
},
|
||
"budget": {
|
||
"max_cost_usd": 8,
|
||
"max_duration_sec": 3600
|
||
},
|
||
"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"
|
||
},
|
||
"agents": [
|
||
{
|
||
"role_template": "backend",
|
||
"default_model_id": "model_xxx"
|
||
}
|
||
]
|
||
},
|
||
"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"
|
||
}
|
||
}
|
||
|
||
created = requests.post(f"{BASE_URL}/api/swarms", headers=headers, json=payload)
|
||
created.raise_for_status()
|
||
run = created.json()
|
||
swarm_id = run["swarm_id"]
|
||
|
||
status = requests.get(f"{BASE_URL}/api/swarms/{swarm_id}/status", headers=headers)
|
||
status.raise_for_status()
|
||
print(status.json()["status"])
|
||
|
||
timeline = requests.get(
|
||
f"{BASE_URL}/api/agnet/user/deployments/{run['deployment_id']}/timeline",
|
||
headers={"Authorization": f"Bearer {TOKEN}"}
|
||
)
|
||
timeline.raise_for_status()
|
||
print(len(timeline.json()["timeline"]))
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 错误处理
|
||
|
||
### 6.1 错误响应格式
|
||
|
||
所有错误响应遵循统一格式：
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": {
|
||
"code": "ERROR_CODE",
|
||
"message": "Human-readable error message",
|
||
"request_id": "req_xyz789"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.2 错误码列表
|
||
|
||
| HTTP 状态码 | 错误码 | 说明 |
|
||
|------------|--------|------|
|
||
| 401 | `UNAUTHORIZED` | 认证失败，Token 无效 |
|
||
| 403 | `FORBIDDEN` | 权限不足 |
|
||
| 404 | `DEPLOYMENT_NOT_FOUND` | 部署不存在 |
|
||
| 409 | `DEPLOYMENT_CONFLICT` | 部署状态冲突 |
|
||
| 422 | `MODEL_NOT_ALLOWED` | 模型不在允许列表中 |
|
||
| 422 | `POLICY_REJECTED` | 策略拒绝（如高风险需审批） |
|
||
| 422 | `SUB_MODE_UNSUPPORTED` | `sub_mode` 不是 `agile` 或 `waterfall` |
|
||
| 422 | `SECRET_REF_INVALID` | `secret_ref` 不是 `azkv://<vault>/secrets/<name>` 格式 |
|
||
| 422 | `RESOURCE_GRANT_INVALID` | Resource Grant 缺少资源类型、权限范围或 `secret_ref` |
|
||
| 422 | `CALLBACK_URL_INVALID` | callback URL 非 HTTPS 或路径不符合约定 |
|
||
| 422 | `ARTIFACT_METADATA_REJECTED` | artifact metadata 含疑似明文密钥 |
|
||
| 422 | `SK_SNAPSHOT_INVALID` | SK snapshot 缺少 source/hash/invocation 关联字段 |
|
||
| 422 | `VALIDATION_ERROR` | 请求参数验证失败 |
|
||
| 429 | `RATE_LIMITED` | 请求过载或 callback 接收端限流 |
|
||
| 500 | `INTERNAL_ERROR` | 服务器内部错误 |
|
||
|
||
### 6.3 错误处理示例
|
||
|
||
```python
|
||
try:
|
||
response = requests.post(
|
||
f"{BASE_URL}/api/agnet/deployments",
|
||
headers=headers,
|
||
json=create_payload
|
||
)
|
||
response.raise_for_status()
|
||
deployment = response.json()
|
||
|
||
except requests.exceptions.HTTPError as e:
|
||
error_data = e.response.json()
|
||
error_code = error_data["error"]["code"]
|
||
error_message = error_data["error"]["message"]
|
||
|
||
if error_code == "MODEL_NOT_ALLOWED":
|
||
print(f"❌ 模型配置错误: {error_message}")
|
||
elif error_code == "POLICY_REJECTED":
|
||
print(f"❌ 需要审批: {error_message}")
|
||
else:
|
||
print(f"❌ 请求失败: {error_message}")
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 最佳实践
|
||
|
||
### 7.1 认证和安全
|
||
|
||
✅ **推荐做法**:
|
||
- 将 Service Token 存储在环境变量或密钥管理系统中
|
||
- 使用 HTTPS 进行所有 API 调用
|
||
- 定期轮换 Service Token
|
||
- 使用 Azure Key Vault 存储敏感配置，并只在请求中传递 `azkv://...` 引用
|
||
|
||
❌ **避免**:
|
||
- 在代码中硬编码 Token
|
||
- 在日志中打印 Token
|
||
- 在 URL 参数中传递敏感信息
|
||
- 在 callback、artifact metadata、timeline 或 SK snapshot 中写入明文密钥
|
||
|
||
### 7.2 幂等性
|
||
|
||
✅ **推荐做法**:
|
||
- 对所有创建操作使用 `X-Idempotency-Key`
|
||
- 使用 UUID 或时间戳生成唯一的幂等性键
|
||
- 在网络不稳定时重试请求
|
||
|
||
### 7.3 预算控制
|
||
|
||
✅ **推荐做法**:
|
||
- 设置合理的 `max_usd` 预算上限
|
||
- 设置 `alert_threshold_pct` 为 80-90%
|
||
- 定期检查 `consumed_usd` 和 `remaining_usd`
|
||
- 在预算告警时及时停止部署
|
||
|
||
### 7.4 日志和监控
|
||
|
||
✅ **推荐做法**:
|
||
- 使用 `X-Correlation-ID` 追踪请求链路
|
||
- 定期轮询 `/logs` 和 `/events` 端点
|
||
- 监控 `/metrics` 端点的资源使用情况
|
||
- 保存审计日志用于问题排查
|
||
|
||
### 7.5 错误处理
|
||
|
||
✅ **推荐做法**:
|
||
- 实现指数退避重试机制
|
||
- 区分可重试错误（5xx）和不可重试错误（4xx）
|
||
- 记录完整的错误上下文（request_id, correlation_id）
|
||
- 为高风险操作准备回滚方案
|
||
|
||
### 7.6 性能优化
|
||
|
||
✅ **推荐做法**:
|
||
- 使用分页参数避免一次性获取大量数据
|
||
- 缓存不常变化的数据（如模板列表）
|
||
- 使用 `since` 参数增量获取日志和事件
|
||
- 并发调用独立的 API 端点
|
||
|
||
---
|
||
|
||
## 8. 附录
|
||
|
||
### 8.1 支持的 Agent 镜像
|
||
|
||
| Agent 类型 | 镜像地址 | 说明 |
|
||
|-----------|---------|------|
|
||
| Search Agent | `agnettaiji.azurecr.io/ai-agents/search-agent:v1.2.0` | 搜索和信息检索 |
|
||
| Doc Creator | `agnettaiji.azurecr.io/ai-agents/doc-creator:v1.2.0` | 文档生成 |
|
||
| Code AI Agent | `agnettaiji.azurecr.io/ai-agents/code-ai-agent:v1.2.0` | 代码生成和 CI/CD |
|
||
| Ad Creator | `agnettaiji.azurecr.io/ai-agents/ad-creator:v1.2.0` | 广告创意生成 |
|
||
| Video Generator | `agnettaiji.azurecr.io/ai-agents/video-generator:v1.2.0` | 视频生成 |
|
||
|
||
### 8.2 联系方式
|
||
|
||
- **技术支持**: support@taijiagnet.com
|
||
- **API 文档**: https://agent-manager.taijiagnet.com/docs
|
||
- **问题反馈**: https://github.com/your-org/agent-manager/issues
|
||
|
||
### 8.3 更新日志
|
||
|
||
| 版本 | 日期 | 更新内容 |
|
||
|------|------|----------|
|
||
| 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 读取接口 |
|
||
| v2.1.7 | 2026-05-29 | 修复普通 sub terminal run 空产物兜底：执行成功但无产物会生成 summary artifact，执行失败/blocked 会生成 failure artifact，历史空产物 run 的 `/api/swarms/{id}`、`events`、`metrics` 查询会合成可展示 artifact；部署镜像更新为 `heicode-v2-20260529232620` |
|
||
| 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.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 模型 |
|
||
| v2.0.0 | 2026-05-12 | 初始版本，支持 Heicode 集成 |
|
||
|
||
---
|
||
|
||
**文档版本**: v2.1.10
|
||
**最后更新**: 2026-05-30
|
||
**维护者**: Agent Manager Team
|