Skip to content

Create an Agent Monitoring Application


By integrating an Agent application or framework, you can view call traces, model usage, and related performance data in Agent Monitoring. Different integration methods apply to different types.

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

Agent Types

Agent Monitoring supports the following types:

Category Agent Type Integration Method
Agent applications Codex, Claude Code, OpenClaw, Hermes, Qoder, WorkBuddy, OpenCode, CodeBuddy, Cursor, DeepSeek Harness, Opm, mimo, pi, Qianwen Work (Desktop) Integrate using the obs-agent-connector installer
Agent frameworks AgentScope, Spring AI Alibaba, Deep Agents Integrate manually using OpenTelemetry; see Integration Steps for a Deep Agents example

Integrating with the Installer

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

Step 1: Select the Agent Type

On the integration configuration page, select the category and Agent type to integrate.

Step 2: Configure User Identity

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

  • By default, Associate workspace personal information is selected. The system uploads personal information such as member names, uses the member UUID as user_id, and the username as user_name;
  • If not selected, the system automatically generates a random ID as user_id, and you need to manually enter user_name;
  • user_id is used for aggregating, filtering, and drilling 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 integrated by the same Connector share the same user_id.

The anonymous user_id remains unchanged after the Connector is restarted, upgraded, or its plugins are updated. A new anonymous ID is generated only when you completely clear the identity configuration or actively reset the identity.

Step 3: Install the Connector

Run the command corresponding to the operating system of the host where the Agent resides.

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

Run the following in 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

After installation, if the current terminal cannot recognize the obs-agent-connector command, open a new terminal before proceeding.

Step 4: Install the Plugin

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

obs-agent-connector discover

Updating or Removing Plugins

To update a plugin:

obs-agent-connector update <plugin identifier>

To remove a plugin:

obs-agent-connector remove <plugin identifier>
More Commands

For supported Agents, common commands, installation parameters, and usage examples, see obs-agent-connector Command Reference.

Manual Integration with AgentScope

AgentScope does not use obs-agent-connector; you need to integrate it manually with OpenTelemetry. Integration steps vary slightly by language; the example below uses Java.

Step 1: Select AgentScope

On the integration configuration page, select AgentScope, then enter an instance name. The instance name can contain Chinese characters, English letters, digits, 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 integration configuration page generates 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 there is no data, check whether Endpoint, X-Token, Agent ID, and the OpenTelemetry environment variables are correctly applied.

Manual Integration with Deep Agents

Deep Agents reports traces via OpenTelemetry, with the runtime identifier langchain. The following configuration applies to Python applications with OpenTelemetry trace collection enabled, and is used to report the invocation of Agents, models, tools, and subagents.

Step 1: Create an Instance

Go to the integration 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 later configuration.

Step 2: Configure OpenTelemetry

In the terminal where you start the application, run the following configuration (for macOS/Linux), replacing the angle-bracket placeholders with the actual values generated on the page in Step 1. Use the base address provided on the page for 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 reports only Traces and disables Metrics and Logs export. Input and output content is not collected by default. To view content, after confirming the data collection scope, set TRACELOOP_TRACE_CONTENT to true and generate new call records. Configuration changes do not backfill content for existing Traces.

Step 3: Start and Verify

Use the application's own startup command to start or restart the Deep Agents application, ensure the process loads the environment variables above, and make one test call.

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

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

Feedback

Is this page helpful?