把AI智能体调试变成聊天：AgentScope Studio运行时可视化与实时用户输入托管完全指南

• 人工智能
• AI 应用
• 可观测性
• 链路追踪
• 数据可视化
• AI 评测
• 前端
• 后端

AgentScope Studio是一个专为 AI 智能体开发打造的本地可视化调试工具，核心能力是运行时可视化与实时用户输入托管：它把智能体的一次次运行变成聊天窗口，把每一次大模型调用、工具执行变成可点击的追踪链路，让你在浏览器里就能完成开发、调试和评测。本文带你 5 分钟看懂这套工具的完整玩法。

一、它解决了智能体开发的什么痛点？

调试 AI 智能体时，大家通常面对这样的困境：

• 黑盒运行：智能体在命令行跑，只能看日志猜"它到底干了什么"；
• 交互割裂：智能体需要用户输入时，程序阻塞等待，只能回到终端敲键盘；
• 链路难查：一次回复背后有多轮 LLM 调用和工具执行，token 消耗、耗时全凭猜测。

AgentScope Studio 的思路是把这三件事全部搬到浏览器里，以Chatbot 风格的界面呈现智能体的运行过程，并基于OpenTelemetry协议接收追踪数据。它的技术栈为：

📖 更多架构细节见 docs/tutorial/zh_CN/tutorial/overview.md。

二、快速上手：3 步启动可视化调试台

前置要求：Node.js ≥ 20.0.0、npm ≥ 10.0.0。

第 1 步：从 NPM 一键安装（推荐方式）：

npm install -g @agentscope/studio # 启动 AgentScope-Studio as_studio

第 2 步：在你的 AgentScope 应用中指定 Studio 地址完成连接：

import agentscope agentscope.init( # 替换为你启动 AgentScope-Studio 的端口 studio_url="http://localhost:3000", )

第 3 步：打开浏览器访问http://localhost:3000，运行实例、聊天界面和追踪数据就会实时出现在页面上。

💡 也可选择 Docker 部署（见 docker/README.md）或从源码启动。完整的安装与配置说明参考 docs/tutorial/zh_CN/tutorial/quick_start.md。

三、运行时可视化：像刷聊天窗口一样调试智能体

运行可视化是 AgentScope Studio 最直观的亮点。项目页面按Projects（项目）→ Runs（运行实例）两级组织你的可观测数据：一个项目下按时间顺序堆叠着每次运行实例，点击任意一条，即可在 Chatbot 风格的界面中查看该次运行的完整交互历史与状态。

在上面的示例中，你可以看到：

• 左侧：运行实例列表，实时显示每条运行的状态（Done / Running / Error）；
• 中间：User 与智能体的多轮对话气泡，工具调用、回复内容逐条流式呈现；
• 右侧 Data View：切换 RUN / MESSAGE / TRACE 三个标签页，查看运行状态、模型调用次数、Token 消耗分布等统计数据。

一个容易上手的细节：智能体的一次回复（调用一次reply）实际上会产生多条消息（提示消息、工具结果等），因此 Studio 在消息之上引入了reply（回复）概念，将多条消息组织为一个完整的回复单元，你可以按replyId或msg.id灵活切换查看粒度。

📖 相关设计说明参考 docs/tutorial/zh_CN/develop/project.md。

四、实时用户输入托管：智能体不再干等终端输入

这是 AgentScope Studio 最具"托管"感的特性：当 AgentScope 应用连接到 Studio 后，智能体需要用户输入时，Studio 会自动在网页端弹出输入框，并通过 WebSocket 把内容实时推送回 Python 智能体。你不再需要盯着终端，直接在浏览器里回复智能体即可。

它支持在同一个运行实例中包含多个UserAgent实例，实现多用户协同交互的场景。整个交互流程如下：

流程拆解为 6 步：

1. Agent 发送请求：智能体通过POST /trpc/requestUserInput向 Studio 服务器发起输入请求；
2. 服务器保存并推送：Studio 将请求落库，并经 WebSocket 推送到 Web 客户端；
3. 用户输入：用户在网页界面上以指定角色输入内容；
4. 客户端回传：Web 客户端通过 WebSocket 把输入发回服务器；
5. 服务器校验转发：服务器验证后转发给智能体的 WebSocket 连接；
6. Agent 接收续跑：智能体拿到输入，继续执行。

服务端的核心路由与 Socket 事件分发逻辑可查看 packages/server/src/trpc/socket.ts。此外，输入请求还支持structuredInput字段，即按 JSON Schema 生成结构化输入表单，适合表单类、选择题类的人机交互。

如果你不想用 AgentScope 框架，也可以直接按三个 API 对接：

五、Trace 追踪：看穿每一次大模型调用与工具执行

除了聊天窗口，Studio 的 Trace 页面基于OpenTelemetry 语义规范和OTLP 协议，把智能体运行时的每个环节变成可钻取的调用树：LLM 调用、Agent 调用、工具调用、输入输出、执行耗时一目了然。

概览页列出所有上报到 Studio 的链路，鼠标悬停在链路名称后的图标上即可查看 Trace ID 等元信息。

点击进入详情页，可以看到链路的调用顺序与层级关系，并查看每次调用详细的输入输出：

对于 LLM、Agent 这类 AI 调用，输入输出按 OpenTelemetry 生成式 AI 语义规范的结构化方式展示；Function、Format 等常规调用则遵循 AgentScope 扩展语义规范。在All Attributes区域，你能看到本次调用的全部关键元信息：

📖 完整的语义规范定义与集成方式（包括 LoongSuite / OpenTelemetry 探针接入）见 docs/tutorial/zh_CN/develop/tracing.md。

六、开箱即用的内置智能体：Friday

如果你还没有自己的智能体项目，Studio 内置了一个由 AgentScope 构建的实验性智能体Friday，可以直接用来体验上述全部能力，也适合作为二次开发的起点：

• 回答 AgentScope 相关问题，充当开发助手；
• 支持元工具（meta tool）、实时操控/中断、会话状态管理；
• 规划可视化、长期记忆等高级功能持续接入中。

首次使用时在设置页配置模型、API KEY 与工具参数即可开聊：

Friday 的完整源码也开源在仓库中，入口是 packages/app/friday/main.py，其中hook.py负责把消息实时推送到 Studio 前端，utils/connect.py维护用于实时操控与中断的 WebSocket 连接，是学习"如何把智能体接入 Studio"的最佳样例。

七、写在最后

把智能体调试"聊天化"，本质是让运行时可视化回答"它做了什么"，让实时用户输入托管解决"它等我做什么"，再配合 OpenTelemetry 级的 Trace 数据回答"它做得怎么样"。AgentScope Studio 把这三件事打包进了一个本地部署、零成本起步的工具里。

👉 建议的体验路径：先按第二节的三步启动 Studio → 用内置 Friday 跑一轮对话感受运行时可视化 → 再看 Trace 页面理解调用链路 → 最后在自己的 AgentScope 应用里加上studio_url参数完成接入。

• 人工智能
• AI 应用
• 可观测性
• 链路追踪
• 数据可视化
• AI 评测
• 前端
• 后端