heicode-mananger/docs/integration/AgentManager普通sub联调整改要求.md

Agent Manager 普通 sub 联调整改要求

更新时间：2026-05-28 发给：Agent Manager / Agent Runtime 负责人 范围：Heicode Manager 普通 sub 敏捷模式联调，不包含蜂群模式完整 task graph 的额外能力。

1. 当前结论

Agent Manager 新版文档 HEICODE_API_INTEGRATION(5).md 已经补充了 Runtime 主动 callback、HMAC、artifact、timeline、SK snapshot 等内容，方向基本对齐 Heicode Manager。

按 2026-05-28 生产实测，Manager 与 Agent Manager 的普通 sub 核心通讯链路已经跑通，但还不能认为“真实开发执行结果”完整闭环。当前结论是：

1. Agent Manager 当前联调统一使用 IP http://20.212.121.126；域名 https://agent-manager.taijiagent.com 后续解析和证书就绪后再切换，不作为当前联调阻塞项。
2. Manager 生产已切到 /api/swarms 创建入口，并验证能拿到 runtime_swarm_id=swm_*。
3. Agent Manager 自动 callback 已能写入 Manager events/timeline，Manager 1.4.19 开始会把 callback 反写到 deployment 快照。
4. 当前仍缺真实产物和真实用量：Agent Manager status 接口返回 tokens_used=0、artifacts=[]，并出现整体 completed 但 agent 仍 running 的状态不一致。
5. 文档写了 callback 重试和死信，但同时又写“发送失败只 warning”，需要明确当前真实实现。

Heicode Manager 侧已确认：

• POST https://code.xinghanlab.com/api/agent/callbacks/swarm-events 生产路由在线。
• callback 支持 HMAC 和旧 token 兼容；当前生产为了先跑通自动 callback，已配置 HMAC fallback。
• GET https://code.xinghanlab.com/api/agent/callbacks/swarm-events/schema 已由 Manager 提供，用于联调前核对事件类型和必填字段。
• Manager 可接收 deployment.status_changed、phase.changed、timeline.updated、agent.started/completed/crashed，并在 1.4.19 反写 deployment 详情状态。

2. Agent Manager 必须整改的 P0

优先级	事项	当前问题	要求
P0	固定联调地址	当前阶段约定先走 IP，后续再切域名	文档和配置先统一使用 http://20.212.121.126；域名切换另行确认
P0	创建普通 sub deployment	/api/swarms 已能创建并返回 swm_*	保持幂等和字段稳定，后续域名切换不能破坏
P0	deployment detail	Manager 已能记录 callback；Agent Manager status 仍有 completed 与 agent running 不一致	返回真实 phase、agent 状态、失败原因和更新时间
P0	deployment stop	/api/agent/deployments/{deployment_id}/stop 已可用	停止后 Runtime 真实停止，并回调 stopped 事件
P0	callback 主动推送	已验证 status/phase/timeline/agent/budget callback 能进入 Manager	继续补 artifact、SK、approval 的真实运行数据
P0	usage 回传	当前 budget callback 中 token/cost/runtime 多为 0	通过 callback 或事件接口回传真实 token、成本、运行时长、资源使用

3. 推荐接口契约

3.1 健康检查

GET /api/agent/health

要求：

• 不要求业务认证。
• 返回 200。
• 响应中包含 success=true 和 data.status=healthy。

3.2 创建普通 sub 运行

普通 sub 当前生产联调使用 Agent Manager /api/agent/deployments，蜂群 /api/swarms 另见 AgentManager蜂群Runtime接口实现要求.md。

POST /api/agent/deployments
Authorization: Bearer <HEICODE_SERVICE_TOKEN>
Content-Type: application/json
X-User-ID: <user_id>
X-Binding-Scope: <binding_scope>
X-Correlation-ID: <correlation_id>
X-Idempotency-Key: <idempotency_key>

请求体示例：

{
  "orchestration_plan": {
    "intent_id": "task_123",
    "template_hint": "heicode-task",
    "objective": "完成本轮普通 sub 敏捷任务",
    "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-28",
      "stage": "development",
      "checkpoint": "draft_created",
      "acceptance_criteria": [
        "Runtime 接收创建请求",
        "Runtime 主动回调 phase/timeline/artifact",
        "Manager 页面和接口可查到回调数据",
        "不出现明文密钥"
      ],
      "next_action": "continue",
      "requires_user_approval": false
    },
    "agents": [
      {
        "role": "backend"
      },
      {
        "role": "frontend"
      },
      {
        "role": "reviewer"
      }
    ],
    "resource_grants": []
  },
  "callback": {
    "url": "https://code.xinghanlab.com/api/agent/callbacks/swarm-events",
    "signing_secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/agent-callback-signing-key",
    "subscribed_events": [
      "deployment.status_changed",
      "phase.changed",
      "timeline.updated",
      "agent.started",
      "agent.completed",
      "sk_tool.called",
      "sk_tool.completed",
      "sk_tool.failed",
      "approval.requested",
      "budget.alert",
      "artifact.created"
    ]
  }
}

