Skip to main content
CoreWeave Agent Lens는 OpenTelemetry (OTel)를 기반으로 구축되었으며, span을 Agent Lens로 수집하는 전용 OTLP 엔드포인트를 제공합니다. 따라서 OTel 익스포터의 현재 엔드포인트 설정을 Agent Lens의 엔드포인트 설정으로 바꾸기만 하면 OTel로 계측된 애플리케이션의 span을 Agent Lens로 빠르게 보낼 수 있습니다. CoreWeave Forge SDK를 설치할 필요도 없습니다. 이 페이지에서는 엔드포인트에 인증하고 span을 전송하는 방법을 설명합니다.
Agent Lens는 Weights & Biases와 동일한 백엔드에서 실행되므로 일부 설정 이름에는 wandb 접두사가 그대로 남아 있습니다. WANDB_API_KEY 환경 변수, wandb-api-key 헤더, wandb.entity 및 wandb.project 리소스 속성이 이에 해당합니다. 이 이름들은 표시된 그대로 사용하세요.

인증

다음 엔드포인트로 span을 전송할 수 있습니다.
  • 경로: /agents/otel/v1/traces
  • 메서드: POST
  • Content-Type: application/x-protobuf
  • 기본 URL: Multi-tenant Cloud의 경우 https://trace.wandb.ai
이 엔드포인트는 OTLP protobuf 페이로드만 허용합니다. opentelemetry-exporter-otlp-proto-http(Python) 또는 @opentelemetry/exporter-trace-otlp-proto(TypeScript) 같은 protobuf HTTP 익스포터를 사용하세요. gzip 및 deflate 콘텐츠 인코딩도 지원합니다. 엔드포인트에 인증하려면 OTLPSpanExporter 설정에서 다음 값 중 하나를 사용해 API 키를 지정하세요.
  • wandb-api-key: Forge API 키를 값으로 지정합니다.
  • Authorization: 사용자 이름은 api, 비밀번호는 Forge API 키로 지정하는 HTTP Basic 인증입니다. 익스포터나 수집기가 표준 인증 헤더만 지원하는 경우에 유용합니다.

프로젝트 라우팅

Agent Lens는 OTel 리소스 속성 또는 요청 헤더를 기준으로 span을 프로젝트에 라우팅합니다.
  • 리소스 속성(권장): TracerProvider 리소스에서 wandb.entity를 Forge 팀 이름 또는 사용자 이름으로, wandb.project를 프로젝트 이름으로 설정하세요.
  • project_id 헤더: 값을 [YOUR-TEAM]/[YOUR-PROJECT]로 설정하세요.
둘 다 지정된 경우 리소스 속성이 우선합니다. entity와 프로젝트가 지정되지 않은 span은 삭제됩니다.

Conversations 탭에 맞게 span 구성하기

Agent Lens는 어떤 OTel span이든 수용하고 해당 span의 속성을 모두 저장하지만, Conversations 탭에는 OTel GenAI 시맨틱 규칙을 따르는 span만 렌더링됩니다. 각 span에 gen_ai.operation.name을 설정하여 해당 span이 무엇을 나타내는지 Agent Lens에 알려 주세요. 그룹화를 제어하는 속성이 두 가지 더 있습니다.
  • gen_ai.conversation.id: 턴을 하나의 대화로 묶습니다. 대화가 지속되는 동안 변하지 않는 고정 ID를 사용하세요.
  • gen_ai.agent.name: Conversations 탭에서 대화를 이름이 지정된 에이전트 아래로 묶습니다.
gen_ai.request.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens 등 그 밖의 GenAI 시맨틱 규칙 속성은 선택 사항이지만, 설정하면 모델 이름과 토큰 수가 함께 표시되어 더 풍부한 정보를 확인할 수 있습니다. 이러한 span이 매핑되는 에이전트 데이터 모델에 대해서는 에이전트 트레이싱하기를 참조하세요.

환경 변수만으로 설정하기

애플리케이션 또는 수집기가 표준 OTel 익스포터 환경 변수를 읽는다면, 다음 변수를 설정하는 것만으로 코드를 변경하지 않고도 span을 Agent Lens로 라우팅할 수 있습니다.
  • OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: 익스포터가 span을 전송할 Agent Lens 엔드포인트입니다.
  • OTEL_EXPORTER_OTLP_TRACES_HEADERS: wandb-api-key 헤더에 담아 보내는 Forge API 키로 각 요청을 인증합니다.
  • OTEL_RESOURCE_ATTRIBUTES: span을 사용자의 프로젝트로 전송합니다. wandb.entity에는 Forge 팀 이름 또는 사용자 이름을, wandb.project에는 프로젝트 이름을 설정하세요.
  • OTEL_EXPORTER_OTLP_TRACES_PROTOCOL: 익스포터가 HTTP를 통해 OTLP protobuf를 전송하도록 설정합니다. 엔드포인트는 protobuf 페이로드만 허용하므로 값은 반드시 http/protobuf여야 합니다.

예시: Agent Lens SDK 없이 에이전트 span 내보내기

다음 예시는 OTel 패키지만 사용하여 최소한의 에이전트 턴을 계측합니다. 턴에 대한 invoke_agent span, LLM Call에 대한 chat span, 도구 Call에 대한 execute_tool span을 생성한 다음, 이를 Agent Lens 에이전트 엔드포인트로 내보냅니다. 먼저 필요한 의존성을 설치하세요.
그런 다음 아래 코드에서 YOUR-TEAM, YOUR-PROJECT, YOUR_API_KEY를 실제 값으로 바꾼 후 실행하세요.
같은 대화에 턴을 더 추가하려면 동일한 gen_ai.conversation.id로 invoke_agent span을 추가로 내보내세요. 각 턴은 자체 트레이스의 루트 span이므로 턴끼리 부모 span을 공유할 필요가 없습니다. 애플리케이션에서 span을 내보낸 후 Agent Lens 프로젝트의 Conversations 뷰를 여세요.
마지막 수정일 2026년 9월 30일