zhanggangyong/agent_management

Fork 1

Files

T

elipitc 9bc172b22a Refresh sub-mode runtime integration guide

2026-06-01 20:39:13 +08:00

11 KiB

Raw Blame History

Heicode Sub Mode Runtime 对接指南

更新时间：2026-06-01

本文档是给 Manager / 客户端 / 平台接入方 的 sub mode 对接指南。目标不是解释历史背景，而是让别人能够基于本文档直接接通当前仓库提供的 Sub Agile / 普通 sub 模式 Runtime。

1. 先记结论

当前仓库只负责：

sub_agile / 普通 sub 模式 Runtime

当前仓库不负责：

真正的 Swarm 产品模式
独立的 swarm-only API

命名约定：

agent：主命名，新的标准入口
agnet：兼容命名，旧调用方继续可用
/api/swarms：仅是 sub-mode compatibility API，不代表当前仓库实现独立 swarm 产品

推荐接入原则：

新接入统一走 /api/agent/*
旧系统暂时可继续走 /api/agnet/*
只有历史 Runtime 兼容方才使用 /api/swarms

2. 推荐接法

2.1 健康检查

主路径：

GET /api/agent/health

兼容路径：

GET /api/agnet/health

返回示例：

{
  "success": true,
  "data": {
    "status": "healthy",
    "service": "agent-manager-sub-mode-runtime",
    "version": "1.0.0",
    "phase": "sub-mode-runtime"
  }
}

2.2 创建 deployment

主路径：

POST /api/agent/sub-agile/deployments

兼容路径：

POST /api/agnet/deployments

Runtime 兼容创建路径：

POST /api/swarms

如果你是新接入方，优先使用：

POST /api/agent/sub-agile/deployments

2.3 查询状态

主路径：

GET /api/agent/sub-agile/deployments/{deployment_id}

兼容路径：

GET /api/agnet/deployments/{deployment_id}
GET /api/swarms/{swarm_id}
GET /api/swarms/{swarm_id}/status

2.4 停止与审批

主路径：

POST /api/agent/sub-agile/deployments/{deployment_id}/stop
POST /api/agent/sub-agile/deployments/{deployment_id}/approvals/{approval_id}

兼容路径：

POST /api/agnet/deployments/{deployment_id}/stop
POST /api/agnet/deployments/{deployment_id}/approvals/{approval_id}
POST /api/swarms/{swarm_id}/stop
POST /api/swarms/{swarm_id}/approvals/{approval_id}

2.5 读取产物

推荐路径：

GET /api/agent/user/deployments/{deployment_id}/artifacts
GET /api/agent/user/deployments/{deployment_id}/artifacts/{artifact_id}/content

兼容路径：

GET /api/agnet/user/deployments/{deployment_id}/artifacts
GET /api/agnet/user/deployments/{deployment_id}/artifacts/{artifact_id}/content
GET /api/swarms/{swarm_id}/artifacts/{artifact_id}/content

3. 状态语义

当前对外统一投影为以下状态：

accepted
running
waiting_approval
completed
failed
stopped

含义建议：

accepted：Runtime 已接单，尚未进入明确执行态
running：至少有一个 subagent 正在执行
waiting_approval：Runtime 请求用户审批，等待 decision
completed：任务完成，并且已经有终态结果或产物
failed：执行失败
stopped：被显式停止

注意：

新创建 deployment 默认返回 accepted
approval.requested 会把展示状态投影为 waiting_approval
/api/swarms 虽然内部复用旧表和旧 runtime 记录，但对外也返回同一套状态集合

4. 推荐请求结构

4.1 新接入推荐请求

推荐你用结构化 sub mode 请求，而不是只发自然语言字符串。

示例：

{
  "orchestration_plan": {
    "intent_id": "task_demo_001",
    "template_hint": "fastapi-crud",
    "objective": "为任务管理系统生成 FastAPI CRUD 后端方案",
    "sub_mode": "agile",
    "user_context": {
      "user_id": "user_123",
      "binding_scope": "project_task_demo_001"
    },
    "agile_context": {
      "stage": "planning",
      "checkpoint": "draft_created",
      "max_iterations": 1
    },
    "budget": {
      "max_cost_usd": 1,
      "max_tokens": 2000,
      "max_duration_sec": 600,
      "alert_threshold_pct": 80
    },
    "billing_context": {
      "provider": "newapi",
      "default_model_id": "gpt-5.4",
      "allowed_model_ids": ["gpt-5.4"],
      "stream": false
    },
    "agents": [
      {
        "role": "backend",
        "template": "a2a_litellm_agent",
        "model": "gpt-5.4",
        "capabilities": ["code", "api", "test"]
      },
      {
        "role": "frontend",
        "template": "a2a_litellm_agent",
        "model": "gpt-5.4",
        "capabilities": ["ui", "react", "css"]
      }
    ]
  },
  "callback": {
    "url": "https://your-manager.example.com/api/agent/callbacks/runtime-events"
  }
}

4.2 最低必填项

如果走 /api/swarms 兼容入口，最低要求至少要有：

orchestration_plan
orchestration_plan.sub_mode
orchestration_plan.user_context.user_id
callback.url

否则会返回 422

5. 创建响应与查询响应

5.1 创建响应示例

{
  "deployment_id": "swm_xxx",
  "swarm_id": "swm_xxx",
  "status": "accepted",
  "agents": [
    {
      "agent_id": "agi_backend_xxx",
      "role": "backend",
      "status": "pending",
      "namespace": "swarm-swm-xxxx-backend",
      "service_url": "http://agent-....svc.cluster.local:8000"
    }
  ],
  "created_at": "2026-06-01T12:00:00Z",
  "estimated_ready_at": "2026-06-01T12:02:00Z"
}

字段说明：

deployment_id：对外主标识
swarm_id：仅为兼容字段；当前通常与 deployment_id 相同
agents：当前 runtime 里为本次执行创建的 subagent 实例

5.2 状态响应示例

{
  "deployment_id": "swm_xxx",
  "swarm_id": "swm_xxx",
  "status": "completed",
  "phase": "development",
  "progress": 100,
  "agents": [
    {
      "agent_id": "agi_backend_xxx",
      "role": "backend",
      "status": "completed",
      "output": "后端实现摘要..."
    }
  ],
  "metrics": {
    "total_messages": 4,
    "tokens_used": 1514,
    "elapsed_seconds": 33
  },
  "artifacts": [
    {
      "artifact_id": "art_xxx_backend_1",
      "artifact_type": "code_patch",
      "title": "backend task delivery",
      "summary": "后端实现摘要...",
      "uri": "azblob://...",
      "metadata": {
        "runtime_deployment_id": "swm_xxx",
        "download_path": "/api/swarms/swm_xxx/artifacts/art_xxx_backend_1/content"
      }
    }
  ]
}

6. 回调事件

6.1 主回调入口

POST /api/agent/callbacks/runtime-events

6.2 兼容回调入口

POST /api/agnet/callbacks/swarm-events

6.3 当前支持的关键事件

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

6.4 接入建议

对接方至少应该消费：

deployment.status_changed
phase.changed
artifact.created
approval.requested

如果你只做最小接入，这四类事件足够支撑：

状态展示
阶段进度
产物列表刷新
审批按钮展示

7. 产物读取约定

7.1 推荐读取顺序

推荐按照这个顺序读取结果：

查询 deployment 状态
等待 status=completed，或者在 artifacts 不为空时提前读取
调用 artifacts list 接口获取 artifact_id
再通过 content 接口拉完整正文

7.2 synthesized fallback artifact

如果真实 agent 没有产出具体 artifact，runtime 会生成 fallback artifact。

约定：

fallback artifact 仍然会出现在 artifacts 列表中
它的用途是让 Manager 和客户端至少有一个可展示终态结果
识别方式是：

{
  "metadata": {
    "synthesized": true
  }
}

8. 真实联调建议

这是本次线上验证后的建议，不是理论建议。

8.1 当前稳定范围

当前 runtime 对以下任务更稳定：

小型单文件函数生成
小型 React 组件生成
中小型实现摘要 / 代码骨架任务

8.2 当前不稳定范围

当前 runtime 在以下任务上可能失败：

单次 prompt 很长的真实开发任务
要求一次性输出大段后端 + 前端 + reviewer 的任务
输出内容过大、tokens 较高的代码生成任务

实际线上现象：

较大的真实编程任务可能在模型网关返回 504 Gateway Time-out

8.3 推荐任务拆分方式

为了让 sub mode 更稳定，建议把一个大任务拆成多个小任务，例如：

先生成数据模型与 API 列表
再生成 CRUD 路由代码骨架
再生成 pytest 用例
前端单独生成为组件与样式骨架
reviewer 单独作为收尾检查任务

不要一上来就发：

“生成完整后端项目”
“生成完整前后端联调代码”
“一次性给出所有页面、接口、测试和审查报告”

9. 模型网关配置要求

这是当前最容易踩坑的地方。

当前 runtime agent 需要一个真正返回模型 JSON 的 OpenAI 兼容基址。

当前线上有效配置是：

https://code.xinghanlab.com/v1

不是：

https://code.xinghanlab.com

如果少了 /v1，subagent 实际打到的会是站点 HTML，而不是模型接口，结果会出现：

JSON 解析失败
artifact 为空
或整体任务失败

建议至少确保以下配置正确：

HEICODE_NEWAPI_BASE_URL=https://code.xinghanlab.com/v1
LITELLM_BASE_URL=https://code.xinghanlab.com/v1

10. 最小验证流程

10.1 服务与契约验证

curl http://127.0.0.1:8000/api/agent/health
curl http://127.0.0.1:8000/api/agnet/health
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python3 -m pytest tests/test_sub_mode_runtime_contract.py -q

10.2 真实 smoke 验证

建议至少跑一条小型真实编程任务，例如：

生成 Python 工具函数 + pytest
生成 React 小组件 + CSS

成功标准：

创建响应返回 accepted
最终状态到 completed
artifacts 非空
artifacts/{artifact_id}/content 返回可读正文，而不是 UUID、HTML 或空串

11. 相关文件

主入口与兼容入口：

状态投影：

api/status_projection.py

K8s 部署与配置：

如果接入方只想记最关键的三件事，只需要记：

新接入统一走 /api/agent/sub-agile/*
结果读取统一走 deployment_id -> artifacts -> artifact content
模型网关基址必须是 https://code.xinghanlab.com/v1

11 KiB Raw Blame History Unescape Escape

Heicode Sub Mode Runtime 对接指南

1. 先记结论

2. 推荐接法

2.1 健康检查

2.2 创建 deployment

2.3 查询状态

2.4 停止与审批

2.5 读取产物

3. 状态语义

4. 推荐请求结构

4.1 新接入推荐请求

4.2 最低必填项

5. 创建响应与查询响应

5.1 创建响应示例

5.2 状态响应示例

6. 回调事件

6.1 主回调入口

6.2 兼容回调入口

6.3 当前支持的关键事件

6.4 接入建议

7. 产物读取约定

7.1 推荐读取顺序

7.2 synthesized fallback artifact

8. 真实联调建议

8.1 当前稳定范围

8.2 当前不稳定范围

8.3 推荐任务拆分方式

9. 模型网关配置要求

10. 最小验证流程

10.1 服务与契约验证

10.2 真实 smoke 验证

11. 相关文件

11 KiB

Raw Blame History