成功响应必须包含：

{
  "deployment_id": "dep_runtime_123",
  "status": "initializing",
  "agent_instances": [
    {
      "agent_instance_id": "agi_backend_001",
      "role": "backend",
      "status": "pending"
    }
  ],
  "created_at": "2026-05-28T07:30:00Z",
  "estimated_ready_at": "2026-05-28T07:32:00Z"
}

要求：

1. deployment_id 必须可用于 /api/agent/deployments/{deployment_id}、/api/agent/deployments/{deployment_id}/stop。
2. 同一个 X-Idempotency-Key 重复请求必须返回同一个运行，不应重复创建。
3. 请求缺少 orchestration_plan、callback.url、sub_mode、user_context 时必须返回 4xx。

3.3 查询普通 sub deployment

GET /api/agent/deployments/{deployment_id}
Authorization: Bearer <HEICODE_SERVICE_TOKEN>

响应示例：

{
  "deployment_id": "dep_runtime_123",
  "status": "running",
  "phase": "development",
  "agent_instances": [
    {
      "agent_instance_id": "agi_backend_001",
      "role": "backend",
      "status": "running",
      "current_task": "实现接口"
    }
  ],
  "created_at": "2026-05-28T07:30:00Z",
  "updated_at": "2026-05-28T07:31:00Z"
}

3.4 停止普通 sub deployment

POST /api/agent/deployments/{deployment_id}/stop
Authorization: Bearer <HEICODE_SERVICE_TOKEN>
Content-Type: application/json

请求体：

{
  "reason": "Heicode Manager requested stop",
  "manager_deployment_id": "dep_manager_123"
}

响应示例：

{
  "deployment_id": "dep_runtime_123",
  "status": "stopped",
  "stopped_at": "2026-05-28T07:40:00Z"
}

要求：

• 停止后不再继续执行任务。
• 停止后可以继续查询状态。
• 停止成功后建议 callback 一条 deployment.status_changed，状态为 stopped。

4. Callback 要求

Manager 生产 callback 地址：

https://code.xinghanlab.com/api/agent/callbacks/swarm-events

4.1 认证方式

优先使用 HMAC：

X-Agent-Event-Id: evt_xxx
X-Agent-Timestamp: <unix_ms>
X-Agent-Signature: sha256=<hex>
X-Correlation-ID: <correlation_id>
Content-Type: application/json

签名规则：

signature_payload = timestamp + "." + event_id + "." + raw_body
signature = HMAC_SHA256(callback_signing_secret, signature_payload)

过渡期可使用旧 token：

X-Agent-Service-Token: <HEICODE_SERVICE_TOKEN>

不要把真实 token 写入文档、日志或 artifact。

4.2 必须回调的事件

普通 sub 最少需要以下事件：

事件	目的	最低要求
deployment.status_changed	整体运行状态	status、stage、checkpoint
phase.changed	普通 sub 阶段推进	stage、checkpoint、progress_pct
timeline.updated	客户端可展示反馈	title、summary、stage、checkpoint
agent.started	Agent 开始工作	agent_role、task_id
sk_tool.called	工具调用开始	tool_name、脱敏参数摘要
sk_tool.completed	工具调用成功	tool_name、耗时、摘要、可选 artifact 引用
sk_tool.failed	工具调用失败	tool_name、脱敏错误
artifact.created	中间/最终产物	artifact_id、artifact_type、title、summary、uri
approval.requested	高危操作审批	operation、resource_type、risk_level、reason
budget.alert	预算告警/用量	usage / cost 摘要

4.3 Callback body 示例

{
  "event_id": "evt_phase_001",
  "event_type": "phase.changed",
  "deployment_id": "dep_manager_123",
  "agent_instance_id": "agi_backend_001",
  "occurred_at": "2026-05-28T07:35:00Z",
  "correlation_id": "corr_123",
  "source": "agent-manager",
  "payload": {
    "stage": "development",
    "checkpoint": "agent_running",
    "progress_pct": 35,
    "summary": "backend agent 已开始实现接口"
  }
}

artifact 示例：

