Agent 监控看板

监控看板（/app/apps/{agent_id}/monitor）汇总单个 Agent 的会话量、Token 消耗、响应时间、工具调用、执行结果分布和用户干预情况。数据只统计该 Agent 已落库的会话与运行记录，是判断「要不要调提示词、加知识库或换模型」的依据。

需要拥有该 Agent 的访问权限：超级管理员可直接访问；私有 Agent 仅创建者可访问；团队 Agent 需要团队成员权限。无权访问返回 403，Agent 不存在返回 404。

打开监控页

前往应用（/app/apps），打开目标 Agent。
在 Agent 侧边栏选择监控（编排 / API / 日志 / 监控）。
页面标题为监控，副标题为「查看此 Agent 的使用统计和性能指标」。

图片待补充：Agent 监控看板

文件：/images/agent-monitor-overview.png。截图内容：Agent 监控页首屏，包含时间范围选择器和 6 张概览卡片。截图需裁剪到指标卡片区域，并用主题色框线标出时间范围选择器。未来图片的 alt 与 caption 均使用"Agent 监控看板"。

时间范围

页面顶部的时间范围选择器默认选中最近 7 天，只提供三档：

选项	取值	趋势粒度
最近 24 小时	`24h`	按小时，`24` 个点
最近 7 天	`7d`	按天，`7` 个点
最近 30 天	`30d`	按天，`30` 个点

点标签按站点时区对齐，显示为 HH:00（按小时）或 MM/DD（按天）。

监控页没有刷新按钮，也没有手动粒度控制。切换时间范围是唯一的刷新方式，切换时会并发触发概览、趋势和工具使用三个统计请求。

概览卡片

页面顶部有 6 张指标卡，数值大于等于 1K 显示为 K、大于等于 1M 显示为 M；耗时小于 1 秒显示毫秒，否则显示 2 位小数秒。

卡片	说明
对话数	区间内创建的会话总数
消息数	用户消息 + 助手消息 + 工具消息之和
Token 用量	总 Token，并分别展示 `↑` 提示词 Token 与 `↓` 补全 Token
平均响应时间	端到端平均耗时
活跃用户	区间内产生过会话的去重用户数
工具调用	助手消息中工具调用参数的数量之和

使用趋势

三张面积图共用同一时间范围：

图表	说明	纵轴
对话趋势	对话数和消息数随时间变化	计数
Token 用量	总 Token 消耗随时间变化	紧凑格式（`K`/`M`）
响应时间	平均响应时间随时间变化	秒

趋势数据由后端返回固定完整的点位网格，缺失的分桶补 0，因此曲线连续、不会因某段时间无数据而断开。

图片待补充：使用趋势

文件：/images/agent-monitor-trends.png。截图内容：监控页的对话趋势、Token 用量与响应时间三张面积图。截图需在趋势卡片区域内，并用主题色框线标出时间范围选择器以说明三图共用同一区间。未来图片的 alt 与 caption 均使用"使用趋势"。

工具调用分布

工具使用卡片用环形图展示该 Agent 的工具调用分布，按次数降序。图例显示工具的本地化名称和调用次数，悬浮提示为调用次数。

最多显示前 8 个工具，其余合并为其他工具并保留合计次数。
无工具调用时显示暂无工具使用数据。
工具名称按站点语言本地化；接口同时返回本地化 display_name 和原始 name。

工具统计不会枚举 MCP 服务器。统计请求刻意不触发外部 MCP 调用，因此 MCP 工具不会出现在分布里。

执行健康度

执行健康度环形图展示该 Agent 已结束运行的结果分布，悬浮提示显示次数与占比。

结果	含义
成功（`completed`）	运行正常执行完毕
失败（`failed`）	运行以失败终态结束
停止（`stopped`）	用户主动停止
中断（`interrupted`）	执行该运行的 Worker 丢失（崩溃、重启、被驱逐），运行未走到完成

