zhanggangyong/agent_management
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bf1508e49cee005402932407459135e5e18ca0dd
agent_management/docs/HEICODE_V2_1_4_UPDATE_SUMMARY.md
T

9.9 KiB
Raw Blame History

Heicode v2.1.6 更新说明

生成日期: 2026-05-29
适用版本: heicode-v2-20260529120632
主文档: docs/HEICODE_API_INTEGRATION.md
联调 Base URL: http://20.212.121.126

1. 更新概览

本次更新面向 Heicode 普通 sub 敏捷模式联调，重点补齐 Agent Manager 作为 Runtime 适配层时需要的创建、查询、回调、审批和观测能力。

核心变化：

  • /api/swarms 新增 Runtime 兼容入口，可接收 Heicode Manager 的结构化 orchestration_plan。
  • /api/agent/sub-agile/deployments 支持普通 sub 结构化计划，并会主动发出 Runtime 生命周期 callback。
  • 修复普通 sub 真实执行后缺失 artifact.created 的问题，并补齐用户态 artifacts 可见性。
  • 新增 task.completed / task.failed / task.blocked 事件，用于补齐普通 sub 子任务终态。
  • 修复 deployment 已完成但 agents[].status 仍为 running 的状态不一致问题。
  • /api/swarms/{swarm_id}/logs 不再返回 Phase 2 固定占位文本，而是输出 Runtime 聚合日志摘要。
  • Callback 协议升级到 v2.1 形态，支持 HMAC 签名、幂等事件、payload.* 格式和旧 token 过渡兼容。
  • 新增 artifact、timeline、SK snapshot 用户态查询接口，数据由 Runtime callback event 投影生成。
  • 新增审批 decision 接收路径，覆盖 /api/swarms 和 /api/agent/sub-agile/deployments 两种运行入口。
  • K8s/Docker 部署配置补充 Heicode、Vault、Redis、模型网关相关环境变量和代码目录。

2. API 变更

2.1 /api/swarms Runtime 兼容入口

新增或补齐以下接口：

方法 路径 用途
POST /api/swarms 创建 Runtime run，映射到底层 swarm 执行记录
GET /api/swarms/{swarm_id} 查询 run 详情
GET /api/swarms/{swarm_id}/status 查询状态、阶段、进度、Agent 和 artifact 摘要
POST /api/swarms/{swarm_id}/stop 幂等停止 run
GET /api/swarms/{swarm_id}/logs 查询 Runtime/Agent 日志聚合兜底
GET /api/swarms/{swarm_id}/events 查询 Runtime message/event 兜底
GET /api/swarms/{swarm_id}/metrics 查询基础用量、耗时和产物数量
POST /api/swarms/{swarm_id}/approvals/{approval_id} 接收 Manager 审批 decision

创建校验规则：

  • dry_run: true 会返回 422，不会创建真实 run。
  • orchestration_plan 必须是对象。
  • orchestration_plan.sub_mode 必须是 agile 或 waterfall。
  • orchestration_plan.user_context.user_id 必填。
  • callback.url 必填。
  • 同一个 X-Idempotency-Key 会返回已有 run，避免重复创建。

响应兼容：

  • deployment_id 与 swarm_id 同时返回；当前两者同值。
  • /api/agent/sub-agile/deployments/{deployment_id} 可查询 /api/swarms 创建出的 run。
  • /api/agent/sub-agile/deployments/{deployment_id}/stop 可停止 /api/swarms 创建出的 run。

2.2 /api/agent/sub-agile/deployments 普通 sub 兼容

创建部署现在可以直接接收结构化 orchestration_plan，并将字段提升到旧版模型：

  • agents
  • risk_level
  • budget
  • billing_context
  • resource_grants
  • metadata
  • agile_context
  • sub_mode
  • callback

兼容字段：

  • agents[].role_template 或 agents[].target_role 会规范化为 role。
  • billing_context.default_model_id 为空时默认填充为 default。
  • billing_context.allowed_model_ids 为空时默认使用 default_model_id。
  • budget.max_usd 与 budget.max_cost_usd 双向兼容。
  • resource_grants 同时兼容 type/ref/permissions 和 resource_type/secret_ref/permission_scope。

安全规则：

  • callback.url 必须使用 https://。
  • callback.signing_secret_ref 必须使用 azkv://。
  • billing_context.secret_ref 必须使用 azkv://。
  • resource_grants 只能传 secret reference，不能传明文凭据。
  • 请求体、callback payload、artifact metadata 等仍会执行敏感字段扫描。

3. Callback 与观测

3.1 Runtime 主动回调

/api/agent/sub-agile/deployments 和 /api/swarms 创建的任务会根据 callback.subscribed_events 主动推送事件。

默认事件集：

  • deployment.status_changed
  • phase.changed
  • timeline.updated
  • agent.started
  • agent.completed
  • agent.crashed
  • task.completed
  • task.failed
  • task.blocked
  • sk_tool.called
  • sk_tool.completed
  • sk_tool.failed
  • approval.requested
  • budget.alert
  • artifact.created

当前 callback 发送端会：

  • 使用 X-Agnet-Event-Id 做事件幂等标识。
  • 使用 X-Agnet-Timestamp 和 X-Agnet-Signature 做 HMAC 校验。
  • 优先从 callback.signing_secret_ref 对应环境变量或 Azure Key Vault 解析签名密钥。
  • 发送失败时记录 warning，不阻塞 Runtime 执行。

3.2 Manager callback 接收端

新增接收接口：

POST /api/agent/callbacks/runtime-events

