Files

T

Songhaoz666andClaude Opus 4.8 54cb327348 Agent Swarm v6：基准 v2.1、主控 Agent、实质性对等回复、客户端指南

- 基准标准 v2.1：SwarmMetrics（15 字段）、τ/η/P_decision/reward 公式、对称 G_E,c（修正 C_base=1.0 退化）、Σλ=1.0 校验；新增基线对比与运行记录 schema；指标覆盖缺口分析；参考系数暂留为元数据（待量化）。
- 主控 Agent 实体（分解 / 评审决策 / 汇总）；事件契约修正（timeline.title、budget.threshold_pct、handoff 角色、task.released）+ 契约校验脚本。
- 实质性 LLM 对等回复（含降级回退）；集成契约（runtime / event / usage / audit / frontend / capability / security）；CLIENT_GUIDE 客户端指南；CI 工作流；治理与交付文档。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-09 16:21:18 +08:00

6.4 KiB

Raw Blame History

客户端接入指南（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. 两个交互面

REST API（客户端 → Swarm）：创建部署、查询状态/任务/日志/事件/指标、审批、停止。
回调事件流（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. 启用完整工作流

默认仅执行 Manager 提供的编排；要启用「分解 → 评审/重做 → 汇总」主控工作流，运行 Swarm 时设置（默认关闭）：

ENABLE_PLANNER_FALLBACK=1：无 Manager 分工时由主控 Agent 自动分解。
ENABLE_REVIEW_LOOP=1 / MAX_REVIEW_CYCLES=2：主控评审与重做循环 + 结果汇总。
模型走 OpenAI 兼容网关（OPENAI_API_KEY/OPENAI_API_BASE/OPENAI_MODEL，经 secret_ref 注入）。

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 "ENABLE_PLANNER_FALLBACK=1" & set "ENABLE_REVIEW_LOOP=1"
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。
计费在 NewAPI（模型网关）侧按请求计量，Swarm 仅上报用量；见 usage-billing-schema.md。

6.4 KiB Raw Blame History Unescape Escape