成功率为成功 ÷ 已结束运行（卡片内提示为「成功 ÷ 已结束运行」）。卡片颜色随成功率变化：

成功率	颜色
`>= 95%`	绿色
`>= 80%` 且 `< 95%`	琥珀色
`< 80%`	红色

中断是终态，会让成功率下降，而不是「仍在进行中」。进行中的运行（queued、running、stopping、completing、waiting）不计入分母，页面会显示「另有 {count} 个进行中，未计入」。运行从未结束时，该卡片显示暂无运行记录。

首 Token 延迟

首 Token 延迟卡片给出 p50（中位数）、p95 和平均值，并用折线图按分桶展示 p95 与 p50 走势。未测到样本的分桶为 null，折线在该处断开不连线，卡片同时显示样本数。没有样本时显示暂无延迟样本。

首 Token 延迟反映「用户等待第一个字出现」的体感，与平均响应时间（端到端总耗时）是两个不同指标：延迟高通常与模型首字速度、上下文长度或排队有关；总耗时高还可能是工具调用多。

用户干预

用户干预柱状图统计用户对运行的三类介入行为（只渲染非零项）：

标签	含义
中途引导（`steer`）	生成过程中插入补充指令
主动停止（`stopped`）	用户手动停止生成
追问（`follow_up`）	针对上一轮结果继续追问

卡片同时给出干预率 = interventions.total / health.total（已结束运行数，保留 2 位小数），提示为基于 {runs} 次已结束运行。

干预总量为 0 时显示空状态；若柱状图有数据但没有任何已结束运行，则不显示干预率。干预率高意味着提示词、工具描述或知识库召回不够明确，用户需要反复纠偏。

数据口径与已知限制

统计端点存在与文档声明不完全一致的口径，排障时需要注意：

概览和工具使用对 24h/7d/30d 之外的时间范围一律按 all（全部）处理；趋势端点对非 24h/7d 一律按 30d 处理。UI 只暴露三档，通常不会触发。
统计失败时前端静默保留上一次或空数据，不显示错误态。图表长时间为空但会话明显存在时，先刷新页面再检查后端。
卡片数量少于 6 张或图表区域空白，通常是统计数据尚未返回；加载过程中卡片与图表位置显示骨架屏。

不可用（Roadmap）：成本/费用拆分、首 Token 之外的请求级响应时间百分位、统计导出（CSV/PDF）与定时报表；运维层面也没有 Prometheus /metrics 端点。

API 端点

监控页数据来自三个只读端点，都需要已登录 JWT 并通过 Agent 访问校验：

GET /api/v1/agents/{agent_id}/stats?period=7d
GET /api/v1/agents/{agent_id}/stats/trends?period=7d
GET /api/v1/agents/{agent_id}/stats/tool-usage?period=7d

period 支持 24h、7d、30d、all（趋势仅 24h/7d/30d，概览与工具使用默认 7d）。

stats 一次返回全部区块：

{
  "code": 0,
  "data": {
    "period": "30d",
    "overview": {
      "total_conversations": 156,
      "total_messages": 1234,
      "user_messages": 620,
      "assistant_messages": 610,
      "tool_messages": 4,
      "active_users": 23
    },
    "tokens": {
      "prompt_tokens": 250000,
      "completion_tokens": 206789,
      "total_tokens": 456789
    },
    "performance": {
      "avg_response_time_ms": 2300,
      "first_token_ms": { "p50": 1200, "p95": 9000, "avg": 2500, "samples": 480 }
    },
    "tools": { "tool_call_count": 512 },
    "health": {
      "completed": 90, "failed": 6, "stopped": 4, "interrupted": 3,
      "unrecognised": 0, "in_flight": 2, "total": 103, "success_rate": 0.8738
    },
    "interventions": { "steer": 12, "stop": 3, "follow_up": 5, "total": 20 }
  },
  "msg": "success"
}