1. 为什么我要给 Agent 单独做一个网站先说结论这个项目的出发点特别朴素——我受够了每次调试 Agent 都要在聊天窗口、终端、文档、日志之间来回横跳。一个 Agent 跑起来它到底调了哪些工具、每一步的输入输出是什么、哪一步开始跑偏、哪个 skill 加载失败全靠我肉眼在滚动的文本里扒。扒一次两次还行天天扒就是纯折磨。所以我做了个专门给 Agent 用的网站核心就两件事把 Agent 的运行过程可视化以及把 skills 做成可管理、可测试、可复用的模块。它不是一个聊天前端也不是又一个 Agent 框架而是一个工作台——你把自己的 Agent 接进来它负责展示、调试、管理技能、回放执行链路。这个网站适合谁三类人。第一类是正在做 Agent 开发的工程师尤其是被调试链路折磨过的第二类是想搞清楚 Agent 到底怎么运转的产品和测试同学他们不需要写代码但需要看懂 Agent 在干什么第三类是把 skills 当成资产来积累的团队技能库越攒越多没有管理工具迟早乱成一锅粥。我踩过的最大一个坑是一开始想把它做成大而全的 Agent 平台结果发现方向错了。Agent 框架已经够多了我再造一个没有意义。真正缺的不是框架是围绕 Agent 的观测和管理层。想清楚这一点之后整个项目的设计就顺了。2. 整体设计思路与架构拆解2.1 核心定位做 Agent 的仪表盘而不是发动机我给自己定的第一条原则是不碰 Agent 的推理逻辑。你的 Agent 用什么框架、用什么模型、怎么编排我都不管。网站只做一件事——通过一套标准接口接收 Agent 上报的运行事件然后把它渲染成人能看懂的东西。这个定位的好处非常明显。第一接入成本低你不需要改 Agent 的核心代码只要在关键节点埋几个上报点。第二不会被框架绑架今天你用这个框架明天换那个网站照样能用。第三职责清晰出问题的时候我知道该去 Agent 那边查还是来网站这边查。打个比方Agent 是发动机我这个网站是仪表盘。仪表盘不参与燃烧但它告诉你转速多少、油温多高、哪个缸在抖。没有仪表盘发动机也能转但你不敢开快。2.2 三层架构接入层、处理层、展示层整个系统我拆成了三层这个分层是反复调整后才定下来的。接入层负责和 Agent 通信。我选的是 HTTP SSE 的组合。为什么不用 WebSocket因为 Agent 的事件流本质上是单向的、服务端推给前端的SSE 足够用而且实现简单、断线重连逻辑清晰、对代理和网关友好。Agent 那边通过一个轻量的 SDK 把事件 POST 过来前端通过 SSE 订阅实时流。处理层负责事件的解析、存储和聚合。这里有个关键决策事件是先落库再推送还是先推送再落库我选了先落库。原因是调试场景下事件的完整性比实时性重要得多。如果先推送一旦前端断开这段事件就丢了回放的时候链路是断的。先落库虽然多一次写操作但保证了任何时候都能完整回放。展示层就是前端。我用了组件化的思路把执行链路技能面板事件详情回放控制拆成独立组件各自订阅自己关心的数据。这样后续加新视图的时候不用动老代码。2.3 为什么 skills 要单独拎出来做管理skills 这个词现在被用得很泛但在我的项目里它有明确定义一段可被 Agent 调用的、有明确输入输出契约的能力单元。它可以是一个提示词模板可以是一段工具调用封装也可以是一个多步骤的子流程。我把它单独做管理是因为在实际项目里 skills 的生命周期特别长而且复用率极高。一个团队做 Agent真正写死的业务逻辑没多少大部分时间都在攒 skills、调 skills、测 skills。如果没有一个地方统一管理就会出现这些问题同一个 skill 被复制了五份改了一份忘了另外四份skill 的输入输出没人说得清接进去才发现参数对不上skill 改了之后不知道会不会影响已经在跑的 Agent。所以网站里的 skills 模块我给它设计了四个能力注册、版本管理、在线测试、依赖查看。注册解决有没有的问题版本管理解决改了会不会崩的问题在线测试解决接进去之前先验一遍的问题依赖查看解决这个 skill 到底依赖了啥的问题。2.4 技术选型背后的取舍前端我用了主流框架加组件库没有追求最新最炫。原因很实际这个工具是给自己和团队用的稳定压倒一切。我见过太多内部工具因为用了实验性技术结果维护成本比业务代码还高。后端我选了轻量级的方案数据库用的是关系型。有人会问事件流这种数据不是应该用时序库或者文档库吗我的考虑是事件量在调试场景下并不大一个 Agent 跑一次可能就几百到几千条事件关系型完全扛得住而且查询灵活、事务可靠、运维简单。等真到了需要时序库的量级再换也不迟接口层已经隔离好了。实时推送用 SSE 前面说过了。这里补一个细节SSE 的连接我做了心跳保活每 15 秒发一个注释行防止中间的网络设备把空闲连接掐掉。这个坑我在别的项目里踩过连接莫名其妙断掉查了半天才发现是网关的超时设置。3. 核心细节解析与实操要点3.1 事件模型设计Agent 到底该上报什么这是整个项目最核心的设计也是最容易做错的地方。事件模型设计得好后面一切都顺设计得烂前端再漂亮也是空中楼阁。我把事件分成了几大类。生命周期事件Agent 启动、结束、异常退出。步骤事件每一步推理的开始和结束包含输入、输出、耗时。工具调用事件调用了哪个工具、传了什么参数、返回了什么。技能事件加载了哪个 skill、版本是多少、执行结果如何。错误事件任何环节出错都归到这里带上堆栈和上下文。每条事件我都强制要求几个字段trace_id整条链路的唯一标识、span_id当前步骤的标识、parent_span_id父步骤标识、timestamp、type、payload。前四个字段构成了链路追踪的基础缺一不可。提示parent_span_id这个字段千万别省。没有它你只能看到一串平铺的事件看不出调用层级。有了它前端才能渲染出树状的执行链路一眼就能看出哪一步嵌套在哪一步里面。这里有个实操心得payload 不要塞太大的东西。我一开始把完整的模型输入输出都塞进 payload结果一条事件几 MB数据库很快就撑不住了。后来改成只存摘要和引用大内容单独存对象存储事件里只放一个指针。这个改动让存储成本降了一个数量级。3.2 skills 的契约定义输入输出必须说清楚skills 管理最容易糊弄的地方就是契约。很多人写 skill 就是一段提示词输入输出全靠约定俗成接进去才发现各种对不上。我在项目里强制要求每个 skill 必须声明输入输出的 schema。输入 schema 描述这个 skill 需要哪些参数、每个参数什么类型、是否必填、有没有默认值。输出 schema 描述它会返回什么结构。这两个 schema 不只是文档它们会被真正用于校验——skill 注册的时候校验 schema 合法性调用的时候校验参数是否符合返回的时候校验结果是否匹配。这样做的好处是skill 变成了一个有契约的组件而不是一段大概能用的文本。团队协作的时候别人看 schema 就知道怎么用不用来问你。测试的时候可以基于 schema 自动生成测试用例。我还加了一个示例字段每个 skill 可以附上几个典型的输入输出样例。这个字段在在线测试的时候特别有用一键填充示例省得每次手敲参数。3.3 实时链路渲染怎么让执行过程看得懂前端渲染执行链路我试过三种方案。第一种是纯文本日志流最简单但信息密度低找问题靠眼睛扫。第二种是时间轴按时间顺序排列事件比纯文本好一点但看不出调用层级。第三种是树状结构按parent_span_id组织成调用树这是最终采用的方案。树状结构的好处是层级一目了然。一个 Agent 的执行过程本质上就是一棵调用树根节点是这次运行下面挂着各个步骤步骤下面挂着工具调用和技能执行。展开收起、点击查看详情、按类型过滤这些交互都建立在树结构之上。但树结构也有个问题长链路会很长。一个复杂的 Agent 跑下来树可能有几百个节点。我的处理是默认折叠深层节点只展开到第二层用户点开才继续展开。同时提供只看错误只看工具调用这类过滤快速定位关心的部分。注意渲染大量节点的时候一定要做虚拟滚动。我一开始没做几百个节点直接把页面卡死。后来上了虚拟列表只渲染可视区域内的节点流畅度立刻上来了。3.4 回放机制把一次运行完整重演回放是我个人最喜欢的功能。调试的时候经常遇到这种情况Agent 跑完了结果不对但过程已经滚过去了只能重新跑一遍。有了回放我可以把任意一次历史运行完整重演一步步看它是怎么走到错误结果的。回放的实现基于前面说的先落库策略。每次运行的所有事件都完整存着回放的时候按时间顺序重新播放。我做了播放控制播放、暂停、单步、跳转、调速。单步特别有用可以一条一条事件地看配合详情面板把每一步的输入输出都看清楚。回放还有一个隐藏价值对比。同一个任务跑两次结果不一样可以把两次回放并排放在一起对比看是哪一步开始分叉的。这个功能帮我定位过好几次偶发失败的问题最后发现是某个工具调用的返回不稳定导致的。4. 实操过程与核心环节实现4.1 从零接入一个 Agent 的完整流程假设你有一个已经能跑的 Agent想接进这个网站完整流程是这样的。第一步在网站上创建一个应用拿到一个应用 ID 和接入密钥。这个应用对应你的一个 Agent 项目所有事件都归属到这个应用下。第二步在你的 Agent 代码里引入 SDK。SDK 很轻核心就是几个上报方法。我在设计 SDK 的时候刻意做得很薄因为它要嵌入到别人的代码里越薄侵入性越小。第三步在关键节点埋点。最少要埋三个Agent 启动、Agent 结束、每次工具调用。这三个点埋上链路的基本骨架就有了。想更细的话可以在每次模型调用前后也埋上。第四步配置上报地址和密钥跑一次 Agent去网站上看事件有没有上来。如果没上来先查网络再查密钥最后查 SDK 版本。第五步根据看到的内容调整埋点。第一次接入几乎不可能一次到位总会发现某些关键信息没上报。看着链路图去补埋点效率最高。4.2 一个最小可用的埋点示例下面这段是伪代码展示埋点的基本形态。不同语言和框架写法不同但思路一致。from agent_insight import Tracer tracer Tracer(app_idyour_app_id, api_keyyour_key) def run_agent(task): with tracer.trace(agent_run, inputtask) as run: # 第一步规划 with run.span(planning) as span: plan llm_plan(task) span.set_output(plan) # 第二步执行 for step in plan.steps: with run.span(execute_step, inputstep) as span: result execute(step) span.set_output(result) return run.output这段代码的关键在于with上下文管理器。进入的时候自动上报开始事件退出的时候自动上报结束事件中间抛异常的话自动上报错误事件。用上下文管理器能保证事件不丢哪怕代码中途 return 或者抛异常。提示span是可以嵌套的。上面代码里execute_step嵌套在agent_run里面上报的时候parent_span_id会自动指向父级。嵌套层级理论上不限但实际用下来三层以内最清晰太深了反而难读。4.3 skills 的注册与测试实操注册一个 skill我设计了两种方式。一种是在网站上填表单适合简单的提示词类 skill。另一种是上传配置文件适合复杂的、带代码的 skill。配置文件我用的是 YAML因为可读性好非技术人员也能看懂。一个典型的 skill 配置长这样name: summarize_text version: 1.0.0 description: 把长文本压缩成指定长度的摘要 inputs: - name: text type: string required: true - name: max_length type: integer required: false default: 200 outputs: - name: summary type: string examples: - input: text: 很长的一段文本... max_length: 100 output: summary: 压缩后的摘要注册之后网站会自动校验 schema然后生成一个测试入口。测试的时候你可以手动填参数也可以一键加载示例。点执行网站会真的去调用这个 skill把结果展示出来同时记录这次测试的输入输出。这里有个我特别想强调的点skill 的测试要和真实调用走同一套代码路径。我见过一些项目测试环境是一套逻辑生产是另一套测的时候好好的上线就崩。我的做法是测试入口直接调用 skill 的正式执行函数只是把结果额外记录下来保证测的就是跑的。4.4 版本管理与灰度skills 改版本是家常便饭但改版本最怕的就是把正在跑的 Agent 搞崩。我的方案是版本不可变 引用指定版本。具体来说一个 skill 一旦发布了某个版本这个版本的内容就冻结了不能再改。要改就发新版本。Agent 引用 skill 的时候必须指定版本号比如summarize_text1.0.0。这样即使 skill 发了 2.0.0正在用 1.0.0 的 Agent 完全不受影响。想升级的时候先把 Agent 的引用改成新版本在测试环境跑一遍没问题再上生产。这个过程就是灰度。网站里可以看到每个 skill 版本被哪些应用引用了升级之前先看看影响范围心里有数。注意千万别做浮动版本就是那种不指定具体版本、永远用最新的引用方式。短期看方便长期看是灾难。某天有人改了个 skill所有引用它的 Agent 行为全变了你还不知道是谁改的。5. 常见问题与排查技巧实录5.1 事件上报了但前端看不到这是接入阶段最高频的问题。排查顺序我总结成了一张表排查点检查方法常见原因网络连通在 Agent 机器上 curl 上报地址防火墙、DNS、地址写错密钥有效看上报接口返回的状态码密钥过期、应用 ID 不匹配事件格式看接口返回的错误信息字段缺失、类型不对前端订阅看浏览器控制台的 SSE 连接连接被断、订阅了错误的应用落库情况直接查数据库写库失败、事务回滚我遇到最多的是密钥问题。有一次排查了半天最后发现是复制密钥的时候多带了一个空格。这种低级错误特别浪费时间所以后来我在 SDK 里加了密钥格式的本地校验格式不对直接报错不浪费网络往返。5.2 链路树渲染错乱链路树错乱八成是parent_span_id的问题。常见的有三种一是父节点还没上报子节点先到了导致找不到父级二是span_id重复两个不同的步骤用了同一个 ID三是跨线程或者异步的时候上下文没传递对子节点挂到了错误的父级上。第一种情况我的处理是延迟挂载。子节点先到的先存着等父节点到了再挂上去。如果父节点一直没来就挂到根节点下并标记为孤儿节点提醒用户检查埋点。第二种情况span_id的生成一定要用全局唯一的方式别用自增或者时间戳并发下必冲突。我用的是 UUID。第三种情况最隐蔽本质是上下文传递的问题。异步场景下span的上下文必须跟着任务走不能存在全局变量里。这个坑我在写 SDK 的时候专门处理了用上下文变量而不是全局状态。5.3 skill 测试通过但线上失败这个问题我遇到过好几次原因基本都在环境差异上。测试的时候用的是测试的模型、测试的工具、测试的数据线上是另一套。skill 本身没问题是它依赖的东西变了。我的应对是给 skill 的依赖也做声明。一个 skill 依赖了哪个模型、哪个工具、哪个外部服务都在配置里写清楚。测试的时候网站会检查这些依赖在当前环境下是否可用。如果测试环境和生产环境的依赖不一致会给出警告。还有一个原因是输入数据的边界。测试的时候用的是示例数据线上来的是真实数据格式、长度、编码都可能不一样。所以我在 skill 的输入校验上做得比较严不符合 schema 的直接拒绝而不是让它带着脏数据往下跑。5.4 性能问题事件太多导致卡顿Agent 跑得越复杂事件越多前端越容易卡。我总结了几条优化经验。第一分页加载。不要一次性把所有事件都拉下来按需加载。链路树默认只加载顶层节点展开的时候再拉子节点。第二虚拟滚动。前面提过可视区域外的节点不渲染。第三事件聚合。同类型的、连续的、没有实质差异的事件可以合并展示。比如一个循环调用了同一个工具 100 次没必要展示 100 个节点聚合成一个调用了 100 次的节点点开才展开。第四后端预聚合。有些统计信息比如总耗时、各阶段耗时占比在后端算好再给前端别让前端去遍历所有事件算。提示性能优化要基于真实数据。我一开始凭感觉优化优化了半天没效果。后来导了一份真实的大链路数据profile 了一下才发现瓶颈在某个不起眼的渲染函数上。没有数据支撑的优化都是瞎猜。5.5 多 Agent 协作时的链路串联单个 Agent 的链路好办多个 Agent 协作的时候就麻烦了。A Agent 调用了 B AgentB 又调用了 C怎么把这三条链路串起来我的方案是传递 trace_id。A 启动的时候生成一个 trace_id调用 B 的时候把这个 trace_id 传过去B 上报事件的时候带上这个 trace_id。这样在网站上同一个 trace_id 下的所有事件不管来自哪个 Agent都能串成一条完整的链路。实现上trace_id 通过调用参数传递。如果是 HTTP 调用放在 header 里如果是函数调用放在参数里。关键是每个 Agent 都要支持接收上游的 trace_id而不是自己重新生成一个。这个机制做好之后多 Agent 协作的调试体验提升巨大。以前要开好几个窗口分别看现在一个视图看全链路谁调用了谁、哪一步慢、哪一步出错清清楚楚。6. 我在这个项目里踩过的坑和攒下的经验做这个项目大半年踩的坑比写的代码还多挑几个最有代表性的说说。第一个坑是过度设计。一开始我想把事件模型设计得无比通用什么类型的事件都能装。结果 schema 复杂到我自己都记不住接入的人更是一头雾水。后来砍掉了大半字段只保留真正必要的反而好用了。通用性是个陷阱够用就行。第二个坑是忽视非功能需求。我一开始只关注功能没考虑性能、没考虑安全、没考虑运维。等到事件量上来、有人开始问权限问题、部署出问题的时候才发现这些都得补。现在我养成了一个习惯做任何功能之前先想三件事量大了怎么办、出错了怎么办、别人怎么用。第三个坑是文档滞后。代码改了文档没改接入的人照着老文档做做不通来问我我才发现文档过期了。后来我把文档和代码放在一起改代码必须改文档review 的时候一起看。虽然麻烦但省了后面无数次的重复解释。第四个坑是测试数据不真实。我用自己造的假数据测了很久觉得挺完善。结果一接真实 Agent各种边界情况全冒出来了。真实数据永远比你想象的脏、比你想象的长、比你想象的怪。有条件的话尽早用真实数据测。攒下的经验也有几条。接口要稳定一旦发布就别轻易改改就要做好版本兼容。错误信息要具体别只说出错了要说清楚哪里错了、为什么错、怎么改。日志要打全出问题的时候日志是唯一的线索。给自己留后路任何可能失败的操作都要有回滚方案。最后分享一个我个人的小习惯每次解决完一个棘手的问题我都会花五分钟把它记下来记在一个专门的问题库里。这个库现在有几百条了很多问题后来都重复遇到过翻一下记录就能解决省了大量时间。做工具的人自己首先得是个会攒工具的人。这个网站后续我还在加东西比如基于历史链路的自动分析、skill 的推荐、异常模式的识别。但核心思路不会变让 Agent 的运行过程变得可见、可懂、可控。Agent 越复杂这个需求就越强烈。把观测和管理这件事做好比再造一个 Agent 框架有价值得多。