docs(integration): HM<->AM interface contract for the template-agent model
Hand-off doc for the agent_management team: the 4 endpoints AM must implement (start/status/stop/delete) with exact request/response (grounded in the isolated adapter agent_template_runtime.go), the env naming convention AM templates must read (git/vm/db/blob/bucket), AM's responsibilities (inject .env, validate the agent access token, models via HM /v1/*, no secret leakage), the client<->agent direct SSE contract AM needs to define, security requirements, the env-overridable paths, and a joint integration checklist. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.8
@@ -0,0 +1,133 @@
|
||||
# HM ↔ AM 接口契约（模板 Agent 模型）— 给 agent_management 团队
|
||||
|
||||
> 更新时间：2026-06-04
|
||||
> 角色:**HM** = Heicode Manager(网关/控制面/模型网关)。**AM** = agent_management(云端 agent 运行时,你们)。
|
||||
> 现状:HM 侧已全部实现并生产验证;**等 AM 实现本文 4 个接口 + agent 直连端**,整条链路即打通。HM 调 AM 的代码全部隔离在 `heicode/controller/agent_template_runtime.go`,字段/路径可按本文对齐;路径都支持环境变量覆盖(见末尾)。
|
||||
|
||||
---
|
||||
|
||||
## 0. 模型一句话
|
||||
|
||||
用户在 HM 网页台选「资源 + agent 模板」部署 → **HM 把 agent 定义(.md)+ 解好的资源 env 交给 AM 启动** → AM 起一个**常驻 agent**、分配**唯一子域名 + 访问 token** 返回 → 桌面客户端从 HM 拿到地址+token 后**直连 agent(SSE)对话**。HM 不在对话回路;agent 用模型走 HM `/v1/*`。
|
||||
|
||||
---
|
||||
|
||||
## 1. AM 需要提供的 4 个接口
|
||||
|
||||
HM 用 `Authorization: Bearer <service_token>` 调 AM。统一响应信封建议 `{ "success": true, "data": {...} }`(HM 会从 `data` 取值;失败给 `{ "success": false, "message": "..." }`)。
|
||||
|
||||
### 1.1 启动 agent（核心）
|
||||
`POST {AM}/api/agent/agents/start`
|
||||
|
||||
**请求体(HM 发):**
|
||||
```json
|
||||
{
|
||||
"manager_deployment_id": "dep_b5fab27e9255", // HM 侧记录 id,回调/排查用
|
||||
"template_key": "architect", // 模板标识
|
||||
"agent_definition": "---\nname: architect\nmodel: opus\n...\n---\n<Agent_Prompt>...</Agent_Prompt>",
|
||||
"model": "opus", // 从模板 frontmatter 解析(可空)
|
||||
"env": { // 资源配置,注入 agent 的 .env(见 §2)
|
||||
"GIT_REPO_URL": "https://github.com/owner/repo",
|
||||
"GIT_TOKEN": "ghp_…",
|
||||
"VM_HOST": "1.2.3.4", "VM_USER": "deploy", "VM_PASSWORD": "…"
|
||||
},
|
||||
"callback_url": "https://code.xinghanlab.com/api/agent/callbacks/runtime-events"
|
||||
}
|
||||
```
|
||||
|
||||
**响应 data(AM 返回):**
|
||||
```json
|
||||
{ "runtime_id": "rt_xxx", "subdomain": "https://abc123.agents.example.com", "access_token": "…", "status": "running" }
|
||||
```
|
||||
- `runtime_id`:AM 侧实例 id(HM 存,用于后续 status/stop/delete)。HM 也接受 `agent_id`/`id`/`deployment_id` 作为别名。
|
||||
- `subdomain`:agent 对外**唯一可直连地址**(完整 URL 最佳)。HM 也接受 `address`/`url` 别名。
|
||||
- `access_token`:客户端连 agent 时出示的令牌(见 §3)。HM 也接受 `token` 别名。
|
||||
- `status`:`running`/`starting`/… HM 也接受 `runtime_status` 别名。
|
||||
|
||||
**AM 启动时必须做的:**
|
||||
1. 用 `agent_definition`(.md:frontmatter + 系统提示)作为该 agent 的**角色/行为定义**(等价 Claude Code subagent)。
|
||||
2. 把 `env` 注入 agent 的 `.env`/进程环境,**agent 只读 env 即知道有哪些资源**。
|
||||
3. 分配唯一子域名 + 生成 access_token,**agent 端自行校验该 token**(§3)。
|
||||
4. 该 agent 用模型时**调 HM 的 `/v1/*`**(带用户身份,HM 计费)——不要直连上游模型。
|
||||
|
||||
> ⚠️ **provisioning 是同步的**:HM 启动调用超时默认 60s(`AGENT_RUNTIME_START_TIMEOUT_SECONDS`),请在该时间内完成起容器+分配地址并返回。
|
||||
|
||||
### 1.2 取 agent 状态
|
||||
`GET {AM}/api/agent/agents/{runtime_id}`
|
||||
→ `data: { "status": "running" }`(HM 接受 `status`/`runtime_status`/`state`)。HM 据此判断 agent 是否存活/挂掉。
|
||||
|
||||
### 1.3 停止 agent
|
||||
`POST {AM}/api/agent/agents/{runtime_id}/stop` → 2xx 即可。
|
||||
|
||||
### 1.4 删除 agent
|
||||
`DELETE {AM}/api/agent/agents/{runtime_id}` → 2xx 即可。
|
||||
|
||||
---
|
||||
|
||||
## 2. env 命名约定（HM↔AM 必须一致,agent 模板按此读）
|
||||
|
||||
HM 把用户绑定的资源按**资源类型 + provider**解成固定 env 名(代码 `controller/agent_template_env.go`)。**AM 的 agent 模板按这些名字读 env**;用户在 HM 只填业务字段、看不到 env 名。
|
||||
|
||||
| 资源类型 | provider | 注入的 env(非密 + 密钥) |
|
||||
|---|---|---|
|
||||
| git | github / gitea / gitlab | `GIT_PROVIDER` `GIT_REPO_URL` `GIT_BRANCH` `GIT_API_BASE` · `GIT_TOKEN`(密) |
|
||||
| vm | (ssh) | `VM_HOST` `VM_PORT` `VM_USER` · `VM_PASSWORD` / `VM_SSH_KEY`(密) |
|
||||
| database | mysql | `MYSQL_HOST` `MYSQL_PORT` `MYSQL_DATABASE` `MYSQL_USER` · `MYSQL_PASSWORD`(密) |
|
||||
| database | pg(postgres) | `PG_HOST` `PG_PORT` `PG_DATABASE` `PG_USER` · `PG_PASSWORD`(密) |
|
||||
| database | redis | `REDIS_HOST` `REDIS_PORT` `REDIS_DB` · `REDIS_PASSWORD`(密) |
|
||||
| database | mongo | `MONGO_HOST` `MONGO_PORT` `MONGO_DATABASE` `MONGO_USER` · `MONGO_PASSWORD`(密) |
|
||||
| storage(blob) | azure blob | `BLOB_ACCOUNT` `BLOB_CONTAINER` · `BLOB_KEY`(密) |
|
||||
| storage(bucket) | s3/oss/minio | `BUCKET_ENDPOINT` `BUCKET_REGION` `BUCKET_NAME` · `BUCKET_ACCESS_KEY_ID` `BUCKET_SECRET_ACCESS_KEY`(密) |
|
||||
|
||||
- 缺失的可选字段不会出现在 env 里(agent 自行容错)。
|
||||
- 同类型资源 HM 限制只挂一个(避免 env 名冲突)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 客户端 ↔ agent 直连（AM 的 agent 端要定义）
|
||||
|
||||
- 客户端从 HM 拿到 `subdomain + access_token`,**直连 agent 子域名、SSE 双向通信**。HM 不在回路。
|
||||
- **agent 端必须校验 access_token**(请求头携带);token 错/缺则拒绝(防公网裸奔)。
|
||||
- **请由 AM 定义并回复 HM:** SSE 握手方式、token 放哪个请求头、消息/事件格式。HM 会把这段补进客户端文档 `heicode-desktop-client-api.md` §6。
|
||||
|
||||
---
|
||||
|
||||
## 4. 安全要求
|
||||
|
||||
- `env` 里**含明文密钥**(vm/db 密码、blob key、git token)。**AM 的启动接口必须 HTTPS 或私网**;HM 检测到明文密钥发往非 HTTPS AM 会打告警。
|
||||
- **agent 绝不能把 `.env`/密钥回显**到对话、日志、或提交进 git——由 AM 保证。
|
||||
- 生产密钥**只到 agent 运行环境**,不要再外传。
|
||||
|
||||
---
|
||||
|
||||
## 5. 回调(可选,lifecycle)
|
||||
|
||||
HM 提供 `POST /api/agent/callbacks/runtime-events`(HMAC 签名,`callback_url` 已随启动下发)。AM 可上报 agent 生命周期(started/stopped/unhealthy)。**当前 HM 主要用主动拉取(§1.2)判状态,回调非必须**;若 AM 走回调推送,与我们对齐事件格式即可。
|
||||
|
||||
---
|
||||
|
||||
## 6. 路径覆盖(联调期改路径无需改 HM 代码)
|
||||
|
||||
HM 这些路径都可用环境变量覆盖(默认值见 §1),AM 若用别的路径,运维改 env 即可:
|
||||
|
||||
| env | 默认 | 用途 |
|
||||
|---|---|---|
|
||||
| `AGENT_RUNTIME_BASE_URL` | — | AM 基址(必须配,HTTPS/私网) |
|
||||
| `AGENT_RUNTIME_SERVICE_TOKEN` | — | HM 调 AM 的 Bearer |
|
||||
| `AGENT_RUNTIME_AGENT_START_PATH` | `/api/agent/agents/start` | 启动 |
|
||||
| `AGENT_RUNTIME_AGENT_PATH` | `/api/agent/agents/{agent_id}` | 取状态(GET)/删除(DELETE) |
|
||||
| `AGENT_RUNTIME_AGENT_STOP_PATH` | `/api/agent/agents/{agent_id}/stop` | 停止 |
|
||||
| `AGENT_RUNTIME_START_TIMEOUT_SECONDS` | `60` | 启动超时 |
|
||||
|
||||
> 字段名若需调整(如 `subdomain`→别的),只改 `heicode/controller/agent_template_runtime.go` 中 `amStartTemplateAgent`/`amGetAgentStatus` 的解析键一处即可,其余 HM 代码不动。
|
||||
|
||||
---
|
||||
|
||||
## 7. 联调自检清单
|
||||
|
||||
- [ ] `POST /agents/start` 收到 `agent_definition`+`env`+`callback_url`,起 agent、注入 env、返回 `{runtime_id, subdomain, access_token, status}`。
|
||||
- [ ] agent 用模型打到 HM `/v1/*`(带用户身份),计费正常。
|
||||
- [ ] agent 子域名校验 access_token;非法连接被拒。
|
||||
- [ ] `GET /agents/{id}` 返回真实 status;`stop`/`delete` 生效。
|
||||
- [ ] agent 不泄露 env/密钥;启动接口 HTTPS/私网。
|
||||
- [ ] 把 §3 的 SSE 直连契约回给 HM 补进客户端文档。
|
||||
Reference in New Issue
Block a user