{
  "event_id": "evt_artifact_001",
  "event_type": "artifact.created",
  "deployment_id": "dep_manager_123",
  "agent_instance_id": "agi_backend_001",
  "occurred_at": "2026-05-28T07:38:00Z",
  "correlation_id": "corr_123",
  "source": "agent-manager",
  "payload": {
    "artifact_id": "art_backend_patch_001",
    "artifact_type": "code_patch",
    "title": "Backend API patch",
    "summary": "新增普通 sub 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
    }
  }
}

4.4 明文密钥禁止项

以下字段不能出现在 callback、artifact metadata、timeline、日志中：

• password
• token
• secret
• private_key
• connection_string
• access_key
• 明文数据库连接串
• 明文模型网关 key
• 明文 Git token

长期凭据只能传：

azkv://<vault>/secrets/<name>

5. Usage / Cost 回传要求

Agent Manager 文档当前缺少真实 usage 字段。普通 sub 后续要支持模型费用、运行费用和审计归属，Runtime 必须回传至少以下字段。

可通过 budget.alert、timeline.updated 或专门的 usage.updated 事件回传。如果新增 usage.updated，需要提前和 Manager 对齐 schema。

{
  "event_id": "evt_usage_001",
  "event_type": "budget.alert",
  "deployment_id": "dep_manager_123",
  "agent_instance_id": "agi_backend_001",
  "occurred_at": "2026-05-28T07:39:00Z",
  "correlation_id": "corr_123",
  "source": "agent-manager",
  "payload": {
    "model_id": "model_xxx",
    "model_tokens": 12000,
    "prompt_tokens": 8000,
    "completion_tokens": 4000,
    "model_cost_usd": 0.23,
    "runtime_seconds": 180,
    "cpu_core_seconds": 36,
    "memory_mb_seconds": 92160,
    "billing_source": "newapi",
    "budget": {
      "max_tokens": 120000,
      "max_cost_usd": 8,
      "consumed_usd": 0.23,
      "remaining_usd": 7.77
    }
  }
}

字段要求：

字段	必需	说明
model_id	是	本次 Agent 调用的模型
model_tokens	是	总 token
prompt_tokens	建议	输入 token
completion_tokens	建议	输出 token
model_cost_usd	是	可归属的模型成本
runtime_seconds	是	Agent 实际运行秒数
cpu_core_seconds	建议	集群资源成本核算
memory_mb_seconds	建议	集群资源成本核算
billing_source	是	newapi / manager_wallet / manager_subscription / 其他约定

注意：budget.max_cost_usd 是预算上限，不是已扣费金额。不能把预算当真实账单。

6. Approval Decision 接收要求

Manager 端已有 approval、credential lease、approve/reject 和 Runtime decision adapter。Agent Manager 需要提供接收审批结果的接口。

推荐接口：

POST /api/agent/deployments/{deployment_id}/approvals/{approval_id}
Authorization: Bearer <HEICODE_SERVICE_TOKEN>
Content-Type: application/json

请求体：

{
  "approval_id": "apr_123",
  "decision": "approved",
  "manager_deployment_id": "dep_manager_123",
  "runtime_deployment_id": "dep_runtime_123",
  "operation": "git.write",
  "resource_type": "git",
  "resource_id": "repo_main",
  "risk_level": "high",
  "requires_credential": true,
  "credential_ref": "lease://agent/cred_123",
  "lease_id": "lease_123",
  "lease_expires_at": 1770000000000,
  "decided_by": "user_123",
  "reason": "允许本次写入",
  "decided_at": 1770000000000
}

要求：

• approved 后 Runtime 继续对应高危动作。
• rejected 后 Runtime 停止该动作并回调 timeline.updated 或 sk_tool.failed。
• 不要求 Manager 回传明文密钥，只能使用 credential_ref 或 lease://...。

7. Callback 重试策略需要说清楚

Agent Manager 文档当前有两种说法：

1. 当前发送失败只记录 warning，不阻塞任务执行。
2. Runtime 推送失败时指数退避，最多重试 12 小时，超过进入死信队列。

请明确当前真实实现是哪一种：

能力	当前是否已实现	需要说明
失败重试	是/否	重试次数、间隔、最大时长
死信队列	是/否	存储位置、人工重放方式
幂等重放	是/否	是否复用原 event_id
失败告警	是/否	是否有日志、监控或告警

如果当前只 warning，不重试，请在文档中写成“当前未实现重试/死信，后续增强”，不要把建议方案写成已完成。

8. 联调验收步骤

Agent Manager 改完后，按下面步骤验收。

