Files
AgentLab/backend/app/api/runs.py
T
ThearchyHelios 964eeaa829 AgentLab:可视化 Agent 编排实验台
在画布上拖拽编排 agent 工作流,并实时看着它执行。

后端 FastAPI + LangGraph:把画布 JSON 编译成 StateGraph,15 种节点
(模型/Agent/多Agent、工具/沙箱、分支/循环/子图、记忆/检索/整形、
人工介入/结构校验)。选 LangGraph 是因为可视化编排真正难的是暂停、
恢复和回放,而 checkpointer + interrupt() 正好把这几件事做在了底层。

前端 React + React Flow:节点元数据驱动属性面板与连接桩,运行时
节点高亮、边流动画、卡片内流式 token 全部由同一份事件流驱动。

关键实现:
- Agent 内工具审批用 @task 缓存模型调用,interrupt 重放时不重复计费
- 沙箱保持只读根文件系统,代码经 exec+base64 写入(put_archive 会被
  只读容器拒绝),断网、非 root、内存/CPU/超时限额
- 检索为向量与 BM25 混合,本地哈希 embedding 零配置可用
- 分支条件走 AST 白名单求值器;HTTP 工具逐 IP 拦截内网与元数据地址
- Mock provider 让无 API Key 也能跑通完整链路

7 个内置模板全部冒烟通过,含真实模型端到端验证。
2026-09-13 17:27:00 +08:00

353 lines
12 KiB
Python

