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

Agent 모니터링 > 요약으로 이동합니다.
Agent 탭을 선택합니다.
Agent 연동을 클릭하여 연동 설정 페이지를 엽니다.

연동 유형¶

Agent 모니터링은 다음 연동 유형을 지원합니다.

연동 방식	연동 유형
설치기 연동	Codex, Claude Code, OpenClaw, Hermes, Qoder, WorkBuddy, OpenCode, CodeBuddy, Cursor, DeepSeek Harness
수동 연동	AgentScope, Spring AI Alibaba

설치기 사용하여 연동¶

Codex, Claude Code, OpenClaw, Hermes, Qoder, WorkBuddy, OpenCode, CodeBuddy, Cursor 및 DeepSeek Harness는 obs-agent-connector 설치기를 사용하여 연동하며, 커넥터는 한 번만 설치하면 됩니다.

1단계: 연동 유형 선택¶

연동 설정 페이지에서 연동할 Agent 유형을 선택합니다.

2단계: 사용자(User) ID 설정¶

연동 설정에서는 현재 워크스페이스 멤버의 개인 정보를 연결할지 여부를 선택할 수 있습니다.

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

익명 user_id는 Connector 재시작, 업그레이드 또는 플러그인 업데이트 후에도 유지됩니다. ID 설정을 완전히 삭제하거나 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 환경 변수가 올바르게 적용되었는지 중점적으로 확인하세요.