步骤	操作	通过标准
1	GET /api/agent/health	返回 healthy
2	POST /api/agent/deployments 创建普通 sub run	返回 deployment_id、status
3	重复同一个 X-Idempotency-Key 创建	不重复创建，返回同一个 ID
4	GET /api/agent/deployments/{deployment_id}	返回真实状态和 agents
5	Runtime 主动 callback phase.changed	Manager callback 返回 success
6	Runtime 主动 callback timeline.updated	Manager timeline 可查到
7	Runtime 主动 callback artifact.created	Manager artifacts 可查到
8	Runtime 主动 callback sk_tool.completed	Manager SK/timeline 可查到
9	Runtime 主动 callback usage	Manager 能看到 usage 摘要或 callback event
10	Runtime 主动 callback approval.requested	Manager pending approval 生成
11	Manager approve/reject	Agent Manager 收到 decision
12	POST /api/agent/deployments/{deployment_id}/stop	Runtime 停止，状态变为 stopped
13	检查日志和 artifact metadata	不包含明文密钥

9. 当前实测记录

2026-05-28 已测：

接口	结果	说明
GET http://20.212.121.126/api/agent/health	200	Agent Manager IP 健康检查正常
GET https://agent-manager.taijiagent.com/api/agent/health	暂不作为当前验收项	当前约定先走 IP，域名后续再切换
POST https://code.xinghanlab.com/api/agent/callbacks/swarm-events 无认证	业务返回 CALLBACK_UNAUTHORIZED	Manager callback 路由在线
POST https://code.xinghanlab.com/api/agent/callbacks/swarm-events 带旧 token 但空 body	业务返回 CALLBACK_INVALID	认证通过，进入事件校验
GET https://code.xinghanlab.com/api/agent/callbacks/swarm-events/schema	404	Manager schema GET 生产未通，Manager 侧需复核
POST http://20.212.121.126/api/agent/deployments	200	普通 sub Runtime deployment 创建可用

9.1 2026-05-28 追加联调记录

本次按当前约定使用 Agent Manager IP http://20.212.121.126。

客户端完整用户态链路说明：

• 已尝试通过生产 Manager /api/user/login 获取用户 session，但手头用户名组合未登录成功。
• 因此本次没有宣称“桌面客户端登录后走 Manager 用户态创建 deployment”完整通过。
• 本次完成的是服务到服务联调：Manager/客户端等价 payload -> Agent Manager IP，以及 Agent Manager callback 协议 -> Heicode Manager callback 接收端。

Agent Manager /api/agent/deployments 服务到服务链路：

步骤	结果	证据
GET /api/agent/health	通过	返回 success=true、status=healthy
POST /api/agent/deployments	通过	返回 deployment_id=dep_dbafd1ac37c3，状态 pending
GET /api/agent/deployments/{deployment_id}	通过	能查到 user_id、binding_scope、sub_mode=agile、callback_configured=true
GET /api/agent/deployments/{deployment_id}/events	部分通过	只看到 deployment.accepted，未看到 phase.changed/timeline.updated/artifact.created/sk_tool.*
GET /api/agent/deployments/{deployment_id}/logs	部分通过	返回系统日志 Pod ... has no logs yet
GET /api/agent/deployments/{deployment_id}/metrics	通过但疑似占位	返回 CPU/内存/网络指标，但值看起来是固定模拟值，需要 Runtime 说明来源
POST /api/agent/deployments/{deployment_id}/stop	通过	dep_dbafd1ac37c3 停止成功，返回 status=stopped

长等待测试：

项	结果
测试 deployment	dep_cd170573cf47
等待时间	约 2 分钟
最终状态	已清理停止
事件结果	只有 deployment.accepted 和 deployment.stopped
未观察到	phase.changed、timeline.updated、artifact.created、agent.started/completed、sk_tool.called/completed
结论	Agent Manager 文档声称的“Runtime 主动推送 status/phase/timeline/agent/tool/artifact 事件”在本次实测中没有跑出来，需要 Agent Manager 继续排查

Heicode Manager callback 接收端：

步骤	结果	证据
无认证 POST callback	通过预期	返回 CALLBACK_UNAUTHORIZED
带旧 token 但缺事件字段	通过预期	返回 CALLBACK_INVALID，说明认证通过并进入业务校验
带旧 token 发送合法 timeline.updated	通过	返回 success=true、inserted=true
重复发送同一 event_id	通过	返回 deduplicated=true、inserted=false

本次合法 callback 测试事件：

event_id=evt_agent_manager_ip_smoke_1779954828884
event_type=timeline.updated
runtime_deployment_id=dep_cd170573cf47
source=agent-manager-ip-smoke

