Create an Agent Monitoring Application¶

By connecting an Agent application or framework, you can view call traces, model usage, and related performance data in Agent Monitoring. Different types use different integration methods, as described below.

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

Agent Types¶

Agent Monitoring supports the following types:

Using the Installer¶

Codex, Claude Code, OpenClaw, Hermes, Qoder, WorkBuddy, OpenCode, CodeBuddy, Cursor, Opm, DeepSeek Harness, mimo, pi, and Qwen Work (desktop) are integrated using the obs-agent-connector installer. The connector only needs to be installed once. Before integrating, install the Agent you want to monitor and run obs-agent-connector agents to confirm that the current connector supports that type and operating system.

Step 1: Select the Agent Type¶

On the connection configuration page, select the category and Agent type you want to connect.

Step 2: Configure User Identity¶

The connection configuration lets you choose whether to associate the personal information of the current workspace member.

• By default, "Associate workspace member personal information" is selected. The system uploads personal information such as the member name, uses the member UUID as user_id, and uses the member name as user_name;
• If deselected, the system automatically generates a random ID as user_id, and you need to manually enter user_name;
• user_id is used to aggregate, filter, and drill down into User data;
• user_name is only used for display and search and is not the unique identifier of a User;
• Multiple Agent types connected through the same Connector share the same user_id.

The anonymous user_id remains unchanged after a Connector restart, upgrade, or plugin update. A new anonymous ID is generated only when the identity configuration is completely cleared or the identity is actively reset.

Step 3: Install the Connector¶

Run the corresponding command based on the operating system of the host where the Agent runs.

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=<Endpoint> \
  --x-token=<X-Token>

$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

After installation, if the current terminal cannot recognize the obs-agent-connector command, open a new terminal before continuing with the remaining steps.

Step 4: Install Plugins¶

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

obs-agent-connector discover

Update or Remove Plugins¶

Update a plugin:

obs-agent-connector update <plugin_identifier>

Remove a plugin:

obs-agent-connector remove <plugin_identifier>

Manually Integrating AgentScope¶

AgentScope does not use obs-agent-connector; instead, integrate it manually with OpenTelemetry. The integration steps differ slightly by language; Java is used as an example below.

Step 1: Select AgentScope¶

On the connection configuration page, select AgentScope, then enter the instance name. Instance names may contain 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 your 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 connection configuration page generates an 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 the Integration¶

Restart the AgentScope application and send 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.

Manually Integrating Deep Agents¶

Deep Agents reports call traces through OpenTelemetry, with langchain as the runtime identifier. The following configuration applies to Python applications with OpenTelemetry trace collection enabled and is used to report the invocation process of Agents, models, tools, and sub-agents.

Step 1: Create an Instance¶

Go to the connection configuration page, select Deep Agents under Agent frameworks, and enter the instance name and User identity information. Copy the Endpoint, X-Token, Agent ID, Agent Name, User ID, and User Name generated on the page for use in the following configuration.

Step 2: Configure OpenTelemetry¶

In the terminal where you start the application, run the following configuration (for macOS/Linux) and replace the angle-bracket placeholders with the actual values generated on the page from Step 1. Use the base address provided on the page for the Endpoint; do not append /v1/write/otel-llm again.

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"

This example only reports Trace and disables Metrics and Logs export. Input and output content is not collected by default; if you need to view content, set TRACELOOP_TRACE_CONTENT to true after confirming the data collection scope, then generate a new invocation record. Changing the configuration does not backfill the content of existing Traces.

Step 3: Start and Verify¶

Start or restart the Deep Agents application with its own startup command, make sure the process loads the environment variables above, and initiate a test call.

After the call completes, go to the Deep Agents type page in Agent Monitoring, select the instance, and view the newly generated Traces. You can locate them by agent_id or service name and inspect the call hierarchy and model/tool invocation information.

If no data appears, first check whether the model request succeeds, then verify the Endpoint, X-Token, protocol, and network connectivity. Whether fields such as Token are displayed depends on the data actually collected; when content collection is disabled, do not conclude that trace reporting failed just because input and output content are empty.