Agent 모니터링 애플리케이션 생성¶

Agent 애플리케이션 또는 프레임워크를 연결하면 Agent 모니터링에서 호출 트레이스, 모델 사용 현황 및 관련 성능 데이터를 확인할 수 있습니다. 유형에 따른 연결 방식은 다음과 같습니다.

Agent 모니터링 > 요약으로 이동합니다.
Agent 탭을 선택합니다.
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로 현재 커넥터가 해당 유형과 운영 체제를 지원하는지 확인하세요.

1단계: Agent 유형 선택¶

연결 구성 페이지에서 연결할 분류와 Agent 유형을 선택합니다.

2단계: User 신원 구성¶

연결 구성에서는 현재 워크스페이스 구성원의 개인 정보 연결 여부를 선택할 수 있습니다.

기본적으로 "워크스페이스 개인 정보 연동"이 선택되어 있습니다. 시스템이 구성원 이름 등의 개인 정보를 업로드하며, 구성원 UUID를 user_id로 사용하고 사용자 이름은 user_name으로 사용됩니다.
선택하지 않으면 시스템이 임의의 ID를 생성하여 user_id로 사용하며, user_name은 직접 입력해야 합니다.
user_id는 User 데이터의 집계, 필터링, 드릴다운에 사용됩니다.
user_name은 표시 및 검색에만 사용되며 User의 고유 식별자로 사용되지 않습니다.
동일한 커넥터로 연결된 여러 Agent 유형은 동일한 user_id를 공유합니다.

익명 user_id는 커넥터 재시작, 업그레이드 또는 플러그인 업데이트 후에도 유지됩니다. 신원 구성을 완전히 제거하거나 신원을 직접 초기화한 경우에만 시스템이 새로운 익명 ID를 생성합니다.

3단계: 커넥터 설치¶

Agent가 설치된 호스트의 운영 체제에 따라 해당 명령을 실행합니다.

macOS/LinuxWindows

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>

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

설치가 완료된 후 현재 터미널에서 obs-agent-connector 명령을 인식하지 못하면 터미널을 다시 연 다음 이후 작업을 진행하세요.

4단계: 플러그인 설치¶

다음 명령을 실행하면 현재 환경의 Agent를 자동으로 검색하여 연결을 완료합니다.

obs-agent-connector discover

플러그인 업데이트 또는 제거¶

플러그인 업데이트:

obs-agent-connector update <플러그인 식별자>

플러그인 제거:

obs-agent-connector remove <플러그인 식별자>

추가 명령

지원되는 Agent, 주요 명령, 설치 매개변수 및 사용 예시를 확인하려면 obs-agent-connector 명령 참조를 참조하세요.

AgentScope 수동 연결¶

AgentScope는 obs-agent-connector를 사용하지 않으며 OpenTelemetry로 수동 연결해야 합니다. 언어별 연결 방식에 약간의 차이가 있으며, 이하에서는 Java를 예로 듭니다.

1단계: AgentScope 선택¶

연결 구성 페이지에서 AgentScope를 선택한 후 인스턴스 이름을 입력합니다. 인스턴스 이름은 중국어, 영문, 숫자, 밑줄 및 하이픈을 지원하며 동일한 Agent 유형 내에서 유일해야 합니다.

2단계: 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();

3단계: 환경 변수 구성¶

연결 구성 페이지는 현재 인스턴스를 기준으로 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"

4단계: 연결 검증¶

AgentScope 애플리케이션을 재시작하고 테스트 요청을 한 번 실행한 다음, Agent 모니터링에서 Trace 및 Metrics 데이터가 생성되었는지 확인합니다. 데이터가 없으면 Endpoint, X-Token, Agent ID 및 OpenTelemetry 환경 변수가 올바르게 적용되었는지 중점적으로 확인하세요.

Deep Agents 수동 연결¶

Deep Agents는 OpenTelemetry를 통해 호출 트레이스를 전송하며 런타임 식별자는 langchain입니다. 다음 구성은 OpenTelemetry 트레이스 수집이 활성화된 Python 애플리케이션에 적용되며, Agent, 모델, 도구 및 하위 에이전트의 호출 과정을 전송하는 데 사용됩니다.

1단계: 인스턴스 생성¶

연결 구성 페이지로 이동하여 Agent 프레임워크에서 Deep Agents를 선택하고 인스턴스 이름 및 User 신원 정보를 입력합니다. 페이지에서 생성된 Endpoint, X-Token, Agent ID, Agent Name, User ID 및 User Name을 복사하여 이후 구성에 사용합니다.

2단계: OpenTelemetry 구성¶

애플리케이션을 시작하는 터미널에서 다음 구성을 실행합니다(macOS/Linux 기준). 꺾쇠괄호(<>)로 표시된 자리 표시자 내용을 1단계 페이지에서 생성된 실제 값으로 바꿉니다. 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의 본문은 소급 기록되지 않습니다.

3단계: 시작 및 검증¶

애플리케이션 자체 시작 명령으로 Deep Agents 애플리케이션을 시작하거나 재시작하여 프로세스에 위 환경 변수가 로드되도록 한 후 테스트 호출을 한 번 실행합니다.

호출을 완료한 후 Agent 모니터링의 Deep Agents 유형 페이지로 이동하여 해당 인스턴스를 선택하고 새로 생성된 Trace를 확인합니다. agent_id 또는 서비스 이름으로 검색하여 호출 계층과 모델·도구 호출 정보를 확인할 수 있습니다.

데이터가 없으면 먼저 모델 요청이 성공했는지 확인한 후 Endpoint, X-Token, 프로토콜 및 네트워크 연결을 점검하세요. Token 등 필드의 표시 여부는 실제 수집된 데이터에 따라 달라집니다. 본문 수집을 비활성화한 경우 입력·출력 본문이 비어 있다고 해서 트레이스 전송이 실패한 것으로 판단해서는 안 됩니다.