Agent Scope Java 2.x 系列【40】Harness：接入 Studio 可视化平台

文章目录

[1. AgentScope Studio](#1. AgentScope Studio)
- [1.1 项目介绍](#1.1 项目介绍)
- [1.2 核心功能](#1.2 核心功能)
- [1.3 安装指南](#1.3 安装指南)
- - [1.3.1 前置环境要求](#1.3.1 前置环境要求)
  - [1.3.2 方式一：NPM 全局安装（推荐）](#1.3.2 方式一：NPM 全局安装（推荐）)
  - [1.3.3 方式二：源码编译运行](#1.3.3 方式二：源码编译运行)
  - [1.3.4 方式三：本地NPM安装](#1.3.4 方式三：本地NPM安装)
[2. agentscope-extensions-studio](#2. agentscope-extensions-studio)
- [2.1 模块介绍](#2.1 模块介绍)
- [2.2 核心组件](#2.2 核心组件)
[3. 简单接入](#3. 简单接入)
- [3.1 启动 Studio 服务](#3.1 启动 Studio 服务)
- [3.2 引入依赖](#3.2 引入依赖)
- [3.3 接入控制器](#3.3 接入控制器)
- [3.4 application.yml](#3.4 application.yml)
- [3.5 配置 StudioMessageHook](#3.5 配置 StudioMessageHook)
[4. 可观测性接入](#4. 可观测性接入)
- [4.1 TelemetryTracer](#4.1 TelemetryTracer)
- [4.2 追踪后台接入路径](#4.2 追踪后台接入路径)
- - [4.2.1 路径 A：接了 Studio 就自动有追踪](#4.2.1 路径 A：接了 Studio 就自动有追踪)
  - [4.2.2 路径 B：独立使用](#4.2.2 路径 B：独立使用)
- [4.3 查看追踪数据](#4.3 查看追踪数据)

1. AgentScope Studio

1.1 项目介绍

AgentScope Studio 是一款面向 AgentScope 开发者的本地可视化工具集。它可以透明、简洁、高效地对智能体应用进行开发、调试与效果评测。

1.2 核心功能

导航菜单 ：首页、运行实例、调用链路、Friday 助手。

项目管理 ：支持多项目管理，统一管理工程与每一轮运行任务（Projects & Runs）。

运行时可视化：对话式界面，实时查看智能体交互全过程。

链路追踪（Tracing） ：基于 OpenTelemetry 实现调用链路可视化，可观测大模型调用、Token 消耗、智能体互相调用全流程。

智能体评测：提供统计维度的数据面板，面向效果评估做量化分析。
内置开发助手 Friday ：集成开发 Copilot，支持快速二次开发调试，同时作为高级能力的集成入口。

1.3 安装指南

1.3.1 前置环境要求

Node.js >= 20.0.0
npm >= 10.0.0
Docker（可选，用于容器部署）

💡 提示：如果你使用 nvm 管理版本，执行 nvm use 即可自动切换到对应 Node 版本。

版本校验命令：

bash 复制代码

node --version  # 输出 v20.x.x 及以上版本
npm --version   # 输出 10.x.x 及以上版本

1.3.2 方式一：NPM 全局安装（推荐）

bash 复制代码

npm install -g @agentscope/studio
# 启动工具
as_studio

1.3.3 方式二：源码编译运行

bash 复制代码

git clone https://github.com/agentscope-ai/agentscope-studio
cd agentscope-studio
npm install
# 开发模式启动
npm run dev

1.3.4 方式三：本地NPM安装

bash 复制代码

npm install -g @agentscope/studio
# 启动命令
as_studio

2. agentscope-extensions-studio

2.1 模块介绍

agentscope-extensions-studio 是 agentscope-extensions 的子模块，主要负责：

AgentScope Studio 集成：把 agent 的对话实时推到 Studio Web 界面做可视化，并支持 Web 端人机交互（HITL）。
OpenTelemetry 链路追踪：把 agent / 模型 / 工具调用按 GenAI 语义约定埋点并经 OTLP 导出。

2.2 核心组件

类	作用
`StudioManager`	入口与生命周期。`init()` 拿 Builder，`initialize()` 建立 HTTP + WebSocket 连接；`getClient()/getWebSocketClient()/getConfig()/isInitialized()/shutdown()`。
`StudioConfig`	配置项：`studioUrl`、`tracingUrl`、`project`、`runName`、`maxRetries`、`reconnectAttempts`。
`StudioClient`	REST 客户端（OkHttp，tRPC 风格端点）：`registerRun()`、`pushMessage(Msg)`、`requestUserInput(...)`，全部返回 `Mono`。
`StudioWebSocketClient`	基于 socket.io 的实时双向通道（推送 / 接收）。
`StudioMessageHook implements Hook`	核心集成点：拦截 `PostCallEvent`（agent 产出回复后触发），把输出消息推给 Studio。推送失败只记日志、不打断 agent 执行。
`StudioUserAgent`	人类用户代理（HITL）：可走终端/控制台输入（默认），或在启用 Studio 时走 Web 界面输入。

3. 简单接入

3.1 启动 Studio 服务

AgentScope Studio 后台是一个独立的 Node.js 应用，要先单独起起来，Java 端再连它，上面已经说明了各种启动方式。

端口要分清（开发模式有坑）：

开发模式 （npm run dev）：浏览器 UI 在 http://localhost:5173 ，后端 API 连接地址在 http://localhost:3000。
生产模式 （npm run build 后 / as_studio）：3000 会托管前端，UI 与后端同在 http://localhost:3000。

3.2 引入依赖

xml 复制代码

        <!-- AgentScope Studio 扩展：可视化 + OpenTelemetry 追踪 -->
        <dependency>
            <groupId>io.agentscope</groupId>
            <artifactId>agentscope-extensions-studio</artifactId>
            <version>2.0.0-RC4</version>
        </dependency>

3.3 接入控制器

根据配置项决定是否建立与可视化平台的长连接，生成消息拦截 Hook，把所有 Agent 对话自动上报到 Studio 面板；关闭时完全静默，不影响主程序运行。

java 复制代码

@Component
public class StudioSupport {

    private static final Logger log = LoggerFactory.getLogger(StudioSupport.class);

    private final boolean enabled;
    private final StudioMessageHook hook; // 未启用时为 null

    public StudioSupport(
            @Value("${studio.enabled:false}") boolean enabled,
            @Value("${studio.url:http://localhost:3000}") String studioUrl,
            @Value("${studio.project:demo-aiai}") String project) {
        this.enabled = enabled;
        if (!enabled) {
            this.hook = null;
            log.info("Studio 集成未启用（studio.enabled=false）。");
            return;
        }
        // 建立到 Studio 的 HTTP + WebSocket 连接（需 Studio 服务已运行）
        StudioManager.init()
                .studioUrl(studioUrl)
                .project(project)
                .runName("run_" + System.currentTimeMillis())
                .initialize()
                .block();
        this.hook = new StudioMessageHook(StudioManager.getClient());
        log.info("Studio 集成已启用，连接到 {}（project={}）。", studioUrl, project);
    }

    public boolean isEnabled() {
        return enabled;
    }

    /** 返回可挂到 agent 的 Hook；未启用时返回 {@code null}（调用方需判空）。 */
    public StudioMessageHook hookOrNull() {
        return hook;
    }
}

3.4 application.yml

配置 studio 相关属性：

yaml 复制代码

studio:
  enabled: true              # 要看可视化时改 true（且确保 Studio 已在运行）
  url: http://localhost:3000
  project: demo-aiai

3.5 配置 StudioMessageHook

各 agent 装配时注入 StudioSupport ，判空后再挂 Hook：

java 复制代码

HarnessAgent.Builder b = HarnessAgent.builder().name("plan_agent")./* ... */;
if (studio.hookOrNull() != null) b.hook(studio.hookOrNull());
return b.build();

4. 可观测性接入

AgentScope 直接采用了 OpenTelemetry 的 GenAI 语义约定，所以产出的 span 字段是业界标准的（gen_ai.*），通用后端都能识别。

4.1 TelemetryTracer

核心类 TelemetryTracer implements io.agentscope.core.tracing.Tracer，在四个关键点埋 span：

方法	埋点
`callAgent(...)` → `Mono<Msg>`	一次 `agent` 调用
`callModel(...)` → `Flux<ChatResponse>`	一次模型调用（含流式聚合）
`callTool(...)` → `Mono<ToolResultBlock>`	一次工具调用
`callFormat(...)`	结构化输出格式化

4.2 追踪后台接入路径

4.2.1 路径 A：接了 Studio 就自动有追踪

如果启用了 Studio（studio.enabled=true），追踪已经自动接好了，无需任何额外代码 。原因在 StudioManager.initialize() 内部------它成功连上后会自动做两件事：

java 复制代码

// StudioManager.initialize() 成功回调里（源码节选）
.doOnSuccess(v -> AgentBase.addSystemHook(new StudioMessageHook(...)))      // ① 全局注册消息 Hook
.doOnSuccess(v -> {
    String traceEndpoint = config.getTracingUrl() != null
            ? config.getTracingUrl()
            : /* studioUrl + */ "/v1/traces";
    TracerRegistry.register(TelemetryTracer.builder().endpoint(traceEndpoint).build());  // ② 自动注册 Tracer
})

所以只要开了 Studio，agent 的 callAgent/callModel/callTool 就会自动产出 span 并送到 Studio 的 /v1/traces ，在 Studio 界面里直接能看到链路------这也是本项目实测的结果。

4.2.2 路径 B：独立使用

如果你不用 Studio 、只想把 trace 导到自己的 OTLP 后端（Jaeger / OTel Collector / Tempo / APM），才需要手动注册：

java 复制代码

import io.agentscope.core.tracing.TracerRegistry;
import io.agentscope.core.tracing.telemetry.TelemetryTracer;

// 构建一个导出到自有 OTLP 后端的 TelemetryTracer，并注册为全局 Tracer
TracerRegistry.register(
        TelemetryTracer.builder()
                .enabled(true)
                .endpoint("http://localhost:4317")          // 你的 OTLP gRPC 端点
                // .addHeader("Authorization", "Bearer ...")  // 可选鉴权头
                .build());

// （可选）打开 Reactor 追踪钩子，增强跨响应式链路的上下文传播
// TracerRegistry.enableTracingHook();

// 之后照常构建运行 agent，callAgent/callModel/callTool 自动产生 span

4.3 查看追踪数据

Studio 中查看：