from __future__ import annotations
import asyncio
import contextlib
from typing import Any
from fastapi import APIRouter, Depends, HTTPException, Query, WebSocket, WebSocketDisconnect
from pydantic import BaseModel, Field
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
from app.core.bus import bus
from app.db.base import SessionLocal, get_session
from app.db.models import Approval, Run, RunEvent, Workflow
from app.engine.runner import run_manager
router = APIRouter(prefix="/api/runs", tags=["runs"])
class StartRunIn(BaseModel):
workflow_id: str | None = None
graph: dict[str, Any] | None = None # 直接跑一张未保存的图(画布上的"试运行")
input: dict[str, Any] = Field(default_factory=dict)
memory_scope: str = "default"
collection: str = "default"
class RunOut(BaseModel):
id: str
workflow_id: str | None
workflow_name: str
status: str
input: dict[str, Any]
output: dict[str, Any]
error: str | None
usage: dict[str, Any]
created_at: Any = None
started_at: Any = None
finished_at: Any = None
model_config = {"from_attributes": True}
@router.post("", response_model=RunOut, status_code=201)
async def start_run(payload: StartRunIn, session: AsyncSession = Depends(get_session)) -> Run:
graph = payload.graph
name = "临时图"
if payload.workflow_id:
workflow = await session.get(Workflow, payload.workflow_id)
if not workflow:
raise HTTPException(404, "工作流不存在")
graph = graph or workflow.graph
name = workflow.name
if not graph:
raise HTTPException(400, "需要提供 workflow_id 或 graph")
try:
return await run_manager.start(
graph=graph,
input_payload=payload.input,
workflow_id=payload.workflow_id,
workflow_name=name,
memory_scope=payload.memory_scope,
collection=payload.collection,
)
except ValueError as e:
raise HTTPException(400, str(e)) from e
@router.get("", response_model=list[RunOut])
async def list_runs(
workflow_id: str | None = None,
status: str | None = None,
limit: int = Query(default=50, le=200),
session: AsyncSession = Depends(get_session),
) -> list[Run]:
stmt = select(Run).order_by(Run.created_at.desc()).limit(limit)
if workflow_id:
stmt = stmt.where(Run.workflow_id == workflow_id)
if status:
stmt = stmt.where(Run.status == status)
return list((await session.execute(stmt)).scalars())
@router.get("/{run_id}", response_model=RunOut)
async def get_run(run_id: str, session: AsyncSession = Depends(get_session)) -> Run:
run = await session.get(Run, run_id)
if not run:
raise HTTPException(404, "运行记录不存在")
return run
@router.get("/{run_id}/events")
async def get_events(
run_id: str,
after: int = 0,
session: AsyncSession = Depends(get_session),
) -> list[dict[str, Any]]:
"""拉历史事件。刷新页面后重建时间线用这个,再接 WebSocket 续上实时流。"""
rows = await session.execute(
select(RunEvent)
.where(RunEvent.run_id == run_id, RunEvent.seq > after)
.order_by(RunEvent.seq)
)
return [
{
"id": e.id,
"run_id": e.run_id,
"seq": e.seq,
"type": e.type,
"node_id": e.node_id,
"ts": e.ts,
"data": e.data,
}
for e in rows.scalars()
]
@router.post("/{run_id}/cancel")
async def cancel_run(run_id: str) -> dict[str, Any]:
stopped = await run_manager.cancel(run_id)
if not stopped:
raise HTTPException(409, "该运行当前不在执行中")
return {"ok": True}
class ResumeIn(BaseModel):
response: Any = None
approval_id: str | None = None
@router.post("/{run_id}/resume", response_model=RunOut)
async def resume_run(run_id: str, payload: ResumeIn) -> Run:
try:
return await run_manager.resume(run_id, payload.response)
except KeyError as e:
raise HTTPException(404, str(e)) from e
except ValueError as e:
raise HTTPException(409, str(e)) from e
@router.get("/{run_id}/state")
async def get_state(run_id: str) -> dict[str, Any]:
"""读取 checkpoint 里的当前状态。调试中断中的 run 时很有用。"""
from app.engine.compiler import compile_graph
from app.engine.context import RunContext
from app.engine.schema import GraphSpec
async with SessionLocal() as session:
run = await session.get(Run, run_id)
if not run:
raise HTTPException(404, "运行记录不存在")
spec = GraphSpec.model_validate(run.graph)
app = compile_graph(spec, RunContext(run_id=run_id, thread_id=run_id, spec=spec)).compile(
checkpointer=run_manager.checkpointer
)
snapshot = await app.aget_state({"configurable": {"thread_id": run_id}})
values = dict(snapshot.values or {})
values.pop("messages", None) # 消息对象不好直接序列化,前端也用不到
return {
"values": _jsonable(values),
"next": list(snapshot.next or ()),
"interrupts": [
{"id": getattr(i, "id", None), "value": _jsonable(getattr(i, "value", None))}
for i in (snapshot.interrupts or ())
],
}
@router.get("/{run_id}/history")
async def get_history(run_id: str, limit: int = 50) -> list[dict[str, Any]]:
"""checkpoint 历史 —— 可以看到每一步之后的状态快照,用来做时间旅行式调试。"""
from app.engine.compiler import compile_graph
from app.engine.context import RunContext
from app.engine.schema import GraphSpec
async with SessionLocal() as session:
run = await session.get(Run, run_id)
if not run:
raise HTTPException(404, "运行记录不存在")
spec = GraphSpec.model_validate(run.graph)
app = compile_graph(spec, RunContext(run_id=run_id, thread_id=run_id, spec=spec)).compile(
checkpointer=run_manager.checkpointer
)
out: list[dict[str, Any]] = []
async for snapshot in app.aget_state_history({"configurable": {"thread_id": run_id}}):
values = dict(snapshot.values or {})
values.pop("messages", None)
out.append(
{
"checkpoint_id": snapshot.config.get("configurable", {}).get("checkpoint_id"),
"next": list(snapshot.next or ()),
"created_at": snapshot.created_at,
"trail": _jsonable(values.get("trail") or [])[-1:],
"nodes_done": list((values.get("nodes") or {}).keys()),
}
)
if len(out) >= limit:
break
return out
@router.delete("/{run_id}", status_code=204)
async def delete_run(run_id: str, session: AsyncSession = Depends(get_session)) -> None:
run = await session.get(Run, run_id)
if not run:
raise HTTPException(404, "运行记录不存在")
await session.delete(run)
await session.commit()
# --------------------------------------------------------------------------
# 实时事件流
# --------------------------------------------------------------------------
@router.websocket("/{run_id}/stream")
async def stream_run(websocket: WebSocket, run_id: str) -> None:
"""把一次运行的事件推给前端。
先补历史再接实时,所以中途打开页面、或者刷新之后,时间线都是完整的。
"""
await websocket.accept()
after = int(websocket.query_params.get("after", 0) or 0)
try:
async with SessionLocal() as session:
rows = await session.execute(
select(RunEvent)
.where(RunEvent.run_id == run_id, RunEvent.seq > after)
.order_by(RunEvent.seq)
)
for event in rows.scalars():
await websocket.send_json(
{
"seq": event.seq,
"type": event.type,
"node_id": event.node_id,
"ts": event.ts,
"data": event.data,
"replay": True,
}
)
run = await session.get(Run, run_id)
# 已经结束的 run 没有后续事件,补完历史就关掉
if run and run.status in ("succeeded", "failed", "cancelled"):
await websocket.send_json({"type": "stream.end", "status": run.status})
await websocket.close()
return
stream = bus.subscribe(run_id)
pump = asyncio.create_task(_pump(websocket, stream))
try:
# 客户端断开时读操作会抛异常,用它来结束这条连接
while True:
await websocket.receive_text()
except WebSocketDisconnect:
pass
finally:
pump.cancel()
with contextlib.suppress(asyncio.CancelledError):
await pump
except WebSocketDisconnect:
return
except Exception: # noqa: BLE001
with contextlib.suppress(Exception):
await websocket.close()
async def _pump(websocket: WebSocket, stream: Any) -> None:
try:
async for event in stream:
await websocket.send_json(event.to_wire())
except (WebSocketDisconnect, RuntimeError):
return
# --------------------------------------------------------------------------
# 审批
# --------------------------------------------------------------------------
approvals_router = APIRouter(prefix="/api/approvals", tags=["approvals"])
class ApprovalOut(BaseModel):
id: str
run_id: str
node_id: str
mode: str
title: str
payload: dict[str, Any]
status: str
response: dict[str, Any]
created_at: Any = None
model_config = {"from_attributes": True}
@approvals_router.get("", response_model=list[ApprovalOut])
async def list_approvals(
status: str = "pending",
run_id: str | None = None,
session: AsyncSession = Depends(get_session),
) -> list[Approval]:
stmt = select(Approval).order_by(Approval.created_at.desc()).limit(100)
if status != "all":
stmt = stmt.where(Approval.status == status)
if run_id:
stmt = stmt.where(Approval.run_id == run_id)
return list((await session.execute(stmt)).scalars())
class DecideIn(BaseModel):
approved: bool = True
note: str = ""
value: Any = None
args: dict[str, Any] | None = None
@approvals_router.post("/{approval_id}/decide", response_model=RunOut)
async def decide(
approval_id: str, payload: DecideIn, session: AsyncSession = Depends(get_session)
) -> Run:
approval = await session.get(Approval, approval_id)
if not approval:
raise HTTPException(404, "审批请求不存在")
if approval.status != "pending":
raise HTTPException(409, "该请求已经处理过了")
response: dict[str, Any] = {"approved": payload.approved, "note": payload.note}
if payload.value is not None:
response["value"] = payload.value
if payload.args is not None:
response["args"] = payload.args
try:
return await run_manager.resume(approval.run_id, response)
except ValueError as e:
raise HTTPException(409, str(e)) from e
def _jsonable(value: Any) -> Any:
if isinstance(value, dict):
return {str(k): _jsonable(v) for k, v in value.items()}
if isinstance(value, (list, tuple)):
return [_jsonable(v) for v in value]
if isinstance(value, (str, int, float, bool)) or value is None:
return value
return str(value)