焕德这周我把本地跑 Agent 的调试环境整体切到了 Agent-Sandbox 的新版 UI 上，连续用了快一个月，说实话再让我切回纯命令行界面，我是切不回去了。群里看到那个标题在问“哪些功能是你经常使用的”，我就想借这个机会把这阵子的真实使用体验和踩坑记录整理出来，尤其适合正在做 Agent 开发、工具调用调试、Prompt 迭代这类工作的朋友参考。
这套 UI 解决的并不是“好不好看”的问题，而是把 Agent 执行过程中原本藏在黑盒里的中间状态变成了可见、可点、可干预的面板。以前命令行下面对着 JSON 日志一行行翻，基本靠猜；现在界面里能看到模型怎么想、工具怎么调、参数怎么传、哪一步报错，排查问题的时间能压缩到原来的三分之一左右。如果你也在做 Agent 类应用，或者准备给你的 Agent 框架配一个调试前端，这篇文章里的功能梳理和接入思路可以直接拿走用。
1. 先对齐认知：Agent-Sandbox 是干什么的，UI 版改变了什么
1.1 以前用命令行调试 Agent 最痛的地方
Agent 类应用和普通接口最大的区别在于：它不是一次性输入输出，而是多轮推理、多步工具调用、多种状态反复横跳的过程。一个任务可能包含若干次大模型请求、若干次外部 API 调用，每一步都可能产生分支。命令行环境也不是不能调，但数据展示方式决定了效率上限。
我早期调试一个带搜索和代码执行能力的 Agent，最常做的事就是开好几个终端窗口：一个跑主程序看标准输出，一个 tail 日志文件，还有一个用来手工调测试数据。一旦 Agent 在某个工具调用环节返回了意外结果，就得从几百行 JSON 日志里定位是模型返回的 tool_call 参数出问题，还是下游接口把参数截断了。这个定位过程消耗的时间往往比改代码本身还多。
命令行输出对短文本很友好，但对树状调用链和多轮状态流并不友好。你很难一眼看出当前轮次的 system prompt 是什么、上下文被塞进了哪些内容、工具返回后模型有没有正确消费这段数据。更麻烦的是，某个中间节点的状态如果你想改一版重新测，在命令行里通常要改代码、重启进程、重新构造输入，整个循环非常重。
1.2 UI 版核心改动：从“看日志”变成“看执行现场”
Agent-Sandbox 的 UI 版本本质上是把原来日志里记录的离散事件，重组成了一条可观察、可回放、可修改的执行链。界面不会替你解决 Agent 本身的逻辑问题，但它能让问题暴露的位置精确到具体某一轮消息、某一个工具参数。
我理解的设计思路是：Agent 运行过程中的每一个关键节点都被定义成结构化事件，包括请求开始、模型返回、工具调用发起、工具结果回传、上下文更新、最终回复生成等。UI 再把事件按时间顺序和调用关系组织成一张时间线，挂在相应会话下。这就好比以前你只能看文字版的行车记录仪，现在能看到车在哪个路口转弯、打了多少方向、遇到什么障碍物，还可以踩住刹车回放细节。
这套交互带来的最大好处，是“中间状态可干预”。在 UI 里可以直接停到某一个工具调用节点，修改传入参数再重新执行，不需要改业务代码；也可以把某一次 Prompt 输入临时替换成测试版本，对比模型反应差异。这些操作在命令行阶段基本属于“想想就好”的奢望。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 界面设计的几个关键取舍：一个“Agent 调试器”的 UI 该怎么布局
2.1 三个主区域：会话列表、运行状态、事件详情
Agent-Sandbox 的 UI 布局我整体看下来是一个“左-中-右”三栏结构，和常见聊天工具类似，但它承载的信息密度比聊天工具高很多。
左侧是会话和用例列表，用来切换不同的调试任务。中间区域是主运行视图，展示当前会话的消息往返和 Agent 状态流转。右侧是细节面板，当你选中某一个