Agentswarm/CLIENT_GUIDE.md

客户端接入指南（Client Guide）

本文说明客户端如何与 Agent Swarm 运行时交互。系统总览见 README.md；接口契约见 docs/integration/runtime-contract.md；事件结构见 docs/integration/event-schema.md。

架构说明：生产链路中，终端用户通过 Heicode Manager / 桌面客户端 提交需求，由 Manager 调用本 Swarm 运行时（见 heicode-swarm-deferred 裁定）。「客户端」在本文指调用 Swarm 运行时 REST API 的一方（Manager、联调脚本或开发者）。Swarm 不在对话回路，通过带签名回调回报状态。

---

1. 两个交互面

1. REST API（客户端 → Swarm）：创建部署、查询状态/任务/日志/事件/指标、审批、停止。
2. 回调事件流（Swarm → 客户端/Manager）：生命周期事件经带 HMAC 签名的回调推送（见 §6）。

WebSocket /ws/{agent_id} 仅供 Agent 执行单元 接入，不是客户端接口。

---

2. 鉴权

• 客户端调用带 Authorization: Bearer <token>，Swarm 校验 AGENT_RUNTIME_SERVICE_TOKEN（兼容 AGNET_RUNTIME_SERVICE_TOKEN）。
• 未配置令牌时为非安全开发模式（不校验，仅本地）。
• 常用请求头：X-Correlation-ID（贯穿追踪）、X-Idempotency-Key（创建幂等）。
• 响应信封：成功 { "success": true, "data": {...} }；失败 { "success": false, "error": {code,message,request_id} }。

---

3. 生命周期：创建 → 观察 → （审批）→ 停止

3.1 创建部署

POST /api/swarms（别名 /api/agent/swarm/deployments、/api/agnet/deployments）

curl -s -X POST http://<host>:8000/api/swarms \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Correlation-ID: corr-123" \
  -H "X-Idempotency-Key: idem-123" \
  -d '{
        "mode": "swarm",
        "requirement": { "objective": "实现 add(a,b) 并补充测试与说明" },
        "callback": { "url": "https://your-manager/api/agent/callbacks/runtime-events", "subscribed_events": [] },
        "metadata": { "manager_deployment_id": "dep-1" }
      }'

必填：requirement.objective（或 orchestration_plan.objective）、callback.url、metadata.manager_deployment_id。

响应 data：deployment_id、runtime_deployment_id、swarm_id(=workflow_id)、manager_deployment_id、mode、status、created。请保存 deployment_id 用于后续查询。

3.2 观察

接口	用途
GET /api/swarms/{deployment_id}	部署状态概要
GET /api/swarms/{deployment_id}/workflow	工作流/阶段视图（phases、agents、tokens、tools、artifacts、summary）
GET /api/swarms/{deployment_id}/tasks	任务 DAG（task_id、agent_role、status、depends_on…）
GET /api/swarms/{deployment_id}/logs（/events）	事件流，分页 ?limit=&cursor=（断线后用 cursor 回补）
GET /api/swarms/{deployment_id}/metrics	任务/Agent/预算指标
GET /api/swarms/{deployment_id}/diagnostics	失败、回调尝试、审批诊断

状态机：waiting_approval → running → (blocked ⇄ running) → completed | failed | stopped。

3.3 审批（高危操作）

当部署进入 waiting_approval 并推送 approval.requested 时，客户端经 Manager 审批后回执：

curl -s -X POST http://<host>:8000/api/swarms/<deployment_id>/approvals/<approval_id> \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "decision": "approved" }'   # 或 "rejected"，可带 credential_ref / reason

3.4 停止

curl -s -X POST http://<host>:8000/api/swarms/<deployment_id>/stop \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "reason": "client requested stop" }'

---

4. 健康检查

• GET / → {status, service}；GET /health → 含 Redis 与连接数；GET /metrics → Prometheus。

---

5. 工作流（去中心化蜂群 —— 唯一行为，无开关）

