新建 Agent 监测应用¶
通过接入 Agent 应用或框架，可以在 Agent 监测中查看调用链路、模型使用情况及相关性能数据。不同类型的接入方式如下。
- 进入Agent 监测 > 总览；
- 选择 Agent Tab；
- 点击接入 Agent，打开接入配置页面。
Agent 类型¶
Agent 监测支持以下类型：
| 分类 | Agent 类型 | 接入方式 |
|---|---|---|
| Agent 应用 | Codex、Claude Code、OpenClaw、Hermes、Qoder、WorkBuddy、OpenCode、CodeBuddy、Cursor、DeepSeek Harness、Opm、mimo、pi | 使用 obs-agent-connector 安装器接入 |
| Agent 框架 | AgentScope、Spring AI Alibaba、Deep Agents | 使用 OpenTelemetry 手动接入；Deep Agents 示例见接入步骤 |
使用安装器接入¶
Codex、Claude Code、OpenClaw、Hermes、Qoder、WorkBuddy、OpenCode、CodeBuddy、Cursor、Opm、DeepSeek Harness、mimo 和 pi 使用 obs-agent-connector 安装器接入，连接器只需安装一次。接入前请先安装需要监测的 Agent，并通过 obs-agent-connector agents 确认当前连接器支持该类型及操作系统。
第一步：选择 Agent 类型¶
在接入配置页面选择需要接入的分类和 Agent 类型。
第二步：User 身份配置¶
接入配置支持选择是否关联当前空间成员的个人信息。
- 默认勾选“关联空间个人信息”。系统会上传成员名称等个人信息，会使用成员uuid作为
user_id，用户名会作为user_name； - 不勾选，系统会自动生成一个随机id作为
user_id, 需手动填写user_name； user_id用于聚合、筛选和下钻 User 数据；user_name仅用于展示和搜索，不作为 User 的唯一标识；- 同一 Connector 接入的多个 Agent 类型共用同一个
user_id。
匿名 user_id 在 Connector 重启、升级或插件更新后保持不变。只有彻底清理身份配置或主动重置身份时，系统才会生成新的匿名 ID。
第三步：安装连接器¶
根据 Agent 所在主机的操作系统执行对应命令。
安装完成后，如果当前终端无法识别 obs-agent-connector 命令，请重新打开终端后再执行后续操作。
第四步：安装插件¶
执行以下命令，自动发现当前环境中的 Agent 并完成接入：
更新或移除插件¶
更新插件：
移除插件：
更多命令
如需查看支持的 Agent、常用命令、安装参数及使用示例，参见 obs-agent-connector 命令参考。
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 环境变量是否正确生效。
Deep Agents 手动接入¶
Deep Agents 通过 OpenTelemetry 上报调用链路，运行时标识为 langchain。以下配置适用于已启用 OpenTelemetry 链路采集的 Python 应用，用于上报 Agent、模型、工具和子代理的调用过程。
第一步：创建实例¶
进入接入配置页面，在 Agent 框架 中选择 Deep Agents，填写实例名称及 User 身份信息。复制页面生成的 Endpoint、X-Token、Agent ID、Agent Name、User ID 和 User Name，供后续配置使用。
第二步：配置 OpenTelemetry¶
在启动应用的终端中执行以下配置（适用于 macOS/Linux），将尖括号占位内容替换为第一步页面生成的实际值。Endpoint 使用页面提供的基础地址，不重复添加 /v1/write/otel-llm。
export OTEL_SERVICE_NAME="langchain-deep-agent"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=none
export OTEL_LOGS_EXPORTER=none
export TRACELOOP_TRACE_CONTENT=false
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="<Endpoint>/v1/write/otel-llm"
export OTEL_RESOURCE_ATTRIBUTES="agent_id=<Agent ID>,agent_name=<Agent Name>,user_id=<User ID>,user_name=<User Name>,agent_runtime=langchain"
export OTEL_EXPORTER_OTLP_HEADERS="X-token=<X-Token>,to-headless=true"
此示例仅上报 Trace，关闭 Metrics 和 Logs 导出。输入、输出正文默认不采集；如需查看正文，在确认数据采集范围后，将 TRACELOOP_TRACE_CONTENT 设为 true，再生成新的调用记录。配置变更不会补录已有 Trace 的正文。
第三步：启动并验证¶
使用应用自身的启动命令启动或重启 Deep Agents 应用，确保进程加载上述环境变量，并发起一次测试调用。
完成一次调用后，进入 Agent 监测的 Deep Agents 类型页面，选择对应实例并查看新产生的 Trace。可按 agent_id 或服务名称定位，检查调用层级和模型、工具调用信息。
若没有数据，先检查模型请求是否成功，再核对 Endpoint、X-Token、协议和网络连接。Token 等字段是否展示取决于实际采集的数据；关闭正文采集时，不应以输入、输出正文为空判断链路上报失败。