Create an Agent Monitoring Application¶

By integrating Agent applications or frameworks, you can view call traces, model usage, and related performance data in Agent Monitoring. Different integration methods apply to different types, as described below.

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

Agent Types¶

Agent Monitoring supports the following types:

Integrating with the Installer¶

Codex, Claude Code, OpenClaw, Hermes, Qoder, WorkBuddy, OpenCode, CodeBuddy, Cursor, Opm, DeepSeek Harness, mimo, and pi are integrated using 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 current connector supports that type and operating system.

Step 1: Select an Agent Type¶

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

Step 2: Configure User Identity¶

The integration configuration supports choosing 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 uses the username as user_name.
• If not selected, the system automatically generates a random ID as user_id, and you must manually enter user_name.
• user_id is used for aggregating, filtering, and drilling down into User data.
• user_name is used only for display and search, and is not the unique identifier of the User.
• Multiple Agent types integrated 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 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.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 cannot recognize the obs-agent-connector command, reopen the terminal before proceeding with subsequent operations.

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¶

To update a plugin:

obs-agent-connector update <plugin identifier>

To remove a plugin:

obs-agent-connector remove <plugin identifier>

Manually Integrating AgentScope¶

AgentScope does not use obs-agent-connector; it must be manually integrated via OpenTelemetry. The integration method varies slightly by language; the following uses Java as an example.

Step 1: Select AgentScope¶

On the integration configuration page, select AgentScope, then enter an instance name. Instance names support Chinese, English, 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 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 initiate a test request, then confirm in Agent Monitoring that Trace and Metrics data has been generated. If there is no data, focus on checking that the Endpoint, X-Token, Agent ID, and OpenTelemetry environment variables are correctly applied.

Manually Integrating Deep Agents¶

Deep Agents report call traces via OpenTelemetry, with the runtime identified as langchain. 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 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¶

Run the following configuration in the terminal where you start the application (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 the Endpoint, and 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 Traces and disables Metrics and Logs export. Input and output content is not collected by default; to view content, confirm the data collection scope, set TRACELOOP_TRACE_CONTENT to true, and then generate new invocation 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 above environment variables, and initiate a test invocation.

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

If there is no data, first check whether the model request succeeded, then verify the Endpoint, X-Token, protocol, and network connection. Whether fields such as Token are displayed depends on the actually collected data; when content collection is disabled, empty input or output content should not be taken as a sign that trace reporting failed.