本仓即蜂群运行时，模式选择（single/chain/sub/swarm）在仓外；没有「启用 swarm」开关。下述流程无条件生效（cutover 已完成）：编排器播种单一目标种子任务 → Agent 感知共享池自选（信息素 τ + 能力/负载/预算）→ 经 task_proposal 自底向上自主分解（#7）→ 经 task_bid/yield/takeover 竞争/接管（#8）→ 同伴交叉评审（≥2 评审者，#11）→ 收敛（产出 termination_reason，#12），最后 master_agent.synthesize 汇总。已删除：Master/planner 自顶向下分解兜底、单 critic 主控评审环及其 ENABLE_PLANNER_FALLBACK / ENABLE_REVIEW_LOOP 等开关。

• MAX_REVIEW_CYCLES（默认 2）：交叉评审/重做的轮次预算（保留）。
• MAX_AGENTS_PER_USER（默认 10）：每用户并发连接的 Agent 上限（见 security-boundary §6）。
• 仅剩的能力开关：ENABLE_QUALITY_EVAL + HEICODE_SANDBOX_ISOLATED（代码沙箱评分，见 security-boundary §8.1）、ENABLE_SUBTASK_HANDOFF（agent 侧子任务移交）。
• 模型走 HM 模型网关（OpenAI 兼容 /v1）：OPENAI_API_KEY = HM 为该用户现签的 per-user sk-（NewAPI token），OPENAI_API_BASE = HM /v1，OPENAI_MODEL 为所选模型。由 Agent 平台在拉起 agent 时注入其进程 env（server→server，不入 create 请求 / 回调 / 日志）。模型调用扣发起用户 user.Quota、按 token 名归集计量；详见 usage-billing-schema.md §2。

---

6. 回调事件流（Swarm → 客户端/Manager）

Swarm 向 callback.url POST 事件，带 HMAC 签名（客户端须验签）：

• 头：X-Agent-Timestamp(ms)、X-Agent-Signature、X-Agent-Event-Id、X-Correlation-ID（+ X-Agnet- 兼容别名）。
• 签名：sha256=hex(HMAC_SHA256(secret, "{timestamp}.{event_id}.{raw_body}"))，secret = AGENT_CALLBACK_SIGNING_SECRET，时间容差 300s。
• 幂等：按 X-Agent-Event-Id → body event_id → idempotency_key 去重。
• 事件类型与必填字段：见 event-schema.md（deployment.status_changed、task.*、handoff.*、approval.requested、artifact.created、timeline.updated、budget.alert…）。

客户端可只消费 REST（轮询 /workflow+/logs?cursor=），或同时接收回调。

---

7. 本地联调（无需密钥）

# 1) 编排器（内存存储；蜂群流程无条件生效，无需开关）
set "REDIS_FAKE=1" & set "MAX_REVIEW_CYCLES=2"
python -m uvicorn orchestrator.main:app --host 0.0.0.0 --port 8000
# 2) 无密钥桩 Agent（联调用）
set "ORCHESTRATOR_URL=ws://localhost:8000" & set "AGENT_ID=stub-1" & set "AGENT_CAPABILITIES=python,code_generation,testing,pytest,technical-writing,general"
python scripts/stub_agent.py
# 3) 用 §3.1 的 curl 提交需求，再用 §3.2 观察

---

8. 说明与边界

• 桌面/前端 UI：当前桌面客户端为单 Agent A2A 直连模型；蜂群图 / 协作时间线的前端事件 API 尚未冻结（见 frontend-event-api.md）。
• 不得在请求/回调/日志中出现明文密钥；凭据一律 secret_ref（azkv://）。见 security-boundary.md。
• 计费主线：Agent 模型调用走 HM /v1，用 HM 为该用户现签的 per-user sk- 作 OPENAI_API_KEY，扣发起用户 user.Quota；NewAPI 是账本、按请求计量，Swarm 不是账本、仅上报用量（随模型请求带 X-Agent-* 归因头）。归因主轴 = user.id/channelId，不引入 tenant。见 usage-billing-schema.md §1/§2。