新建 Agent 监测应用¶

进入Agent 监测 > 总览；
选择 Agent Tab；
点击接入 Agent，打开接入配置页面。

集成类型¶

Agent 监测支持以下集成类型：

接入方式	集成类型
安装器接入	Codex、Claude Code、OpenClaw、Hermes、Qoder、WorkBuddy
手动接入	AgentScope

使用安装器接入¶

Codex、Claude Code、OpenClaw、Hermes、Qoder 和 WorkBuddy 使用 obs-agent-connector 安装器接入，连接器只需安装一次。

第一步：选择集成类型¶

在接入配置页面选择需要接入的 Agent 类型。

第二步：安装连接器¶

根据 Agent 所在主机的操作系统执行对应命令。

macOS/LinuxWindows

curl -fsSL -O https://static.guance.com/obs-agent-connector/install.sh && \
sh install.sh \
  --download-base-url=https://static.guance.com/obs-agent-connector-test \
  --endpoint=xxx \
  --x-token=xxx

在 PowerShell 中执行：

$env:OBS_AGENT_CONNECTOR_OSS_ENDPOINT = "https://static.guance.com/obs-agent-connector"
Invoke-WebRequest -Uri "$env:OBS_AGENT_CONNECTOR_OSS_ENDPOINT/install.ps1" -OutFile "install.ps1"
powershell -ExecutionPolicy bypass -File .\install.ps1

安装完成后，如果当前终端无法识别 obs-agent-connector 命令，请重新打开终端后再执行后续操作。

第三步：安装插件¶

执行以下命令，自动发现当前环境中的 Agent 并完成接入：

obs-agent-connector discover

更新或移除插件¶

更新插件：

obs-agent-connector update <插件标识>

移除插件：

obs-agent-connector remove <插件标识>

AgentScope 手动接入¶

AgentScope 不使用 obs-agent-connector，需要通过 OpenTelemetry 手动接入。不同语言的接入方式略有差异，以下以 Java 为例。

第一步：选择 AgentScope¶

在接入配置页面选择 AgentScope，然后填写实例名称。实例名称支持中文、英文、数字、下划线和短横线，并且在同一 Agent 类型内唯一。

第二步：启用 OpenTelemetry¶

参考 AgentScope 官方文档，在 AgentScope 代码中注册 TelemetryTracer：

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

TraceRegistry.register(
    TelemetryTracer.builder()
        .build()
);

ReActAgent agent = ReActAgent.builder()
    .name("Assistant")
    .model(model)
    .build();

第三步：配置环境变量¶

接入配置页面会根据当前实例生成 Endpoint、X-Token、Agent ID 和 Agent Name。复制页面生成的实际值，并配置以下环境变量：

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="<Endpoint>/v1/write/otel-llm"
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT="<Endpoint>/v1/write/otel-metrics"
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT="<Endpoint>/v1/write/otel-logs"
export OTEL_RESOURCE_ATTRIBUTES="service.version=1.0.0,deployment.environment=production,agent_id=<Agent ID>,agent_name=<Agent Name>,agent_runtime=agentscope"
export OTEL_EXPORTER_OTLP_HEADERS="X-token=<X-Token>,to-headless=true"

第四步：验证接入¶

重启 AgentScope 应用并发起一次测试请求，然后在 Agent 监测中确认已产生 Trace 和 Metrics 数据。如果没有数据，请重点检查 Endpoint、X-Token、Agent ID 以及 OpenTelemetry 环境变量是否正确生效。