목록으로
기술

Koog 에이전트에 대한 Weave 추적

·3분 읽기
#Koog#JetBrains#AI Agent#Kotlin#Java#JVM

원문: Koog Documentation — Weave 이 글은 Koog 공식 문서의 Weave 페이지를 한국어로 옮긴 번역본입니다. 문서 구조와 링크 의미를 유지하되, MkDocs 전용 UI 문법은 블로그에서 읽기 좋도록 정리했습니다.

Koog 에이전트에 대한 Weave 추적

:material-github: Open on GitHub{ .md-button .md-button--기본 } :material-download: Download .ipynb{ .md-버튼 }

이 노트북은 OpenTelemetry(OTLP)를 사용하여 Koog 에이전트를 W&B Weave로 추적하는 방법을 보여줍니다. 간단한 Koog AIAgent을 생성하고, Weave 내보내기를 활성화하고, 프롬프트를 실행하고, Weave UI의 풍부한 추적.

배경 정보는 Weave OpenTelemetry 문서: https://weave-docs.wandb.ai/guides/tracking/otel/를 참조하세요.

전제 조건

예제를 실행하기 전에 다음 사항을 확인하세요.

  • Weave/W&B 계정: https://wandb.ai
  • https://wandb.ai/authorize의 API 키가 환경 변수로 노출됩니다: WEAVE_API_KEY
  • 귀하의 Weave 법인(팀 또는 사용자) 이름은 WEAVE_ENTITY로 노출됩니다.
  • WEAVE_PROJECT_NAME로 노출되는 프로젝트 이름(설정되지 않은 경우 이 예시에서는 koog-tracing을 사용함)
  • Koog 에이전트를 실행하기 위해 OPENAI_API_KEY로 노출된 OpenAI API 키

예(macOS/Linux):

1export WEAVE_API_KEY=...  # required by Weave2export WEAVE_ENTITY=your-team-or-username3export WEAVE_PROJECT_NAME=koog-tracing4export OPENAI_API_KEY=...

노트북 설정

우리는 최신 Kotlin Jupyter 설명자를 사용합니다. Koog가 %use 플러그인으로 사전 구성되어 있는 경우, 아래 줄의 주석 처리를 해제할 수 있습니다.

1%useLatestDescriptors2//%use koog3

에이전트 생성 및 Weave 추적 활성화

우리는 최소한의 AIAgent을 구성하고 Weave 내보내기와 함께 OpenTelemetry 기능을 설치합니다. 내보내기는 환경 구성을 사용하여 OTLP 범위를 Weave로 보냅니다.

  • WEAVE_API_KEY — Weave에 대한 인증
  • WEAVE_ENTITY — 추적을 소유한 팀/사용자
  • WEAVE_PROJECT_NAME — 트레이스를 저장할 Weave 프로젝트
1import ai.koog.agents.core.agent.AIAgent2import ai.koog.agents.features.opentelemetry.feature.OpenTelemetry3import ai.koog.prompt.executor.clients.openai.OpenAIModels4import ai.koog.prompt.executor.llms.all.simpleOpenAIExecutor56val entity = System.getenv()["WEAVE_ENTITY"] ?: throw IllegalArgumentException("WEAVE_ENTITY is not set")7val projectName = System.getenv()["WEAVE_PROJECT_NAME"] ?: "koog-tracing"89val agent = AIAgent(10    executor = simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")),11    llmModel = OpenAIModels.Chat.GPT4oMini,12    systemPrompt = "You are a code assistant. Provide concise code examples."13) {14    install(OpenTelemetry) {15        addWeaveExporter(16            weaveEntity = entity,17            weaveProjectName = projectName18        )19    }20}21

에이전트를 실행하고 Weave에서 추적을 확인하세요.

간단한 프롬프트를 실행합니다. 완료 후 인쇄된 링크를 열어 Weave에서 추적을 확인하세요. 에이전트 실행, 모델 호출 및 기타 계측 작업에 대한 범위가 표시되어야 합니다.

1import kotlinx.coroutines.runBlocking23println("Running agent with Weave tracing")45runBlocking {6    val result = agent.run("Tell me a joke about programming")7    "Result: $result\nSee traces on https://wandb.ai/$entity/$projectName/weave/traces"8}9

문제 해결

  • 추적이 표시되지 않으면 환경에 WEAVE_API_KEY, WEAVE_ENTITY 및 WEAVE_PROJECT_NAME가 설정되어 있는지 확인하세요.
  • 네트워크가 Weave의 OTLP 엔드포인트에 대한 아웃바운드 HTTPS를 허용하는지 확인하세요.
  • OpenAI 키가 유효하고 계정에서 선택한 모델에 액세스할 수 있는지 확인하세요.
#Koog#JetBrains#AI Agent#Kotlin#Java#JVM