# 查看会话与用量 (/docs/developers/agent/monitor)



从会话、用户和花费判断嵌入是否正常工作，再打开具体会话检查发生了什么。本页适合已经产生真实宿主访问的服务智能体。



## 准备检查记录 [#prepare]

使用有权管理该智能体的组织账户，打开控制台「服务智能体 → 选择智能体 → 运营与管理」。下文使用当前中文控制台的控件名称。准备要检查的时间、终端用户 ID 和宿主接入方式。

先在宿主网页发送一条可识别的测试消息并收到回复，再查运营数据。控制台「试用调试」的记录不会进入客户运营统计，不能用它证明客户流量或花费已经入表。

## 查看概览 [#overview]

进入「概览」，选择 24 小时、7 天或 30 天。概览统计目前只能在控制台查看，没有对应的公开聚合 API。

| 检查内容               | 用它回答什么                                    |
| ------------------ | ----------------------------------------- |
| 会话、活跃终端用户、花费、每会话花费 | 访问量和每次服务的成本是否变化                           |
| 好评率                | 有评价的回复中，正面评价占比是多少                         |
| 首字延迟 P50、错误率       | 首次响应是否变慢，运行是否出现失败                         |
| 来源与版本分布            | 流量来自 Kit、iframe、Hosted、API 还是自动化；新版本是否被使用 |
| 需要关注、工具调用 Top 5    | 来源被拦、预算触顶或工具调用是否异常                        |

**预期结果：** 选择的时间范围内出现会话趋势和版本分布；没有对应样本的指标显示「—」，不是零。24 小时趋势按小时展示，其他范围按天展示。运行错误、来源拦截和工具计数按所选范围覆盖的 UTC 自然日汇总，首尾不足一天时也包含整日计数。

## 查找与回放会话 [#sessions]

<Tabs items="['控制台', 'API']">
  <Tab value="控制台">
    1. 进入「会话」，输入完整终端用户 ID，点击「筛选」；需要时从「来源」选择接入方式。
    2. 点击对应会话，检查回放头部的用户、来源、版本和创建时间。
    3. 对照消息与工具调用，确认测试消息及其回复；点击「关闭回放」收起。

    **预期结果：** 回放只读，不能发送消息。若要停止后续发言，点击「归档」并确认；归档后记录仍可查看，但不能继续发送消息。
  </Tab>

  <Tab value="API">
    在服务器设置 `PRAXIS_API_BASE`（API 源站）、`PRAXIS_API_KEY`（组织 API Key）和 `PRAXIS_AGENT`（公开 `agent_…` ID）。使用支持原生 `fetch` 的 Node.js。将下例保存为 `inspect-sessions.mjs`，执行 `node inspect-sessions.mjs customer_42`，替换为真实测试用户 ID。

    ```js
    import assert from 'node:assert/strict';

    const { PRAXIS_API_BASE, PRAXIS_API_KEY, PRAXIS_AGENT } = process.env;
    const [user, sessionId] = process.argv.slice(2);
    assert(PRAXIS_API_BASE && PRAXIS_API_KEY && PRAXIS_AGENT && user, 'Set environment variables and a user ID');
    assert(PRAXIS_AGENT.startsWith('agent_'), 'Use the public agent ID');
    const base = `${PRAXIS_API_BASE.replace(/\/$/, '')}/agent/v1`;
    async function readPages(path, filters) {
      const rows = [];
      let page;
      do {
        const query = new URLSearchParams(filters);
        if (page) query.set('page', page);
        const response = await fetch(`${base}${path}?${query}`, {
          headers: { Authorization: `Bearer ${PRAXIS_API_KEY}` },
        });
        if (!response.ok) throw new Error(`Read failed: HTTP ${response.status}`);
        const result = await response.json();
        rows.push(...result.data);
        page = result.next_page;
      } while (page);
      return rows;
    }
    const sessions = await readPages('/sessions', { agent_id: PRAXIS_AGENT, external_user_id: user });
    console.log(sessions.map(({ id, title, source, status }) => ({ id, title, source, status })));
    if (sessionId) {
      assert(sessions.some(row => row.id === sessionId), 'Choose a session from this user listing');
      const events = await readPages(`/sessions/${encodeURIComponent(sessionId)}/events`, { order: 'asc' });
      console.log(events);
    }
    ```

    首次运行列出会话。复制目标会话的 `id`，作为第二个参数再次运行，即读取该会话的全部事件。它使用 `GET /agent/v1/sessions` 和 `GET /agent/v1/sessions/{session_id}/events`；请求只读，API Key 不进入浏览器。

    **预期结果：** 列表中出现该用户的测试会话；事件按时间顺序返回，能找到测试消息与回复。脚本持续读取 `next_page`，不会把第一页当作完整回放。输出可能包含对话内容，请按你的数据访问规则保管。
  </Tab>
</Tabs>

## 检查用量与预算 [#usage]

进入「用量与预算」，查看本月花费、月度上限和触顶动作，再选择 7、30 或 90 天的每日花费。下方展示预算与限流、本月来源拆分及花费最高的终端用户 Top 20。本月按 UTC 自然月计算，界面金额为美元。

这些聚合报表与预算设置目前只能在控制台查看或配置。「修改上限」进入「配置 → 安全」；保存后返回核对。触顶动作为「停止新会话」时会拒绝新建会话；「只告警」不会拦截。「花费构成」尚未提供，不能从占位区域推断费用拆分。

## 验证与后续处理 [#verify]

用同一用户、会话和时间范围核对宿主消息、回放及来源。若版本与预期不符，先检查令牌签发时的版本；固定或回滚版本不改变已签发令牌。没有数据时先核对环境、组织和时间范围，不要反复创建测试会话来填充统计。

出现来源拦截或预算拒绝时，记录响应中的 `X-Request-Id`、时间、HTTP 状态和错误码；不要附上 API Key 或令牌。用户级处理见[管理终端用户](/docs/developers/agent/end-users)。

下一步：[嵌入限制与错误](/docs/developers/agent/embed/limits-and-errors) · [智能体 API](/docs/api/native/agent) · [Cookbook](/docs/cookbook)