老板要求「在 ai 网关里做智能体 agent,新的一个菜单」,一期仅管理员、成熟后下发。 完整设计(27 条决策,4 轮评审)见 docs/agents-dev-plan.md。 架构(路线 A):界面与权限在网关,执行在 QwenPaw(独立 profile ai-gateway)。 网关当门面(鉴权/计量/灰度/审计),引擎提供工具能力(文件/命令/浏览器)。 Step -1 技术验证(实测,全部改变或确认了设计): - 请求级指定模型【无效】:传 model 被忽略,turn_usage 回 provider_id=opencode、 model_name=deepseek-v4.1-flash;AgentRequest 无 model 字段。模型是 profile 级。 → 甲案:所有智能体共用 ai-gateway 一个 profile ⇒ 共用同一模型,配置页模型栏只读。 - role:"system"【被接受且生效】:塞入「只用英文回答」后模型真的用英文 → params.system_suffix 走注入 system 消息。 - SSE 事件谱已录制 → tests/fixtures/sse-tool-flow.sse + docs/qwenpaw-agent-api-sse.md 后端: - app/agents.py:AgentStore(data/agents.yaml,600/原子写/mtime 热载)+ 严格校验 (slug 三重查重:模型 id/别名/QwenPaw profile;params 4 键白名单;suffix 限长 2000; max_agents=5 软上限,归档不计入;restore 可恢复) - app/adapters/qwenpaw_engine.py:OpenAI 形状 ↔ AgentScope Agent API + SSE 翻译器 (text 累积、delta:false 快照忽略、plugin_call→轨迹、call_id 配对 output、turn_usage→计量) - app/agents_routes.py:GET/POST/PUT/DELETE /agents、/restore、/chat(SSE)、/stop、 /runs、/sessions、/test + 新增 GET /auth/me(灰度通道,features.agents 后端权威); 权限唯一入口 can_use_agent();防自指(引擎模型不得指向 agent/*) - app/history.py:会话类别扩展支持 agent_<slug>(复用现有存储) - data/agents.yaml(配置,入库);data/agent_runs.json(运行时,gitignore) 前端: - views/Agents.vue(列表 + 对话/配置/运行记录)+ lib/agents.ts(SSE 解析) - 菜单核心组第 5 位 + 图标 bot;router meta.admin 双层守卫;i18n 中英对称 871/871 上线实测:真实对话跑通 —— 让智能体 read_file 读 /etc/hostname,前端正确显示 「执行了 1 步」+ 工具参数、正文、计量(wjd · 47196 tokens · 缓存 13696)、终态; 引擎调用经 wangjinding 过网关(计量闭环)。 测试 209 → 217 全过(新增 8 条,含用真实夹具验证 SSE 翻译器);ci_check 全绿。
321 lines
13 KiB
Python
321 lines
13 KiB
Python
"""QwenPaw 引擎适配器(第三十八轮 · 路线 A)。
|
||
|
||
把网关的对话请求转成 QwenPaw 的 **AgentScope Agent API** 形状,再把它的 SSE 事件流
|
||
翻译回网关前端认识的形式。
|
||
|
||
协议事实全部来自实测 —— 见 `docs/qwenpaw-agent-api-sse.md` 与
|
||
`tests/fixtures/sse-tool-flow.sse`。要点:
|
||
|
||
- `POST {base}/api/console/chat`,body `{input: [Message], session_id, stream: true}`
|
||
- 头 `X-Agent-Id: <profile>` 选择 QwenPaw 侧用哪个智能体 profile
|
||
- 回 SSE(前缀固定 `data: `,**没有 event: 行**)
|
||
- 事件:`text` / `plugin_call` / `plugin_call_output` / `data` / `message` / `response` / `turn_usage`
|
||
- `role: "system"` 的输入消息**被接受且生效**(实测)→ `system_suffix` 走这条
|
||
- `model` 字段**被忽略**(实测)→ 模型是 profile 级,不在请求里指定
|
||
|
||
网关对前端的输出形状(自定义、简单):
|
||
|
||
```jsonc
|
||
{"type": "text", "text": "增量"} // 正文增量
|
||
{"type": "step", "id": "...", "name": "read_file", "args": {...}, "status": "running"}
|
||
{"type": "step", "id": "...", "status": "done", "ms": 320, "output": "..."}
|
||
{"type": "usage", "prompt": 1, "completion": 2, "cached": 0, "model": "wjd", "context_ratio": 0.02}
|
||
{"type": "done", "status": "completed"}
|
||
{"type": "error", "message": "..."}
|
||
```
|
||
|
||
这样前端不必理解 AgentScope 的事件细节。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
import json
|
||
import logging
|
||
from typing import Any, AsyncIterator
|
||
|
||
import httpx
|
||
|
||
log = logging.getLogger("api-gateway.agents")
|
||
|
||
#: 单轮对话的超时(秒)。引擎可能跑很久(多步工具),给足。
|
||
DEFAULT_TIMEOUT = 300.0
|
||
|
||
#: 引擎不可达时的兜底文案。
|
||
ENGINE_DOWN_MSG = "引擎不可达(QwenPaw 未运行或未就绪)"
|
||
|
||
|
||
class EngineError(Exception):
|
||
"""引擎层错误(映射为 502)。"""
|
||
|
||
|
||
# ── 请求构造 ──────────────────────────────────────────────────────────
|
||
def build_input(messages: list[dict[str, Any]], system_suffix: str = "") -> list[dict[str, Any]]:
|
||
"""把网关侧的消息列表转成 AgentScope 的 `input`。
|
||
|
||
- 网关历史里的 role/文本 → `{role, content:[{type:"text", text}]}`
|
||
- `system_suffix` → 在最前面插一条 **system 消息**(实测被接受且生效)
|
||
- `system` 角色的历史消息也照传(引擎接受)
|
||
"""
|
||
out: list[dict[str, Any]] = []
|
||
if system_suffix:
|
||
out.append({
|
||
"role": "system",
|
||
"content": [{"type": "text", "text": system_suffix}],
|
||
})
|
||
for m in messages:
|
||
role = (m.get("role") or "user").lower()
|
||
if role not in ("user", "assistant", "system"):
|
||
role = "user"
|
||
content = m.get("content")
|
||
# content 允许是字符串或 [{type:text,text}] 形状
|
||
if isinstance(content, str):
|
||
parts = [{"type": "text", "text": content}]
|
||
elif isinstance(content, list):
|
||
parts = []
|
||
for c in content:
|
||
if isinstance(c, str):
|
||
parts.append({"type": "text", "text": c})
|
||
elif isinstance(c, dict) and c.get("type") == "text":
|
||
parts.append({"type": "text", "text": str(c.get("text") or "")})
|
||
# 图片等一期不支持,静默跳过(计划「一期不做图片/附件」)
|
||
else:
|
||
parts = [{"type": "text", "text": str(content or "")}]
|
||
out.append({"role": role, "content": parts})
|
||
return out
|
||
|
||
|
||
def build_body(messages: list[dict[str, Any]], session_id: str,
|
||
system_suffix: str = "") -> dict[str, Any]:
|
||
return {
|
||
"input": build_input(messages, system_suffix),
|
||
"session_id": session_id,
|
||
"stream": True,
|
||
}
|
||
|
||
|
||
# ── SSE 解析与翻译 ────────────────────────────────────────────────────
|
||
def parse_sse_line(line: str) -> dict[str, Any] | None:
|
||
"""把一行 SSE 解析成事件 dict;非数据行返回 None。"""
|
||
if not line.startswith("data:"):
|
||
return None
|
||
payload = line[5:].strip()
|
||
if not payload or payload == "[DONE]":
|
||
return None
|
||
try:
|
||
obj = json.loads(payload)
|
||
except json.JSONDecodeError:
|
||
log.debug("引擎 SSE 非 JSON 行(忽略):%.120s", payload)
|
||
return None
|
||
return obj if isinstance(obj, dict) else None
|
||
|
||
|
||
class StreamTranslator:
|
||
"""把引擎的事件序列翻译成网关前端的消息序列(有状态)。
|
||
|
||
状态:
|
||
- `_text_buf`: 已累积的正文(用来在结束时兜底补全)
|
||
- `_steps`: call_id → 步骤信息(配对 plugin_call / plugin_call_output)
|
||
"""
|
||
|
||
def __init__(self) -> None:
|
||
self.text_parts: list[str] = []
|
||
self.steps: dict[str, dict[str, Any]] = {}
|
||
self.usage: dict[str, Any] | None = None
|
||
self.final_status: str = "completed"
|
||
self._step_started: dict[str, float] = {}
|
||
|
||
# ── 单事件 → 若干前端消息 ──
|
||
def feed(self, ev: dict[str, Any], now: float | None = None) -> list[dict[str, Any]]:
|
||
import time
|
||
now = now or time.time()
|
||
t = ev.get("type")
|
||
out: list[dict[str, Any]] = []
|
||
|
||
if t == "text":
|
||
# delta:true 是增量;delta:false 是整段快照 —— 忽略,否则会重复
|
||
if ev.get("delta") is False:
|
||
return out
|
||
piece = ev.get("text")
|
||
if isinstance(piece, str) and piece:
|
||
self.text_parts.append(piece)
|
||
out.append({"type": "text", "text": piece})
|
||
return out
|
||
|
||
if t == "plugin_call":
|
||
info = _extract_call(ev, key="arguments")
|
||
if info:
|
||
cid = info.get("call_id") or info.get("name") or "?"
|
||
self.steps[cid] = info
|
||
self._step_started[cid] = now
|
||
out.append({
|
||
"type": "step", "id": cid, "name": info.get("name"),
|
||
"args": info.get("args"), "status": "running",
|
||
})
|
||
return out
|
||
|
||
if t == "plugin_call_output":
|
||
info = _extract_call(ev, key="output")
|
||
if info:
|
||
cid = info.get("call_id") or info.get("name") or "?"
|
||
started = self._step_started.pop(cid, None)
|
||
ms = int((now - started) * 1000) if started else None
|
||
if cid in self.steps:
|
||
self.steps[cid]["status"] = "done"
|
||
msg: dict[str, Any] = {"type": "step", "id": cid, "status": "done"}
|
||
if ms is not None:
|
||
msg["ms"] = ms
|
||
if info.get("output") is not None:
|
||
msg["output"] = _clip(info["output"])
|
||
out.append(msg)
|
||
return out
|
||
|
||
if t == "turn_usage":
|
||
u = ev.get("usage") or {}
|
||
self.usage = u
|
||
ctx = ev.get("context_usage") or {}
|
||
out.append({
|
||
"type": "usage",
|
||
"prompt": int(u.get("prompt_tokens") or 0),
|
||
"completion": int(u.get("completion_tokens") or 0),
|
||
"cached": int(u.get("cache_read_tokens") or 0),
|
||
"model": u.get("model_name") or "",
|
||
"provider": u.get("provider_id") or "",
|
||
"context_ratio": ctx.get("context_usage_ratio"),
|
||
})
|
||
return out
|
||
|
||
if t == "response":
|
||
st = ev.get("status")
|
||
if st:
|
||
self.final_status = st
|
||
if st in ("failed", "cancelled"):
|
||
out.append({"type": "done", "status": st})
|
||
return out
|
||
|
||
# data / message 等其余事件:忽略(分片由快照覆盖)
|
||
return out
|
||
|
||
def finish(self) -> list[dict[str, Any]]:
|
||
"""流结束时收尾。"""
|
||
out: list[dict[str, Any]] = []
|
||
if self.final_status not in ("failed", "cancelled"):
|
||
out.append({"type": "done", "status": self.final_status})
|
||
elif self.final_status == "cancelled":
|
||
out.append({"type": "done", "status": "cancelled"})
|
||
return out
|
||
|
||
@property
|
||
def text(self) -> str:
|
||
return "".join(self.text_parts)
|
||
|
||
|
||
def _extract_call(ev: dict[str, Any], *, key: str) -> dict[str, Any] | None:
|
||
"""从 plugin_call / plugin_call_output 里取 {call_id, name, args|output}。
|
||
|
||
结构(实测):`content[0].data = {call_id, name, arguments|output}`
|
||
注意 `arguments` 是 **JSON 字符串**,要二次解析。
|
||
"""
|
||
content = ev.get("content")
|
||
if not isinstance(content, list):
|
||
return None
|
||
for c in content:
|
||
if not isinstance(c, dict):
|
||
continue
|
||
data = c.get("data")
|
||
if not isinstance(data, dict) or key not in data:
|
||
continue
|
||
info: dict[str, Any] = {
|
||
"call_id": data.get("call_id"),
|
||
"name": data.get("name"),
|
||
}
|
||
raw = data.get(key)
|
||
if key == "arguments":
|
||
info["args"] = _maybe_json(raw)
|
||
else:
|
||
info["output"] = raw
|
||
return info
|
||
return None
|
||
|
||
|
||
def _maybe_json(v: Any) -> Any:
|
||
"""`arguments` 是 JSON 字符串 → 解析成对象;解析不了就原样返回字符串。"""
|
||
if not isinstance(v, str):
|
||
return v
|
||
try:
|
||
return json.loads(v)
|
||
except (json.JSONDecodeError, TypeError):
|
||
return v
|
||
|
||
|
||
def _clip(v: Any, limit: int = 4000) -> Any:
|
||
"""工具输出可能很长 —— 转发给前端前裁一刀(避免 SSE 帧过大)。"""
|
||
if isinstance(v, str) and len(v) > limit:
|
||
return v[:limit] + "…(已截断)"
|
||
return v
|
||
|
||
|
||
# ── 调用引擎 ──────────────────────────────────────────────────────────
|
||
async def stream_chat(base_url: str, agent_id: str, messages: list[dict[str, Any]],
|
||
session_id: str, *, system_suffix: str = "",
|
||
timeout: float = DEFAULT_TIMEOUT) -> AsyncIterator[dict[str, Any]]:
|
||
"""打引擎并产出"已翻译"的前端消息。
|
||
|
||
用法:
|
||
async for msg in stream_chat(...): # msg 就是 {type: text|step|usage|done|error}
|
||
yield sse(msg)
|
||
"""
|
||
url = base_url.rstrip("/") + "/api/console/chat"
|
||
body = build_body(messages, session_id, system_suffix)
|
||
tr = StreamTranslator()
|
||
headers = {
|
||
"Content-Type": "application/json",
|
||
"Accept": "text/event-stream",
|
||
"X-Agent-Id": agent_id,
|
||
}
|
||
try:
|
||
async with httpx.AsyncClient(timeout=httpx.Timeout(timeout, connect=10.0)) as client:
|
||
async with client.stream("POST", url, headers=headers, json=body) as resp:
|
||
if resp.status_code >= 400:
|
||
raw = (await resp.aread()).decode("utf-8", "replace")[:300]
|
||
yield {"type": "error",
|
||
"message": f"引擎返回 {resp.status_code}:{raw}"}
|
||
return
|
||
async for line in resp.aiter_lines():
|
||
ev = parse_sse_line(line)
|
||
if ev is None:
|
||
continue
|
||
for msg in tr.feed(ev):
|
||
yield msg
|
||
for msg in tr.finish():
|
||
yield msg
|
||
except httpx.ConnectError:
|
||
yield {"type": "error", "message": ENGINE_DOWN_MSG}
|
||
except httpx.ReadTimeout:
|
||
yield {"type": "error", "message": "引擎响应超时(本轮未完成)"}
|
||
except httpx.RemoteProtocolError:
|
||
# 引擎中途断开 —— 保留已收到的内容(前端自己累积着),只提示中断
|
||
for msg in tr.finish():
|
||
pass
|
||
yield {"type": "error", "message": "引擎连接中断,本轮未完成"}
|
||
except Exception as exc: # noqa: BLE001 —— 兜底,别让流把异常抛给客户端
|
||
log.exception("引擎调用失败")
|
||
yield {"type": "error", "message": f"引擎调用失败:{exc}"}
|
||
|
||
|
||
async def check_engine(base_url: str, *, timeout: float = 5.0) -> tuple[bool, str]:
|
||
"""探活:引擎是否可达。返回 (ok, 说明)。
|
||
|
||
不引 `/api/healthz`(那是 QwenPaw 的)—— 用最轻的请求确认端口活着。
|
||
"""
|
||
url = base_url.rstrip("/") + "/api/healthz"
|
||
try:
|
||
async with httpx.AsyncClient(timeout=timeout) as client:
|
||
r = await client.get(url)
|
||
if r.status_code < 500:
|
||
return True, "就绪"
|
||
return False, f"引擎异常(HTTP {r.status_code})"
|
||
except httpx.ConnectError:
|
||
return False, ENGINE_DOWN_MSG
|
||
except Exception as exc: # noqa: BLE001
|
||
return False, f"引擎不可达:{exc}"
|