›_ 提示字形和一个彩色的健康状态点。点击轨道（或按 ⌘J / Ctrl+J）可展开为完整的聊天面板。展开后的面板可通过拖动左边缘在 320 到 640 像素之间自由调整宽度，且你的偏好宽度会在刷新后保留。
助手作为一个小型内部 agent 容器运行（基于 Claude Agent SDK），仅供仪表盘访问。默认情况下处于禁用状态，需配置 LLM 端点后才会显示。
能力范围
- 读取发起请求的用户有权访问的运营数据。 包括事件、评估、会话、评估任务队列、已保存的查询和仪表盘，所有数据均根据用户的读取权限按请求进行范围限定。读取工具立即执行。
- 写操作需逐项审批。 助手可以创建已保存查询（
create_saved_query、update_saved_query）、在只读角色下执行草稿 SQL 以进行验证（run_query），并将这些查询组合成仪表盘（create_dashboard、update_dashboard、add_query_to_dashboard）。每次写操作都会在聊天中暂停，显示批准 / 拒绝 / 提问提示；SDK 在操作员点击”批准”之前不会调用该工具。助手永远不具备删除能力；破坏性操作仅限操作员执行。 - 起草的 SQL 会经过与用户编写的 SQL 相同的
sql_guard验证和只读角色（仅限 SELECT/WITH，不支持多语句）。执行路由取决于查询涉及的表：引用分析表（事件、评估、会话）的查询以组织的只读 ClickHouse 用户身份运行（通过行策略限定到该组织，执行上限为 10 秒，行数上限为 10 万）；仅涉及关系表的查询则在只读 Postgres 角色下运行（10 秒，1 万行）。助手无法扩大数据访问范围，只能在操作员已有的查询权限范围内进行操作。 - 助手使用专用助手密钥（见下文），该密钥预设了固定的权限集；即使模型出现异常行为，也无法超出这些权限范围。
- 每个仪表盘用户需要拥有
agent:use权限才能看到并使用助手。工具会按请求过滤以匹配用户自身的数据权限，例如拥有events:read的用户可获得事件工具，但不会获得dashboards:write工具。
页面感知的 AI 停靠栏：在 /queries 页面作为编辑器，其他页面作为聊天助手
右侧的助手停靠栏具有页面感知能力。模型选择器、对话历史、模型健康状态点和聊天输入框保持不变，但空状态模板卡片、占位符文本以及用户消息实际调用的后端端点都会根据当前路由自动切换。停靠栏会变成”你当前所在页面的 AI 助手”。
两个后端，按页面自动选择（支持按卡片覆盖）。
| 路由 | 页面默认后端 | 原因 |
|---|---|---|
/queries、/queries/new | POST /api/agent/compose-sql（无工具循环） | 用户正在从头开始；首个 token 延迟 ≤1 秒的 SQL 直接流式输出到编辑器 |
/queries/<id>（已有查询） | POST /api/agent/chat（完整工具循环助手），页面默认 | 自由输入的消息应允许用户提任何问题（“解释一下”、“这是做什么的？”）；重构卡片通过 per-chip kind 切换回 compose-sql |
| 其他所有页面 | POST /api/agent/chat（完整工具循环助手） | 读取工具 + 审批门控的写入工具 |
/queries/<id> 上的卡片带有明确的 kind 字段，使单个页面可以无缝混用两种流程。默认卡片集包含两个聊天卡片（解释当前查询、这个查询做什么？）和五个 compose-sql 卡片（按日期范围参数化、添加 status='error' 过滤条件 等）。自由输入的消息回落到页面默认（聊天），因此”为什么这么慢？“这类问题会获得散文式回答，而点击按日期范围参数化卡片则会路由到 compose 端点并修改 SQL。
当编辑器处于编辑模式时（因为用户在 /queries/<id> 上，或者 /queries/new 已加载了待处理的 SQL，导致 currentSql 不为空），系统提示词会从”编写一个新查询”切换为”对所提供的 SQL 进行最小化修改：保留表的选择、列名、连接结构、别名和缩进”。模型会接收到一组独立的修改前后示例（参数化、添加过滤条件、转换为按小时分桶），因此通过卡片触发的重构会生成针对编辑器中 SQL 的最小差异，而不是从头重写。
点击 compose 卡片（或在 /queries/new 上自由输入）→ SQL 以 ```sql 代码块的形式流式输出到助手消息中。当流输出完成后，若当前路由挂载了 Monaco 编辑器，编辑器会自动进入差异视图（左侧为原始内容，右侧为建议内容，顶部有▾ AI 提出了修改提示，下方有接受 / 拒绝按钮）。用户无需查找或点击”插入编辑器”按钮即可看到差异。“插入”按钮仍会显示在 SQL 块下方，作为手动重新触发的入口（在拒绝后或用户离开又返回时很有用）；当用户在非编辑器页面（例如已保存查询列表）时，它是唯一的操作路径——此时会将 SQL 暂存到 sessionStorage 并跳转到 /queries/new，新挂载的编辑器在初始化时读取暂存内容并打开相同的差异视图。
如果建议的 SQL 与编辑器中已有的内容完全相同（无实质性修改），则跳过自动打开差异视图，避免弹出空差异。此时”插入编辑器”按钮同样不执行任何操作。
当用户在 /queries/new 上接受建议时，工具栏的主操作按钮显示为**保存**而非创建；SQL 由助手生成，操作的心智模型是”最终确认”而非”从头编写”。停靠栏插入 SQL 后标签立即切换为保存，直到页面导航才恢复。在 /queries/<id> 上按钮始终为保存，不受影响。
在 /queries 以外的页面，停靠栏的行为与之前完全一致：带有工具审批卡片的完整聊天、页面上下文感知和引用链接。
权限 / 访问控制。 compose 端点按用户的 queries:run 权限进行门控（等同于读取权限；用户仍需点击”接受”和”运行”，而”运行”会经过 Rust 服务器上现有的 sql_guard + references_ch_tables 路由）。chat 端点按 agent:use 门控。两者都要求在 agent 容器上配置了 LLM 连接；若未配置，停靠栏会在两种路径上均显示”此部署未配置助手”的横幅。
拒绝策略。 compose 模式会拒绝任何无法通过只读分析查询满足的请求，并输出 -- REFUSE: <一句话原因> 代替 SQL。它会拒绝会写入数据或访问分析视图以外的表（api_keys、users、dashboards、saved_queries、evaluation_jobs）的请求，也会拒绝在 compose 路径上的纯文本请求（如”解释一下”、“这是做什么的？”）——这类请求应走 chat 路径并在那里获得散文式回答。停靠栏会将拒绝原因以内联红色错误卡片的形式显示在助手消息中，不插入任何内容。
模型选择。 与聊天路径共享。停靠栏标题中的模型选择器适用于两个端点（compose 调用会将选中的模型传递给 agent 服务上的 resolveModel()）。当 AGENTEYE_AGENT_MODELS 列出多个模型时，操作员可以为 compose 选择 Haiku 级别的模型，为聊天选择 Sonnet 级别的模型；用户按对话进行选择。
按页面定制模板。 每个页面都有自己的模板（标题、正文、占位符文本和建议卡片），使停靠栏能够适应你所在的页面。特定路由上提供的卡片与 compose 模型调优的意图一致，因此点击建议会产生预期的修改效果。
禁用方式。 与聊天路径相同：停靠栏和 compose 功能都通过 agent 容器及其 LLM 连接进行门控。如果你希望特定用户只使用聊天功能，移除 queries:run 权限（这也会禁用编辑器的运行按钮）；如果你希望只使用 compose 功能，从该用户的角色中移除 agent:use，然后单独重新添加 queries:run，这样他们仍然可以执行自己编写的 SQL。
启用方式
agent 服务已包含在 Docker Compose 文件和 Kubernetes 清单中。要启用助手，需要提供 (1) LLM 端点 和 (2) 助手专用数据密钥。
1. 选择 LLM 连接方式
从以下选项中选择一种，并在agent 服务上设置对应的变量：
a) 直接使用 Anthropic
@<slug>/<model>，slug 中包含了 provider 和凭证路由，因此不需要虚拟密钥，只需你的 Portkey API 密钥即可。Agent 只发送 x-portkey-api-key 并指向 Portkey 网关，Portkey 负责解析其余内容。（使用普通模型名称会报错”x-portkey-config or x-portkey-provider header is required”；@slug/ 前缀是实现纯密钥访问的关键。）如需使用自托管网关，请设置 PORTKEY_BASE_URL。
如果你偏好按请求路由而非使用 slug，可以设置 PORTKEY_VIRTUAL_KEY=<vk>（或 PORTKEY_CONFIG=<id>）配合普通的 AGENTEYE_AGENT_MODEL。
c) 其他兼容 Anthropic 的网关（LiteLLM、自托管等）
AGENTEYE_AGENT_MODEL 固定默认模型（默认值为 claude-sonnet-4-6）。若需允许用户从多个模型中选择，将 AGENTEYE_AGENT_MODELS 设置为逗号分隔的允许列表（例如 @anthropic-prod/claude-opus-4-7,@anthropic-prod/claude-sonnet-4-6）；聊天标题中会出现模型选择器，每个用户的选择会被记住。Agent 只会调用此允许列表中的模型。
2. 提供助手密钥
选择任意随机密钥，将其作为AGENTEYE_API_KEY 提供给 agent 服务，同时作为 AGENT_API_KEY 提供给 server 服务（值相同）。服务器启动时会将其注册为名为 dashboard-assistant 的专用密钥，并赋予以下固定权限集：events:read、evaluations:read、dashboards:read、dashboards:write、queries:read、queries:write、queries:run。写入权限只通过审批门控的工具执行（见上文”能力范围”部分）。无需手动创建密钥，也不涉及管理员密钥。权限集在服务器中固定，且注册的密钥受保护：无法通过 keys API 禁用或重新生成；如需轮换，只需更改值并重启服务器。请勿复用管理员/仪表盘密钥。
AGENTEYE_API_KEY 放入 agenteye-agent secret 中，服务器 Deployment 已自动将相同的值作为 AGENT_API_KEY 读取。
3. 设置仪表盘与 Agent 之间的共享令牌
在dashboard 和 agent 服务上设置相同的 AGENTEYE_AGENT_TOKEN。仪表盘在调用内部 agent 服务时出示该令牌；Agent 会拒绝不携带此令牌的请求。
4. 授予用户访问权限
为相关的仪表盘操作员授予agent:use 权限（参见 enterprise-docs/api-keys.md）。没有该权限的用户将看不到助手。
配置好 LLM 端点和只读密钥后，重启 server（以注册只读密钥）和 agent 服务。任何拥有 agent:use 权限的用户的仪表盘右侧都会出现助手停靠栏，默认收起；点击轨道或按 ⌘J / Ctrl+J 展开。
环境变量参考
在agent 服务上设置：
| 变量 | 用途 |
|---|---|
PORTKEY_API_KEY | 通过 Portkey 路由（agent 据此构建网关连接） |
PORTKEY_VIRTUAL_KEY | 你的 Anthropic 凭证的 Portkey 虚拟密钥（如果该密钥有默认配置则可选） |
PORTKEY_CONFIG / PORTKEY_BASE_URL | 命名的 Portkey 配置 / 自托管 Portkey 网关 URL（可选） |
PORTKEY_PROVIDER | Portkey provider slug——除 PORTKEY_VIRTUAL_KEY / PORTKEY_CONFIG 之外的第三种路由选项（仅在两者均未设置时使用） |
ANTHROPIC_API_KEY | 直接访问 Anthropic（网关 / Bedrock / Vertex 的替代方案） |
ANTHROPIC_AUTH_TOKEN | 用于通过 Authorization: Bearer 而非 x-api-key 进行身份验证的网关的 Bearer 令牌（可选） |
ANTHROPIC_BASE_URL | 非 Portkey 网关的端点 |
ANTHROPIC_CUSTOM_HEADERS | 非 Portkey 网关的额外请求头：换行分隔的 Name: Value 格式（非 JSON） |
CLAUDE_CODE_USE_BEDROCK / CLAUDE_CODE_USE_VERTEX | 通过 Bedrock / Vertex 路由 |
AGENTEYE_AGENT_MODEL | 默认模型 ID（默认值 claude-sonnet-4-6） |
AGENTEYE_AGENT_MODELS | 用户可在聊天标题中选择的模型允许列表（逗号分隔）。不设置则使用单一固定模型。上述默认值必须包含在列表中（否则会自动添加）。 |
AGENTEYE_AGENT_MAX_CONCURRENCY | 每个 Pod 的最大并发聊天数（默认 4）；超出的请求返回 429 |
AGENTEYE_API_KEY | 助手的数据密钥。与服务器的 AGENT_API_KEY 设置相同的值，服务器启动时会将其注册为具有固定范围权限集的密钥（见步骤 2）。 |
AGENTEYE_AGENT_TOKEN | 与仪表盘共享的密钥 |
AGENTEYE_SERVER_URL | AgentEye 服务器 URL（默认值 http://server:8080） |
AGENTEYE_AGENT_ALLOW_NO_ORG | 多租户支持。 默认关闭（安全失败）：若 /chat 请求不携带组织上下文，助手会返回 400 拒绝请求，因为其所有工具都限定在单个组织范围内。仪表盘一旦具有组织感知能力，就会始终发送该上下文，因此通常无需设置此变量。仅在过渡期内使用，即尚未具备组织感知能力的仪表盘与已具备组织感知能力的 agent 通信时，设置为 1 使助手回退到 default 组织而非拒绝请求。仪表盘升级完成后请清除此设置。 |
AGENTEYE_AGENT_MAX_STEPS | 每次回答的最大工具调用步数（默认 8） |
AGENTEYE_AGENT_TIMEOUT_MS | /chat 请求的整体超时时间（包括所有模型轮次和工具步骤），单位毫秒（默认 90000）；SQL 工具有独立的 10 秒上限 |
AGENTEYE_AGENT_SELF_TELEMETRY | 设为 1 以将助手自身的运行记录到 AgentEye 中 |
AGENTEYE_TELEMETRY_API_KEY | 用于自监控的独立 events:add 专用密钥 |
AGENTEYE_AGENT_ENV | 应用于助手自监控数据的环境标签（默认值 prod） |
dashboard 服务上设置：
| 变量 | 用途 |
|---|---|
AGENTEYE_AGENT_URL | 仪表盘访问 agent 服务的地址。随附的 Kubernetes 清单和 Compose 文件将此设置为 http://agent:9100。不设置则完全隐藏助手。 |
AGENTEYE_AGENT_TOKEN | 必须与 agent 的令牌一致 |
遥测与查看用户提问内容
提示词内容默认保留在你自己的系统内。共有三个层次：- 对话存储：每个提示词和回答都保存在你的 AgentEye 数据库中（按用户，私密），可从助手的历史记录切换器中重新加载。这是用户提问内容的持久记录。
- 产品分析：仪表盘仅记录元数据（助手的使用频率、工具调用次数、延迟）到你的分析系统。此路径不包含提示词文本。
- 自监控（可选）：设置
AGENTEYE_AGENT_SELF_TELEMETRY=1（以及仅具有events:add权限的AGENTEYE_TELEMETRY_API_KEY），助手会将自身的运行记录到 AgentEye 中，以dashboard-assistantagent 的身份存储。然后你可以在用于其他所有内容的同一会话/事件视图中查看用户提示词和助手的推理过程。注意：这些事件对任何拥有events:read权限的人可见；如果范围过广，请不要启用此功能。
禁用方式
以下任意一种方式均可禁用助手（停靠轨道消失）：- 在仪表盘上取消设置
AGENTEYE_AGENT_URL，或 - 在 agent 上不配置 LLM 端点（不设置
ANTHROPIC_API_KEY/ 网关 / Bedrock / Vertex），或 - 完全不部署
agent服务。
安全摘要
- 无静默写入：助手的写入工具（
create_saved_query、update_saved_query、create_dashboard、update_dashboard、add_query_to_dashboard）在操作员明确点击聊天中的”批准”按钮之前无法执行；SDK 的调用前拦截会阻止工具执行，直到审批信号通过后台通道到达 agent。此拦截机制没有任何禁用设置。 - 固定且受限的数据范围：助手通过专用密钥向服务器进行身份验证，该密钥的权限集在服务器中固定（
events:read、evaluations:read、dashboards:read、dashboards:write、queries:read、queries:write、queries:run）。它能够创建的写入内容仅限于已保存的查询和仪表盘；无论模型尝试什么操作，服务器都会拒绝超出该范围的请求。 - 无删除权限：密钥不包含删除权限，也不暴露任何删除工具。删除操作通过仪表盘 UI 由操作员执行，不经过助手。
- 仅限内部访问：agent 没有公开路由；只有仪表盘可以调用它，且必须携带共享令牌。（在 Kubernetes 中，NetworkPolicy 限制 agent 只能访问 AgentEye 服务器和 LLM 端点。）
- 按用户范围限定：只有拥有
agent:use权限的用户才能使用助手，且只提供与每个用户读取权限匹配的工具。 - 无原始 HTML / 无链接外泄：回答以经过净化处理的 Markdown 格式渲染；外部链接已被无害化处理。