failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/zh/agenteye/python-sdk.mdx

@@ -0,0 +1,433 @@
+---
+title: "Python SDK"
+description: "精确了解您的 AI 智能体在生产环境中的行为：每次智能体运行、工具调用、模型请求、钩子以及人工干预。"
+---
+
+
+精确了解您的 AI 智能体在生产环境中的行为：每次智能体运行、工具调用、模型请求、钩子以及人工干预。Failproof AI 可观测性 Python SDK 从您的智能体代码内部记录完整的执行轨迹，让您可以调试、审计和评估发生的一切。当您希望 Failproof AI 可观测性监控您的智能体时，请使用此 SDK。
+
+在底层，SDK 将结构化事件写入本地 JSONL 文件，采集器守护进程会自动将这些文件上传到平台。您无需自行管理这些文件。
+
+> **提示：** 刚接触 Failproof AI 可观测性？本页是完整的 SDK 事件参考文档。
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/VWxukZc5k7s?autoplay=1&mute=1&loop=1&playlist=VWxukZc5k7s&rel=0&playsinline=1" title="Watch: Agent Tracing by Failproof AI (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+---
+
+## 安装
+
+SDK 以私有 wheel 包的形式分发给客户，而非通过公共包索引。您的入职培训将涵盖如何获取、安装和固定版本——如需访问权限，请联系您的 Failproof AI 联系人。
+
+安装完成后，确认您已成功安装：
+
+```bash
+python -c "import agenteye; print(agenteye.__version__)"
+```
+
+希望让编码智能体完成整个集成工作？[Python SDK Agent Skill](/zh/agenteye/python-sdk-skill) 了解安装路径，能够规划插桩点、编写代码并验证事件是否正确落地。
+
+---
+
+## 快速开始
+
+```python
+import agenteye
+
+agenteye.configure(environment="production")
+
+agenteye.event.agent_start(session_id="run-001", agent_id="planner", goal="answer user query")
+
+agenteye.event.tool_use(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",
+    tool_call_id="toolu_01",
+    input={"query": "latest AI research"},
+)
+
+agenteye.event.tool_result(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",
+    tool_call_id="toolu_01",
+    output={"results": ["..."]},
+)
+
+agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success")
+```
+
+### 为真实调用添加插桩
+
+在实践中，您需要对现有的智能体代码进行包装。在模型调用前后分别发送 `model_request` 和 `model_response` 事件，使这两个事件覆盖真实请求的时间范围，以便 Failproof AI 可观测性将它们配对：
+
+```python
+import anthropic
+import agenteye
+
+agenteye.configure(environment="production")
+client = anthropic.Anthropic()
+
+messages = [{"role": "user", "content": "Summarise today's incidents."}]
+
+agenteye.event.model_request(
+    session_id="run-001",
+    agent_id="planner",
+    model="claude-sonnet-4-6",
+    messages=messages,
+)
+
+reply = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=512,
+    messages=messages,
+)
+
+agenteye.event.model_response(
+    session_id="run-001",
+    agent_id="planner",
+    model=reply.model,
+    stop_reason=reply.stop_reason,
+    input_tokens=reply.usage.input_tokens,
+    output_tokens=reply.usage.output_tokens,
+    content=[block.model_dump() for block in reply.content],
+)
+```
+
+工具调用同样使用 `tool_use` 和 `tool_result` 进行包装，并在这一对事件中复用同一个 `tool_call_id`。
+
+以下是这些事件到达仪表板后的样式，按类型用颜色区分，并支持按环境、智能体和会话进行筛选：
+
+![实时事件流，按事件类型颜色编码，可按环境、智能体和会话筛选](/agenteye/images/events-stream.png)
+
+---
+
+## configure()
+
+```python
+agenteye.configure(
+    base_dir=None,           # Path | str | None。默认值：$AGENTEYE_HOME 或 ~/.agenteye
+    flush_interval=0.5,      # float，两次刷新之间的秒数
+    environment=None,        # str | None。部署环境标签
+)
+```
+
+在任何 `event.*` 调用之前调用一次。可以省略；默认值开箱即用。所有参数均为仅限关键字参数；请按上面所示按名称传递。
+
+当 `base_dir` 为 `None`（默认值）时，SDK 会读取 `$AGENTEYE_HOME`（如果已设置），否则回退到 `~/.agenteye`。这与采集器自身的解析逻辑一致，因此单个 `AGENTEYE_HOME` 环境变量可同时为 SDK 和采集器配置共享的事件缓冲目录。
+
+---
+
+## 环境
+
+为每个事件标记一个部署环境（`production`、`staging`、`qa`、`canary` 等）。设置一次，SDK 会自动将其附加到每个事件上。
+
+**方式一：通过 `configure()`：**
+
+```python
+agenteye.configure(environment="production")
+```
+
+**方式二：通过环境变量：**
+
+```bash
+export AGENTEYE_ENVIRONMENT=production
+```
+
+**优先级：** `configure(environment=...)` 优先于环境变量。若两者均未设置，默认为 `"dev"`。
+
+环境值会作为一级过滤器显示在仪表板中，并存储在服务器上以支持快速查询。
+
+> **警告：** 环境值不得包含字面逗号 `,`。仪表板过滤器在传输时使用逗号分隔的多选格式（`?environment=prod,staging`），因此名为 `prod,blue` 的环境会被拆分为两个值。包含逗号的环境值的事件将在摄取时被拒绝。
+
+---
+
+## 数据与隐私
+
+SDK 仅记录您显式传递的字段。提示词、消息、工具输入输出以及模型内容，只有在您将其传递给 `event.*` 调用时才会被捕获。不会从您的进程中读取任何内容，也不会有隐式捕获。您未设置的任何字段将从事件中完全省略，不会写入磁盘。
+
+因此，数据脱敏是您的选择和责任。如果提示词或工具负载中包含您不希望存储的 PII 或密钥，请在将其传递给事件方法之前进行清除或掩码处理。
+
+---
+
+## 事件参考
+
+大多数事件以共享关联 ID 的开始/结束对形式出现：`tool_use` 和 `tool_result` 共享一个 `tool_call_id`，`hook_triggered` 和 `hook_completed` 共享一个 `hook_id`，`human_wait` 和 `human_input` 共享一个 `input_id`。发送开始事件，执行工作，然后使用相同 ID 发送结束事件。Failproof AI 可观测性会自动匹配这一对事件并为您计算 `duration_ms`，因此您无需自行传递 `duration_ms`。
+
+![会话的 git 风格执行图及其事件时间线（由配对事件重建），以及工具/模型/钩子分解面板](/agenteye/images/session-detail.png)
+
+所有事件方法均需要以下两个字段：
+
+| 字段 | 类型 | 描述 |
+|---|---|---|
+| `session_id` | `str` | 标识顶级智能体运行 |
+| `agent_id` | `str` | 标识会话中发送该事件的智能体 |
+
+所有方法还接受任意 `**kwargs` 用于自定义元数据（参见[自定义字段](#custom-fields)）。
+
+---
+
+### `event.agent_start()`
+
+当智能体开始工作时发送。
+
+```python
+agenteye.event.agent_start(
+    session_id="run-001",
+    agent_id="planner",
+    goal="answer user query",   # str | None
+    parent_id=None,             # str | None - 嵌套智能体的父 agent_id
+)
+```
+
+---
+
+### `event.agent_end()`
+
+当智能体完成工作时发送。
+
+```python
+agenteye.event.agent_end(
+    session_id="run-001",
+    agent_id="planner",
+    outcome="success",          # str | None
+    summary="Answered query",   # str | None
+)
+```
+
+---
+
+### `event.tool_use()`
+
+当智能体调用工具时发送。与 `tool_result` 配对；SDK 自动计算 `duration_ms`。
+
+```python
+agenteye.event.tool_use(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",     # str，必填
+    tool_call_id="toolu_01",    # str，必填 - 与匹配 tool_result 的关联键
+    input={"query": "..."},     # dict | None
+)
+```
+
+---
+
+### `event.tool_result()`
+
+当工具返回时发送。通过 `tool_call_id` 与 `tool_use` 关联。
+
+```python
+agenteye.event.tool_result(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",
+    tool_call_id="toolu_01",        # 必须与之前的 tool_use 匹配
+    output={"results": ["..."]},    # Any | None
+    error=None,                     # str | None - 若工具抛出异常则设置
+    # duration_ms 自动计算 - 请勿传递
+)
+```
+
+---
+
+### `event.model_request()`
+
+在向 LLM 发送提示词之前发送。
+
+```python
+agenteye.event.model_request(
+    session_id="run-001",
+    agent_id="planner",
+    model="claude-sonnet-4-6", # str | None - 任意提供商/模型字符串；不做验证
+    messages=[                   # list[dict] | None - 对话轮次
+        {"role": "user", "content": "..."},
+    ],
+    system="You are helpful.",   # Any | None - 字符串或内容块列表
+    tools=[                      # list[dict] | None - 提供给模型的工具模式
+        {"name": "search", "input_schema": {"type": "object"}},
+    ],
+)
+```
+
+`messages` 条目的 `content` 可以是普通字符串，也可以是 Anthropic 风格的块列表。采样参数（`temperature`、`max_tokens` 等）可作为额外 kwargs 传递。
+
+---
+
+### `event.model_response()`
+
+当 LLM 返回响应时发送。
+
+```python
+agenteye.event.model_response(
+    session_id="run-001",
+    agent_id="planner",
+    model="claude-sonnet-4-6", # str | None - 任意提供商/模型字符串；不做验证
+    stop_reason="end_turn",     # str | None
+    input_tokens=1024,          # int | None
+    output_tokens=256,          # int | None
+    content=[                    # Any | None - 字符串或内容块列表
+        {"type": "text", "text": "..."},
+    ],
+    role="assistant",            # str | None
+)
+```
+
+`content` 可以是普通字符串（通用提供商）或 Anthropic 风格的内容块列表。工具调用以 `{"type": "tool_use", ...}` 块的形式存在于 `content` 中，没有单独的 `tool_calls` 字段。
+
+---
+
+### `event.hook_triggered()`
+
+当钩子触发时发送。与 `hook_completed` 配对；SDK 自动计算 `duration_ms`。
+
+```python
+agenteye.event.hook_triggered(
+    session_id="run-001",
+    agent_id="planner",
+    hook_name="pre_tool_use",   # str，必填
+    hook_id="hook-abc",         # str，必填 - 关联键
+    trigger_event="tool_use",   # str | None
+    input={"tool": "search"},   # Any | None
+)
+```
+
+---
+
+### `event.hook_completed()`
+
+当钩子完成时发送。通过 `hook_id` 与 `hook_triggered` 关联。
+
+```python
+agenteye.event.hook_completed(
+    session_id="run-001",
+    agent_id="planner",
+    hook_name="pre_tool_use",
+    hook_id="hook-abc",         # 必须与之前的 hook_triggered 匹配
+    outcome="allow",            # str | None
+    output=None,                # Any | None
+    error=None,                 # str | None
+    # duration_ms 自动计算 - 请勿传递
+)
+```
+
+---
+
+### `event.error()`
+
+当发生未处理的错误时发送。
+
+```python
+agenteye.event.error(
+    session_id="run-001",
+    agent_id="planner",
+    error_type="TimeoutError",  # str，必填
+    message="timed out",        # str，必填
+    traceback="Traceback...",   # str | None
+)
+```
+
+---
+
+## 人在回路事件
+
+人在回路事件让您能够监督人员介入智能体执行的关键时刻（等待审批、提供输入、暂停或停止智能体）。通过这些事件，您可以衡量人类响应所需的时间（SDK 会自动为配对事件计算 `duration_ms`），审计谁暂停或中断了智能体，并构建在仪表板中呈现的审批和监督工作流。
+
+### `event.human_wait()`
+
+当智能体暂停执行以等待人类提供输入时发送。与 `human_input` 配对；SDK 自动计算 `duration_ms`（人类响应所需时间）。
+
+```python
+agenteye.event.human_wait(
+    session_id="run-001",
+    agent_id="planner",
+    input_id="inp-abc",                          # str，必填 - 与匹配 human_input 的关联键
+    prompt="Do you approve this action?",        # str | None - 展示给人类的问题
+    options=["approve", "reject", "defer"],      # list[str] | None - 提供给人类的选项
+    reason="approval_required",                  # str | None - 智能体等待的原因
+)
+```
+
+### `event.human_input()`
+
+当人类提供输入且智能体恢复执行时发送。通过 `input_id` 与 `human_wait` 关联。`duration_ms` 自动计算，调用方不得传递。
+
+```python
+agenteye.event.human_input(
+    session_id="run-001",
+    agent_id="planner",
+    input_id="inp-abc",    # str，必填 - 必须与之前的 human_wait 匹配
+    response="approve",    # str | None - 人类的回答（自由文本或所选选项）
+    # duration_ms 自动计算 - 请勿传递
+)
+```
+
+### `event.human_pause()`
+
+当人类主动暂停智能体时发送（例如通过仪表板控件）。智能体被挂起但未终止。
+
+```python
+agenteye.event.human_pause(
+    session_id="run-001",
+    agent_id="planner",
+    reason="user_requested",  # str | None
+    user_id="usr_42",         # str | None - 暂停智能体的人
+)
+```
+
+### `event.human_interrupt()`
+
+当人类在执行过程中主动停止智能体时发送。与 `human_pause` 不同，智能体的工作被终止而非挂起。
+
+```python
+agenteye.event.human_interrupt(
+    session_id="run-001",
+    agent_id="planner",
+    reason="output_incorrect",       # str | None
+    user_id="usr_42",                # str | None - 中断智能体的人
+    at_step="tool_use:web_search",   # str | None - 智能体被停止时正在执行的操作
+)
+```
+
+---
+
+## 自定义字段
+
+任何额外的关键字参数都会在标准字段之后附加到事件中：
+
+```python
+agenteye.event.tool_use(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="db_query",
+    tool_call_id="toolu_02",
+    tenant_id="acme",           # 自定义字段
+    region="us-east-1",         # 自定义字段
+)
+```
+
+`timestamp`、`type` 和 `environment` 是保留字段，如果作为自定义字段传递，将引发 `ValueError`（`Reserved field names cannot be used as custom fields: [...]`）。`session_id` 和 `agent_id` 是每个事件方法的必填参数，不能再次提供；若重复传递，Python 会引发 `TypeError`。请使用 `configure(environment=...)` 或 `AGENTEYE_ENVIRONMENT` 变量来设置环境。
+
+当您希望查询字段内容时，请保持负载为结构化 JSON。JSON 原生不支持的值类型——例如 datetime、UUID、decimal、set、bytes 或模型对象——将被转换为字符串，以确保记录安全继续。
+
+---
+
+## 事件的写入方式
+
+事件在进程内缓冲，每隔 `flush_interval` 秒（默认 500 毫秒）刷新到磁盘。每次刷新写入一个 JSONL 文件：
+
+```text
+~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl
+```
+
+采集器监视此目录并自动上传文件。您无需直接管理这些文件。
+
+每个文件以原子方式写入：SDK 先写入临时文件，然后将其重命名到位，因此采集器不会看到半写的文件。当您的进程退出时，还会执行最终刷新，确保最后一个间隔内缓冲的事件不会丢失。如果采集器处于离线状态，事件会以文件形式积累在磁盘上，待采集器恢复后自动上传。
+
+---
+
+## 后续步骤
+
+- [事件流](/zh/agenteye/event-stream)：实时查看这些事件，按事件类型颜色编码，可按环境、智能体和会话进行筛选。
+- [会话](/zh/agenteye/sessions)：了解配对事件如何将每次智能体运行重建为执行图和时间线。

package/.next/standalone/docs-old/zh/agenteye/queries.mdx

@@ -0,0 +1,56 @@
+---
+title: "查询"
+description: "向 Agent 数据提问，秒级获取答案。"
+---
+
+
+向 Agent 数据提问，秒级获取答案。Failproof AI 可观测性为您提供一个已保存、可直接运行的查询库，覆盖您的事件与评估数据，让您从现成示例出发，而无需面对空白的 SQL 编辑器。
+
+![已保存查询库：一个包含可复用查询的网格视图，涵盖内置预设和自定义查询](/agenteye/images/queries.png)
+
+*您的已保存查询库，位于 `/<org-slug>/queries`：内置预设与团队保存的查询并排展示。*
+
+## 从预设出发，而非从空白页开始
+
+您无需记忆表名，也无需从零编写 SQL。查询库打开后即展示内置预设，涵盖团队最常提问的问题，并与您团队已保存并命名的查询并排显示。选择一个接近您需求的预设，答案就已触手可及。
+
+每个已保存查询都以组织为作用域并对成员共享，因此您的队友写下的实用查询也会成为您的资源。为查询命名并添加描述后，组织内的任何人都可以找到它、运行它，或将其结果固定到仪表板上。
+
+访问路径：`/<org-slug>/queries`。
+
+## 在 SQL 编辑器中调整并运行
+
+打开任意查询，它会直接加载到 SQL 编辑器中，您可以即时调整并查看结果——无需导出，无需往返传递，无需等待他人。
+
+![SQL 查询编辑器正在运行一个已保存查询，左侧有 Schema 侧边栏，下方有实时结果网格](/agenteye/images/query-lab.png)
+
+*SQL 编辑器：左侧是您的查询，Schema 侧边栏让您无需猜测列名，下方是实时结果网格。*
+
+- **Schema 侧边栏** 列出分析表及其列名，让您无需翻找字段名即可构建查询。
+- **实时结果网格** 在您运行后立即返回数据行，秒级迭代，告别反复猜测。
+- **只读设计。** 查询在您的事件存储上运行，并在服务器端进行验证：仅允许 `SELECT` 和 `WITH` 语句，同时设有执行超时和行数上限。探索性查询永远不会修改您的数据，失控的查询也会被自动终止。
+
+对结果满意？将其保存回查询库，让整个团队共享；或将其输出以折线图、柱状图、面积图或饼图的形式固定到仪表板上。
+
+## 从终端运行，或让助手来写
+
+同样的已保存查询可在您工作的任何地方使用：
+
+- **从终端运行。** `agenteye` CLI 可列出、运行和保存完全相同的查询，您可以将结果输出到脚本中、接入 CI 流程，或传递给编程 Agent。
+
+```bash
+agenteye query list                 # 在终端查看相同的已保存查询
+agenteye query run errs --arg prod  # 运行并打印数据行（添加 --json 可进行管道传输）
+```
+
+  完整命令集请参阅 [CLI 与 Agents](/zh/agenteye/cli-and-agents)。
+
+- **从 AI 助手获取。** 不确定如何编写 SQL？用自然语言向仪表板内置的 [AI 助手](/zh/agenteye/assistant) 提问，它会为您起草查询并自动保存到查询库。
+
+运行已保存查询需要 `queries:run` 权限，该权限与创建或删除查询的权限相互独立，因此您可以授予只读访问权限，而无需允许所有人改写查询库。
+
+## 相关内容
+
+- [仪表板](/zh/agenteye/dashboards)：将查询结果固定为组织共享的图表。
+- [AI 助手](/zh/agenteye/assistant)：用自然语言提问，获取对应查询。
+- [CLI 与 Agents](/zh/agenteye/cli-and-agents)：从终端运行和保存相同的查询。

package/.next/standalone/docs-old/zh/agenteye/security.mdx

@@ -0,0 +1,68 @@
+---
+title: "安全性"
+description: "Failproof AI Observability 被设计为紧邻您的生产环境 Agent 运行，这意味着它能看到您的提示词、工具输入和输出内容。"
+---
+
+
+Failproof AI Observability 被设计为紧邻您的生产环境 Agent 运行，这意味着它能看到您的提示词、工具输入和输出内容。本页说明它如何确保数据隔离、受控，并始终掌握在您手中。如果您正在对 Failproof AI Observability 进行安全审查评估，请从这里开始。
+
+---
+
+## 您的数据保留在您的环境中
+
+Failproof AI Observability 采用自托管模式。事件、提示词、模型响应和分析数据均存储在您自己的数据库和环境中。数据不会被发送至任何第三方 SaaS 平台存储，始终保留在您自己的云账户内。
+
+---
+
+## 租户隔离
+
+一个 Failproof AI Observability 实例可以托管多个组织，每个组织在存储层面相互隔离——这由数据库强制执行，而不仅仅依赖 UI 层面的限制：
+
+- 组织的运营数据（用户、密钥、仪表盘、已保存查询）仅限于该组织访问，跨组织读取由数据库本身拦截阻止。
+- 每个采集的事件都标记了所属组织，因此一个组织的事件永远无法被另一个组织读取。
+
+每个仪表盘路由都以组织 slug 为前缀（`/<org-slug>/…`）。
+
+---
+
+## 登录方式
+
+Failproof AI Observability 采用无密码、基于邮件的登录方式，不存在可被钓鱼或泄露的密码。用户申请一次性验证码（或一键魔法链接），系统将其发送至用户邮箱，且会在短时间内过期。登录受**白名单**限制：只有您允许的邮箱地址（或域名）才能完成认证。
+
+![Failproof AI Observability 登录界面，将一次性验证码发送至您的邮箱](/agenteye/images/login.png)
+
+---
+
+## 通过 API 密钥实现精细化访问控制
+
+每个客户端均使用携带精细化最小权限的 API 密钥进行认证。数据采集器只需 `events:add` 权限；仪表盘或助手密钥可设为只读；破坏性操作（删除、重新生成）作为独立权限授予，由您自行决定是否开放。
+
+![API 密钥页面：每个密钥的权限授予情况，按读取、写入和破坏性范围用颜色区分](/agenteye/images/api-keys.png)
+
+保留管理员引导密钥用于初始配置，其余场景均应颁发权限受限的密钥。详见 [API 密钥](/zh/agenteye/api-keys)。
+
+---
+
+## 只读、需审批的 AI 助手
+
+仪表盘内的 [AI 助手](/zh/agenteye/assistant) 可基于您的数据回答问题，但在设计上受到严格约束：
+
+- **默认只读**：其执行的 SQL 经过守卫过滤，仅允许 `SELECT`/`WITH` 查询，单条语句执行，并设有行数上限。
+- 它创建的任何内容（已保存查询、仪表盘）均需**审批才能生效**：每一次写入操作发生前，您都需要审查并确认。
+- **它永远无法执行删除操作**。
+
+因此，团队成员可以询问"本周哪些 Agent 报错最多？"并基于答案采取行动，而无需担心助手会自行修改或删除您的数据。
+
+---
+
+## 传输安全
+
+所有流量均通过 HTTPS 传输。您使用自己的证书终止 TLS，确保采集器到服务器以及浏览器到服务器的流量在传输过程中全程加密。
+
+---
+
+## 后续步骤
+
+- [概览](/zh/agenteye/overview)：了解 Failproof AI Observability 的整体架构。
+- [API 密钥](/zh/agenteye/api-keys)：为采集器、仪表盘和助手配置访问权限。
+- [可观测性](/zh/agenteye/observability)：了解 Failproof AI Observability 从您的 Agent 中采集的数据内容。

package/.next/standalone/docs-old/zh/agenteye/sessions.mdx

@@ -0,0 +1,56 @@
+---
+title: "会话与执行图"
+description: "将一次运行的所有事件汇总为一行可读记录，并以 git 风格的执行图直观呈现，让你几秒内看清全貌。"
+---
+
+不再猜测运行失败的原因。Failproof AI 可观测性将一次运行的所有事件汇总为一行可读记录，再将整个运行过程绘制成 git 风格的图示，让你几秒内看清全貌，逐步了解智能体究竟做了什么。
+
+![会话列表：每次运行占一行，跨越多个环境和智能体，附带状态标签和评估分数徽章](/agenteye/images/sessions-list.png)
+
+*每次运行占一行：状态标签让你一眼看出运行结果，连接评估器后还会显示分数徽章。*
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/VWxukZc5k7s?autoplay=1&mute=1&loop=1&playlist=VWxukZc5k7s&rel=0&playsinline=1" title="Watch: Agent Tracing by Failproof AI (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+*智能体追踪：从目标到工具调用再到最终答案，逐步跟踪一次完整运行。*
+
+---
+
+## 一眼纵览所有运行
+
+原始事件流记录了每一步的真实情况，但当你面对数十次运行中的数千个步骤时，你需要的是运行层面的视图，而不是单步细节。会话页面将一次运行的所有事件汇总为一行，让一天的活动变成一份可快速浏览的列表，而非令人眼花缭乱的信息洪流。
+
+每行都带有状态标签，让失败的运行在你点击之前就能一眼显现。按日期范围、环境、智能体或会话进行筛选，几次点击即可从「全部」缩小到「我关心的那次运行」。
+
+连接评估器后，每次完成的运行都会自动获得评分，最新分数以徽章形式显示在对应行上。你可以按任意分数范围筛选，「显示本周所有低分生产运行」只是一个筛选条件，无需人工逐一查看。在设置评估器之前，会话仍然会完整记录运行过程，只是暂时没有分数。
+
+---
+
+## 以图示读懂整个运行过程
+
+![会话的 git 风格执行图与事件时间线并排显示，右侧面板展示工具、模型和 hook 的详细拆解](/agenteye/images/session-detail.png)
+
+*执行图（左侧）与事件时间线并排显示；右侧栏对本次运行使用的工具、模型、hook 以及 token 消耗进行详细拆解。*
+
+点击任意会话，即可打开其执行图：这是一个 git 风格的视图，展示了智能体、工具、hook 和模型调用随时间展开的过程。并行的子智能体各自分支到独立的泳道，让你清楚地看到哪些工作是并行执行的、哪个子智能体发生了停滞、以及运行在哪里偏离了预期——无需在脑海中从一堆日志中重新推演。
+
+右侧栏提供逐次运行的详细拆解：哪些工具和模型参与了运行、哪些 hook 触发了、以及本次运行消耗了多少 token。「这次运行为什么这么贵？」或「哪个工具最慢？」的答案就在执行图旁边。
+
+每个单独事件都有固定链接，因此你可以把某一时刻的链接直接分享给他人，而不是说「在那个会话里，大概三分之二的位置」。从任意事件复制链接，或从[审计](/zh/agenteye/audits)发现或错误中跳转，会话将打开并定位到该事件。对于非常长的运行同样适用：时间线出于浏览器性能考虑只加载有限的时间窗口，但指向窗口之外的链接仍然能定位到对应事件，而不是把你扔到最开始。如果该事件已超出你的数据保留窗口，页面会明确提示，而不是静默地选中空白内容。
+
+---
+
+## 在哪里找到它
+
+每个控制台页面都限定在你的组织范围内（`/<org-slug>/…`）。会话功能位于左侧边栏的 **Observe** 下，紧邻 Events，列表顶部提供日期范围、环境、智能体和会话等筛选条件。每行点击一次即可进入完整执行图。
+
+要开启分数徽章和按分数范围筛选的功能，请连接评估器，详见[评估](/zh/agenteye/evaluations)。
+
+---
+
+## 相关内容
+
+- [事件流](/zh/agenteye/event-stream)：每个会话汇总自原始的逐步事件记录。
+- [评估](/zh/agenteye/evaluations)：连接评估器，让每次运行都获得可供筛选的分数徽章。
+- [遥测](/zh/agenteye/telemetry)：了解运行数据如何从你的智能体传入这些会话。

package/.next/standalone/docs-old/zh/agenteye/telemetry.mdx

@@ -0,0 +1,52 @@
+---
+title: "性能指标"
+description: "即时发现模型、工具或 hook 的性能下降或费用飙升，在用户察觉之前捕捉尾延迟峰值。"
+---
+
+
+即时发现模型、工具或 hook 的性能下降或费用飙升，在用户察觉之前捕捉尾延迟峰值。三个专属页面将原始计时数据转化为一目了然的 p50、p95 和 p99 指标。
+
+![模型页面展示了延迟热力图、百分位数区间，以及每个模型的 token 数量、成本和上下文窗口占用情况](/agenteye/images/models.png)
+*模型页面：延迟热力图、百分位数区间，以及每个模型的 token 数量、预估成本和上下文窗口填充情况。*
+
+## 别让平均值掩盖最糟糕的情况
+
+平均延迟数字看似令人安心，实则毫无意义：它将每五十次调用中那一次导致凌晨两点告警的卡顿全部抹平了。模型、工具和 Hook 页面拒绝这样做。三个页面结构相同，学会一个，其余触类旁通：
+
+- **24 格迷你折线图**，一眼看出趋势：情况是否在恶化？
+- **核心指标条**，展示 p50、p95 和 p99 延迟，让典型运行时间与尾部延迟并排对比。
+- **延迟热力图**，横轴为 24 个时间段，纵轴为延迟区间，直观呈现慢调用的集中时段。
+- **百分位数区间**：p50 中线配合 p25 至 p75、p10 至 p90 的阴影带以及 p99 散点，让分布情况清晰可见，而非被平均值淹没。
+
+热力图与区间图共享悬停十字准线，尾部延迟峰值在两者中同步对齐，不会藏匿于单一均值线之后。在仪表板的 **observe** 区域可找到这三个页面，均按组织范围划分，支持按日期范围、环境、Agent 和会话进行筛选。
+
+## 模型：精确掌握每个模型的成本
+
+模型页面（如上图所示）直接回答账单上的两个问题：哪个模型，花了多少钱。在共享延迟视图之上，它还增加了**每模型 token 消耗量**、**预估成本**和**上下文窗口填充情况**，让提示词无节制增长和即将触发的压缩操作在发生之前就能被发现。
+
+Failproof AI Observability 能自动识别常见的模型 ID。如果某个窗口显示有误，或者您使用的是自有私有模型，可在 **Settings** 的 **model context windows** 中进行修正或添加，填充率读数将随之更新。
+
+## 工具：区分慢速与故障
+
+一次工具调用可能只是速度慢，也可能是在悄悄失败，您希望在几秒内知道是哪种情况，而不是翻遍日志之后才发现。
+
+![工具页面展示了共享的延迟热力图和百分位数区间，以及成功/失败分类统计和工具分布条形图](/agenteye/images/tools.png)
+*工具页面：相同的热力图和百分位数区间，加上成功/失败分类统计和工具分布条形图。*
+
+在共享延迟视图的基础上，工具页面额外提供**成功/失败分类统计**和**工具分布条形图**，让您一眼看出哪些工具最常被调用，哪些正在侵蚀您的错误预算。
+
+## Hook：精准定位具体的 hook 和触发事件
+
+当某个生命周期 hook 拖慢了运行速度，"hook 太慢了"这样的结论根本无从下手。Hook 页面能帮您直接定位到问题所在。
+
+![Hook 页面在共享热力图和百分位数区间之上，按 hook 名称和触发事件细分延迟数据](/agenteye/images/hooks.png)
+*Hook 页面：按 hook 名称和触发事件细分的延迟数据。*
+
+在相同的延迟热力图和百分位数区间之上，Hook 页面将活动按 **hook 名称**和**触发事件**进行细分，让您精准锁定需要关注的单个 hook 和单个事件。
+
+## 相关内容
+
+- [事件流](/zh/agenteye/event-stream)：每个事件的实时彩色追踪记录。
+- [会话](/zh/agenteye/sessions)：将事件汇总为每次运行一行，并打开其执行图。
+- [错误追踪](/zh/agenteye/error-tracking)：统一处理仪表板标红的所有问题。
+- [仪表板](/zh/agenteye/dashboards)：跨全局的汇总视图。