结论：

1. Heicode Manager callback 接收端可用，旧 token 认证和幂等可用。
2. Agent Manager IP 的 /api/agent/deployments 创建、查询、停止可用。
3. Agent Manager 当前没有在实测中产生普通 sub 所需的 phase/timeline/artifact/SK 主动回调。
4. 因没有可用生产 Manager 用户 session，本次没有完成“客户端登录态 -> Manager 用户态 deployment -> Runtime”的完整端到端测试。

9.2 2026-05-28 测试用户客户端模拟链路

测试用户：

email: zsbgnw@gmail.com
username: chenchen
user_id: 22
group: default

说明：密码只用于本次登录测试，不写入本文档。

本次已完成“客户端模拟 -> Heicode Manager 生产用户态接口 -> Agent Manager IP Runtime”链路。

步骤	结果	证据
登录生产 Manager	通过	/api/user/login 返回 success=true，用户 id=22
查询用户信息	通过	/api/user/self 返回用户 chenchen、group=default
查询 Runtime 健康	通过	/api/agent/runtime/health 返回 enabled=true、configured=true、status=healthy、create_path=/api/agent/deployments、远端为 Agent Manager IP
客户端模拟创建 deployment	通过	POST /api/agent/user/deployments 返回 Manager deployment dep_1ba14ccfb558
Manager -> Agent Manager create	通过	Manager detail 写回 runtime_deployment_id=dep_3335e54e9bdf，runtime_state=pending
Manager 用户态 events	通过	出现 deployment.accepted、runtime.sync.started、runtime.sync.accepted
Manager 用户态 logs	通过	出现 control-plane 日志和 runtime sync 日志，均为 redacted
Manager 用户态 metrics	部分通过	返回 platform_estimated=true，说明是 Manager 估算/占位，不是 Runtime 真实资源指标
Manager 用户态 artifacts	未产出	返回空列表
Manager 用户态 timeline	部分通过	能返回 deployment/events，但 callbacks/artifacts 为空
Manager stop	通过	POST /api/agent/user/deployments/dep_1ba14ccfb558/stop 返回 status=stopped
Runtime stop 结果	通过	直查 Agent Manager dep_3335e54e9bdf，状态为 stopped

本次真实 ID：

manager_deployment_id=dep_1ba14ccfb558
runtime_deployment_id=dep_3335e54e9bdf
correlation_id=manager-client-sim-1779955103016
runtime_agent_instance_id=agi_ed399bf8cc70

Agent Manager 侧直查 dep_3335e54e9bdf：

接口	结果
GET /api/agent/deployments/dep_3335e54e9bdf	200，状态 stopped，user_id=22
GET /api/agent/deployments/dep_3335e54e9bdf/events	200，仅有 deployment.accepted、deployment.stopped
GET /api/agent/deployments/dep_3335e54e9bdf/logs	200，仅有 Pod ... has no logs yet
GET /api/agent/deployments/dep_3335e54e9bdf/metrics	200，返回 CPU/内存/网络固定值

本次客户端模拟链路结论：

1. 测试用户登录、Manager 用户态接口、Manager Runtime bridge、Agent Manager create、Agent Manager stop 均已真实跑通。
2. Manager 能拿到 Runtime 健康状态，并能把用户态 deployment 同步到 Agent Manager IP。
3. Manager stop 能传递到 Agent Manager，Runtime deployment 已停止。
4. Agent Manager 仍未真实产生普通 sub 必需的阶段、timeline、artifact、SK 工具和 usage 回调。
5. 当前 metrics/logs 更像 Runtime 占位数据：日志显示 Pod ... has no logs yet，metrics 为固定 CPU/内存/网络值。
6. 本次 Manager 请求中的 agile context 没有在 Runtime 详情中表现为有效阶段推进，Runtime 事件里 agile_context 为空字段，需要双方继续核对字段解析和透传。

10. 完成定义

只有满足以下条件，才能认为普通 sub 敏捷 Runtime 联调完成：

1. Manager 能创建 Runtime run，并保存 Runtime 返回的 deployment_id。
2. Runtime 能主动回调 Manager，且 callback 通过认证、幂等、脱敏和 schema 校验。
3. Manager 的 artifacts / timeline / sk-snapshots / events 能看到 Runtime 回传数据。
4. Manager 发起 stop 后 Runtime 真实停止。
5. Runtime 高危审批能暂停，Manager approve/reject 后 Runtime 收到 decision 并继续或停止。
6. Runtime usage / cost 能按 user、deployment、task、agent role、model 归属。
7. 整个流程不传递、不记录明文长期密钥。