Create an Agent Monitoring Application¶

1. Go to Agent Monitoring > Summary;
2. Select the Agent tab;
3. Click Access Agent to open the access configuration page.

Integration Types¶

Agent Monitoring supports the following integration types:

Access via Installer¶

Codex, Claude Code, OpenClaw, Hermes, Qoder, WorkBuddy, OpenCode, CodeBuddy, Cursor, and DeepSeek Harness use the obs-agent-connector installer for access. The connector only needs to be installed once.

Step 1: Select the Integration Type¶

On the access configuration page, select the Agent type to connect.

Step 2: User Identity Configuration¶

The access configuration supports whether to associate the personal information of the current workspace member.

• By default, Associate workspace personal information is checked. The system uploads personal information such as member names, uses the member's UUID as user_id, and the username as user_name.
• If unchecked, the system automatically generates a random ID as user_id, and you need to manually fill in user_name.
• user_id is used for aggregating, filtering, and drilling down into user data.
• user_name is only used for display and search, not as the unique identifier of the user.
• Multiple Agent types connected by the same Connector share the same user_id.

The anonymous user_id remains unchanged after Connector restarts, upgrades, or plugin updates. A new anonymous ID is only generated when the identity configuration is completely cleared or the identity is actively reset.

Step 3: Install the Connector¶

Execute the corresponding command based on the operating system of the host where the Agent is located.

curl -fsSL -O https://static.truewatch.com/obs-agent-connector/install.sh && \
sh install.sh \
  --download-base-url=https://static.truewatch.com/obs-agent-connector-test \
  --endpoint=<Endpoint> \
  --x-token=<X-Token>

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

After installation, if the current terminal does not recognize the obs-agent-connector command, reopen the terminal before proceeding.

Step 4: Install the Plugin¶

Run the following command to automatically discover Agents in the current environment and complete the access:

obs-agent-connector discover

Update or Remove a Plugin¶

Update a plugin:

obs-agent-connector update <Plugin ID>

Remove a plugin:

obs-agent-connector remove <Plugin ID>

Manual Access for AgentScope¶

AgentScope does not use obs-agent-connector; it requires manual access via OpenTelemetry. The access method varies slightly by language; the following takes Java as an example.

Step 1: Select AgentScope¶

On the access configuration page, select AgentScope, then fill in the instance name. The instance name supports Chinese characters, English letters, numbers, underscores, and hyphens, and must be unique within the same Agent type.

Step 2: Enable OpenTelemetry¶

Refer to the AgentScope official documentation and register TelemetryTracer in the AgentScope code:

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();

Step 3: Configure Environment Variables¶

The access configuration page generates the Endpoint, X-Token, Agent ID, and Agent Name for the current instance. Copy the actual values generated on the page and configure the following environment variables:

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"

Step 4: Verify Access¶

Restart the AgentScope application and initiate a test request. Then confirm in Agent Monitoring that Trace and Metrics data have been generated. If no data appears, check whether the Endpoint, X-Token, Agent ID, and OpenTelemetry environment variables are correctly applied.