支持能力：

  • v2.1 HMAC callback。
  • 旧版 X-Agnet-Service-Token 或 Authorization: Bearer <HEICODE_SERVICE_TOKEN> 过渡兼容。
  • X-Agnet-Event-Id 或 body event_id 幂等去重。
  • payload.* 标准载荷格式。
  • 旧版顶层 artifact 自动合并到 payload。
  • swarm_id、occurred_at、agent_instance_id 会持久化到事件投影。
  • approval.requested 会写入审计标记。

联调 schema 接口：

GET /api/agent/callbacks/runtime-events/schema

该接口只返回事件类型、分类、必填字段、阶段枚举和 artifact 类型，不返回 token 或明文密钥。

3.3 用户态观测接口

新增或补齐：

方法 路径 数据来源
GET /api/agent/user/deployments/{deployment_id}/artifacts artifact.created callback payload
GET /api/agent/user/deployments/{deployment_id}/timeline timeline、phase、agent、approval、budget、artifact、SK tool 事件合并
GET /api/agent/user/deployments/{deployment_id}/sk-snapshots sk_tool.* 与携带 sk_snapshot 的 artifact 事件

注意：当前 artifact/timeline/SK snapshot 不是独立表字段化存储，而是由 callback event payload 投影生成。

4. 审批与预算

审批路径：

场景 接口
/api/swarms run POST /api/swarms/{swarm_id}/approvals/{approval_id}
普通 deployment POST /api/agent/sub-agile/deployments/{deployment_id}/approvals/{approval_id}

decision 只接受：

  • approved
  • rejected

预算与用量：

  • budget.alert payload 会包含 model_id、token 计数、成本、运行时长、资源秒、billing_source 和预算摘要。
  • /api/swarms/{swarm_id}/metrics 当前返回本地基础聚合，后续可接入真实 Pod 指标与日志后端。

5. 部署与配置

Docker 镜像：

  • 当前部署镜像更新为 agnettaiji.azurecr.io/ai-agents/agent-manager:heicode-v2-20260529120632。
  • 当前 AKS 线上运行 digest 为 sha256:8aebf04ff6a4f398d6a9a75583199db2b62f2a29c2aad2390e7225ac59ef52dd。
  • Dockerfile 已复制 config/、api/、models/，确保 Heicode 对接模块进入镜像。

新增运行时配置项：

  • HEICODE_SERVICE_TOKEN
  • REDIS_URL
  • HEICODE_NEWAPI_BASE_URL
  • LITELLM_BASE_URL
  • NAMESPACE_PREFIX
  • MAX_CONCURRENT_DEPLOYMENTS_PER_USER
  • MAX_CONCURRENT_DEPLOYMENTS_PER_SCOPE
  • VAULT_URL
  • VAULT_TOKEN

安全提醒：

  • K8s Secret 清单在提交或对外分发前应只保留占位符，不应包含真实 Azure、Vault、Gitee 或 Heicode token。
  • azkv:// 是密钥引用，不是明文密钥；Runtime 不应把它展开写入日志、callback、timeline 或 artifact metadata。

6. 已知限制

  • Callback 发送失败当前只记录 warning，不阻塞任务执行；尚未实现完整重试队列、死信队列和人工 replay。
  • /api/swarms/{id}/logs、events、metrics 目前是 Runtime/Swarm 本地聚合与轮询兜底，未接入完整日志和指标后端。
  • credential lease 的真实凭证兑换仍由 Manager / Vault 链路负责，Runtime 只消费 credential_ref。
  • artifact/timeline/SK snapshot 当前由 event payload 投影生成，后续如需强查询能力可拆为独立表。
  • SSE 实时日志流仍是后续增强项。

7. 建议联调清单

  1. 调用 GET /api/agent/health 确认服务可用。
  2. 调用 GET /api/agent/callbacks/runtime-events/schema 确认 callback schema 与事件类型。
  3. 使用 POST /api/swarms 创建普通 sub 敏捷 run，并传入 X-Idempotency-Key。
  4. 重复第 3 步确认幂等返回已有 run。
  5. 使用缺失 callback.url、缺失 user_context.user_id、dry_run:true 的 payload 验证 422。
  6. 查询 /api/swarms/{swarm_id} 和 /api/swarms/{swarm_id}/status 验证 deployment_id / swarm_id 兼容。
  7. 验证普通 sub 实际执行后会收到 task.completed / task.failed 回调。
  8. 验证 Runtime 主动 callback 是否写入 /api/agent/user/deployments/{deployment_id}/timeline。
  9. 验证普通 sub 实际执行后会收到 artifact.created，并查询 artifacts 不再为 0。
  10. 发送 sk_tool.completed 或带 sk_snapshot 的 artifact callback 后查询 SK snapshots。
  11. 触发或模拟 approval.requested 后调用 approval decision 接口验证 approved / rejected。

8. 相关代码位置

模块 文件
Heicode API router api/agnet/router.py
部署创建、停止、审批 api/agnet/deployments.py
Callback 接收与用户态观测 api/agnet/callbacks.py
Heicode 请求/响应模型 api/agnet/models.py
Runtime callback 发送端 api/swarm/callback_client.py
/api/swarms 兼容入口 api/swarm/router.py
Swarm callback 触发点 api/swarm/orchestrator.py
数据模型 database.py
配置项 config/settings.py
错误码 config/error_codes.py
K8s 配置 k8s/agent-manager-configmap.yaml、k8s/agent-manager-deployment.yaml、k8s/agent-manager-secret.yaml
Reference in New Issue View Git Blame Copy Permalink