agentglass

<div align="center"> # ✦ AgentGlass ### 您的 AI 代理的透明窗口 **捕获、检查、重放和分析每一次代理运行 — 无需 SDK，无需代码修改** 将您的代理的基准 URL 指向 AgentGlass，即可查看每一次 LLM 调用、工具调用、令牌和花费的美元。实时显示，在您的本地机器上。      _{实时仪表盘 → 展开运行（瀑布流、上下文增长、每一步的输入/输出）→ 分析 → 向运行提问。} </div> --- ## AgentGlass 存在的原因 您的代理刚刚进行了 14 次 LLM 调用，调用了 6 次工具，消耗了 180k 个令牌，花费了 \$2.30 —— 但您对发生了什么**完全不知情**。哪一步导致上下文窗口溢出？哪个工具调用失败并被静默重试？哪个模型消耗了您的预算？现代 AI 代理是**黑盒**：您只看到最终答案，而不是它们到达答案的复杂、昂贵的路径。 **AgentGlass 使它们透明。** 它透明地位于您的代理和模型提供商（Anthropic 或 OpenAI）之间，记录通过的所有内容，并将其转换为一个您可以阅读的仪表盘 —— 跟踪每一个跟踪、跨度、令牌和美元。 - 🛰️ **无需仪表盘。** 无需安装 SDK，无需导入包装器。设置一个环境变量，即可开始捕获。与 Claude Code、OpenAI SDK、LangChain 兼容 —— 任何使用 Anthropic 或 OpenAI 线路格式的工具。 - 🔒 **本地优先。** 所有内容都在您的机器上运行并存储。单个进程，一个 SQLite 文件，无需云，无需账户，无需遥测。 - 🧱 **无原生模块。** 基于 Node 内置的 `node:sqlite` 构建 —— 无需编译，在所有平台上安装干净。 - 🎛️ **像仪器一样读取。** 一个密集、黑暗、专用的控制台：工具调用瀑布流、每步令牌和成本表、上下文窗口图表、运行差异、花费分析，以及一个回答您运行问题的助手。 ``` 您的代理 ──▶ AgentGlass ──▶ Anthropic / OpenAI │ ▼ 记录 + 流式传输 │ ▼ 📊 仪表盘 ``` ## 快速入门 ```bash npx agentglass ``` 就这样。打开 **http://localhost:4319** —— 仪表盘已经上线，包含一周的**模拟**代理运行，因此每个屏幕在您连接任何内容之前都有内容可显示。 然后将一个真实的代理指向它： ```bash # Claude / Anthropic SDK export ANTHROPIC_BASE_URL=http://localhost:4319 # OpenAI SDK — 也适用于 OpenRouter、LiteLLM、Groq、Together、vLLM、Ollama… export OPENAI_BASE_URL=http://localhost:4319/v1 ``` 像平常一样运行您的代理。每次调用、每个工具、每个令牌、每笔花费都会显示出来 —— **无需 SDK，无需装饰器，无需代码修改。** <details> <summary>其他运行方式</summary> ```bash # 容器 docker run -p 4319:4319 -v agentglass:/app/data ghcr.io/vugarfamiloglu/agentglass # 从源码开始，热重载（仪表盘在 :4318，服务器在 :4319） git clone https://github.com/vugarfamiloglu/agentglass.git cd agentglass npm install && npm --prefix web install npm run dev ``` </details> --- ## 浏览每张屏幕 AgentGlass 在左侧导航栏中分为三个组 —— **观察**（正在发生什么）、**分析**（花费了什么以及表现如何）、**设置**（如何连接和配置）。以下是每张屏幕的作用。 ### 概述 — 命令中心  登陆页面一眼就能回答“我的代理现在表现如何？” 六个**统计卡片** 显示总运行次数、累计花费、使用的令牌数（以及从缓存中提供的令牌数）、工具调用次数、错误率和平均延迟。在它们下面，一个**花费图表** 绘制了过去一天的每小时花费，一个**最近运行** 表列出了最新的代理运行及其模型、状态、令牌、花费和年龄 —— **实时** 更新。 ### 直播 — 观看运行到达  代理运行开始时的实时推送。借助 WebSocket 流式传输，它显示正在进行的运行（状态为 `RUNNING`）变为 `OK` 或 `ERROR`，令牌和花费不断增加。这是您在代理运行时会在第二个显示器上打开的屏幕。 ### 跟踪 — 每个运行都可搜索  每个代理运行的完整、可筛选的日志。按运行名称或模型搜索，按状态筛选（`all` / `ok` / `error` / `running`），并分页浏览历史。每一行代表一个代理运行 —— 其跨度数、总令牌数、花费、持续时间和发生时间。点击任意一行即可打开**检查器**。 ### 运行检查器 — 打开黑盒  这是 AgentGlass 的核心。打开一个运行，查看其中发生了什么： - **摘要芯片** — 整个运行的持续时间、跨度数、工具调用、令牌、缓存令牌和总花费。 - **上下文窗口图表** — 每个 LLM 调用的堆叠条形图，显示输入上下文如何**增长**（紫色 = 新鲜输入，青色 = 缓存）。这就是您发现消耗上下文预算的步骤的地方。 - **时间线瀑布流** — 每个跨度（LLM 调用、工具执行、事件）作为时间定位条形，按类型着色，以便您可以看到代理的 `计划 → 工具 → 观察 → 动作` 循环展开。每一行显示该步骤的令牌、花费和延迟。 - **点击任意跨度** 以展开其完整的输入和输出 JSON、模型和确切的令牌/花费明细。 ### 运行差异 — 比较两个运行  选择任意两个运行并并排比较。**指标** 行显示每个运行的成本、令牌、跨度、工具调用和持续时间，带有彩色增量（青色 = 更好，玫瑰色 = 更差）—— 这样您就可以一眼看出“opus 是否真的值得比 mini 多 100 倍的成本？” 在下面，两个运行的跨度序列并排放置。 ### 分析 — 花费、模式和明细  大局观。一个**花费图表** 随时间变化，一个 GitHub 风格的**活动热图** （每天的运行次数），以及两个明细表：**按模型** （每个模型的成本、调用次数和令牌数，带有比例条形图）和**按工具** （每个工具的调用次数和失败次数）。单击一次**导出所有跟踪到 CSV** 以供您自己的分析。 ### 模型和工具 — 每个实体的详细信息  专页深入研究单个维度。**模型** 按成本排名显示每个模型的调用次数和令牌使用量；**工具** 按调用频率和失败次数排名 —— 快速找到悄悄导致重试的故障工具。  ### 连接 — 将您的代理指向此处  记录代理的设置。显示确切的 `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` 值，可选的 `x-agentglass-session` 头部用于将任务的调用分组到一个跟踪中，以及请求如何流经 AgentGlass 到达真实提供商并返回的图表。 ### 设置 — 连接模型，注意您的数据  助手在**没有任何连接**的情况下本地回答有关运行的问题。将其指向模型以解锁开放式分析: | | | |---|---| | **托管** | Anthropic · OpenAI · Google Gemini · xAI Grok · DeepSeek · Mistral · Groq · Together · OpenRouter · Cohere · Qwen | | **本地** | Ollama · LM Studio — **无需密钥，无需成本，数据不会离开机器** | | **其他** | 自定义基准 URL — vLLM、LiteLLM、Azure、您自己的网关 | 几乎每个供应商现在都提供与 OpenAI 兼容的 `/v1/chat/completions` 端点，因此添加一个只是基准 URL 而不是新客户端；Anthropic 的原生 Messages API 直接支持。**加载模型** 会询问提供商它当前提供的内容 —— 包括您已拉取到 Ollama 的模型 —— 因此您从实际情况中选择。密钥使用 **AES-256-GCM** 在 `data/.vault-key` 中密封，**每个提供商一个**，因此切换来回不会丢失它们。 **数据** 面板显示存储了多少运行以及在磁盘上花费了多少，并允许您设置保留窗口（7 / 30 / 90 天，或保留所有内容 — 默认）。超出窗口的内容会在启动和之后每隔几个小时修剪。清除跟踪和断开提供商都需要确认对话框。 ### 助手 — 向您的运行提问  右侧导航栏（在顶部栏中切换 ✦）是一个聊天，**读取您的跟踪**。询问“花费了多少？”、“错误率是多少？”，“哪个模型的成本最高？”，或“总结我的工具使用情况”，它会立即通过计算您的数据回答 —— 无需 API 密钥。在特定运行的页面上，它可以回答有关**该**运行的问题（“为什么这花费这么多？”）。在设置中连接一个模型，开放式问题会被路由到它，令牌流式传输，并附带您的运行上下文 —— 包括到本地 Ollama 模型，因此您可以询问您的代理而无需任何字节离开您的机器。 --- ## 记录代理的工作原理 AgentGlass 暴露了两个与提供商自己的端点镜像的端点： | 端点 | 镜像 | 设置 | |----------|---------|-----| | `POST /v1/messages` | Anthropic Messages API | `ANTHROPIC_BASE_URL=http://localhost:4319` | | `POST /v1/chat/completions` | OpenAI Chat Completions | `OPENAI_BASE_URL=http://localhost:4319/v1` | 当您的代理调用其中一个端点时，AgentGlass **将请求转发到真实提供商**（保留流式传输），读取 JSON 或 SSE 响应中的令牌使用情况，为其定价，记录为一个跨度 —— 然后将提供商的响应**完全不变**地返回给您的代理。记录是完全有保证的：AgentGlass 中的错误永远不会更改或破坏您的代理接收的响应。 连续调用被分组到一个单独的**跟踪**（一个代理任务）中，要么通过明确的 `x-agentglass-session` 头部，要么通过一个短暂的空闲窗口，以便多步骤代理运行显示为一个连贯的树形结构而不是分散的调用。 ### 工具调用，无需仪表盘 代理只看到 LLM 请求 —— 它从不监视工具执行。它通过读取对话双方的内容得到工具树： ``` ┌── 请求 ──────────┐ ┌── 响应 ─────────────┐ │ “修复身份验证测试” │ → │ 文本 + tool_use(read_file) ← 调用开启 └─────────────────────┘ └─────────────────────────┘ ⋮ 代理运行工具 ┌── 下一个请求 ─────────────────┐ │ …，tool_result(read_file) → ok │ ← 调用关闭 └─────────────────────────────────┘ ``` 从每个响应中解析出工具调用（Anthropic `tool_use` 块，OpenAI `tool_calls`，流式或非流式）并保存，直到其结果出现在代理的下一个请求中。然后写入**工具跨度**，从 LLM 响应完成到下一个请求到达的时刻 —— 精确地说是代理执行它的窗口。并行工具调用共享该窗口，因为情况就是如此。 因此，将 Claude Code 或任何使用工具的代理指向 AgentGlass 可以为您提供完整的 `llm → tool → llm` 瀑布流在检查器中。**零代码更改，零 SDK，零装饰器。只需一个基准 URL。** ### 它知道哪些模型 大约 90 个模型来自 **Anthropic、OpenAI、Google、xAI、DeepSeek、Meta、Mistral、Qwen、Cohere 和 Amazon**，按最长前缀匹配，以便过时的 ID（`claude-opus-4-8-20260101`）或带前缀的 ID（`anthropic.claude-sonnet-5`）正确解析，未发布的版本仍按其家族定价。缓存读取和写入按其各自的费率计费 —— 这很重要，因为代理循环不断写入缓存，而 Anthropic 收取 1.25 倍的输入费用。 任何支持 `/v1/chat/completions` 的工具 —— **OpenRouter、LiteLLM、Groq、Together、Gemini 的 OpenAI 兼容端点、vLLM、Ollama** —— 今日通过 OpenAI 路由记录并按同一表格定价。 ## 功能 | | | |---|---| | 🛰️ **记录代理** | Anthropic- 和 OpenAI 兼容端点，透明转发和记录 — 流式传输保留。 | | 🔧 **工具调用，无需仪表盘** | 从代理流量中重建完整的 `llm → tool → llm` 树。无需 SDK，无需装饰器。 | | 🌲 **跟踪资源管理器** | 每个运行作为跨度的树：LLM 调用、工具执行、事件。 | | 🔬 **运行检查器** | 瀑布流时间线、上下文窗口图表、每步令牌和成本、完整输入/输出。 | | 💸 **令牌和成本核算** | ~90 个模型，涵盖 10 个提供商，缓存读取和写入单独定价，按步骤和运行汇总。 | | ⚡ **实时流** | 运行在仪表盘中实时显示，通过 WebSocket。 | | 🔀 **运行差异** | 并排比较两个运行 — 成本、令牌、延迟、跨度。 | | 📈 **分析** | 随时间变化的花费、活动热图、按模型和工具分类、CSV 导出。 | | 🤖 **询问运行的助手** | 本地回答有关跟踪的问题；或连接 13 个提供商中的任意一个 — 流式传输令牌。 | | 🧹 **保留** | 默认保留所有内容；选择一个窗口，旧运行会自动修剪。 | | 🔒 **本地和密封** | 在您的机器上运行；一个秘密（助手密钥）使用 AES-256-GCM 密封。 | ## 🛠 技术栈 | 层 | 技术 | |-------|-----------| |  | 服务器运行时 — 一个进程提供 API、WebSocket、代理和 UI | |  | 微小、快速的 HTTP + WebSocket 框架 | |  | 内置跟踪存储（WAL）— 无原生模块 | |  | 仪表盘 SPA | |  | 前端构建 + 开发服务器 | |  | 端到端 | 所有图表和可视化都是手工卷积的 SVG — 无需图表库。 ## 架构 ``` agentglass/ src/ 服务器（Node + Hono + node:sqlite） index.ts 入口 — API + WebSocket + 代理 + SPA 主机 proxy.ts 记录代理 — 相关性 + 工具重建 providers.ts 提供商线路格式（代理流经的内容） llm.ts 助手的 LLM 客户端（调用的内容） db.ts 跟踪存储（跟踪 → 跨度，WAL，滚动汇总） sim.ts 模拟器 — 一周现实运行，实时流式传输 assistant.ts 询问运行（本地答案 + 可选 LLM） vault.ts AES-256-GCM 密钥密封 pricing.ts 模型目录 + 令牌定价 retention.ts 旧跟踪修剪 hub.ts / api.ts 事件实时分发 / REST 接口 web/ 仪表盘（Vite + React 19 + TypeScript） src/pages/ 概述、跟踪、跟踪详情、差异、分析... src/components/ 手工 SVG 图表、助手导航栏... scripts/ record-demo.mjs — 重新剪辑顶部的 GIF deploy/ fly.toml 用于只读公共演示 docs/ demo.gif + 本自述中的截图 ``` ## Docker ```bash docker run -p 4319:4319 -v agentglass:/app/data ghcr.io/vugarfamiloglu/agentglass ``` 在 **http://localhost:4319** 上打开。容器提供构建的仪表盘、API、WebSocket 流和记录代理 — 所有端口均在一个端口上。图像在标签上构建和烟雾测试；`docker build -t agentglass .` 在本地也适用。 ## 托管公共演示 托管的 AgentGlass 不能是您本地运行的 AgentGlass：陌生人不应能够清除您的跟踪、写入密钥或通过您的盒子代理他们的代理。`AGENTGLASS_READONLY=1` 提供只读服务并拒绝其余服务 — 无代理、无写入、无模型发现调用，该调用获取调用者提供的 URL，在公共主机上允许任何人从内部探测您的网络。 ```bash fly deploy --config deploy/fly.toml # 只读 + 模拟器，无数据卷 ``` 无需数据卷 — 数据目录保持短暂，因此每次冷启动都会播种一个全新的运行周，并可让演示永远不会变 stale 或无边界。 ## 配置 | 环境变量 | 默认值 | 用途 | |-----|---------|---------| | `AGENTGLASS_PORT` | `4319` | 仪表盘/API/代理端口 | | `AGENTGLASS_DATA` | `data` | SQLite 存储 + 保险库密钥目录 | | `AGENTGLASS_SIMULATE` | `1` | 播种和流式传输模拟运行（设置为 `0` 禁用） | | `AGENTGLASS_READONLY` | `0` | 只提供只读服务 — 用于公共演示（见上文） | | `ANTHROPIC_API_URL` | `https://api.anthropic.com` | 向上游转发 Anthropic 调用 | | `OPENAI_API_URL` | `https://api.openai.com` | 向上游转发 OpenAI 调用 | 一旦您开始提供真实运行，请关闭模拟器（`AGENTGLASS_SIMULATE=0`）。 ## 开发 ```bash npm run dev # 服务器（:4319）和 Vite 开发服务器（:4318）一起 npm run typecheck # 类型检查服务器和网络 npm test # 运行测试套件 npm run build # 构建 SPA + 将服务器编译到 dist/ npm start # 运行生产版本 ``` ## 许可证 [Apache-2.0](LICENSE)