메인 콘텐츠로 건너뛰기
Koog는 단일 실행 및 복잡한 워크플로우 에이전트를 구축하기 위한 Kotlin 기반 프레임워크입니다. Koog는 기본 제공 OpenTelemetry (OTEL) 지원 기능을 포함하고 있으며 trace를 Weave 로 직접 내보낼 수 있어, 프롬프트, 완료(completions), tool 호출 및 엔드투엔드 에이전트 실행에 대한 풍부한 가시성을 제공합니다. Weave exporter를 활성화하면 Koog가 OpenTelemetry span을 Weave 프로젝트로 전달하여 성능을 디버깅 및 분석하고 더 빠르게 반복할 수 있습니다.
Koog

사전 요구 사항

에이전트를 실행하기 전에 다음 환경 변수를 설정하세요:
export WEAVE_API_KEY="<your-api-key>"
export WEAVE_ENTITY="<your-entity>"           # W&B 팀/엔티티
export WEAVE_PROJECT_NAME="koog-tracing"      # 프로젝트 이름; 처음 사용 시 생성됨

Koog 설치 (Gradle)

Kotlin 프로젝트에 Koog를 추가하세요 (Kotlin DSL 예시):
dependencies {
    implementation("ai.koog:koog-agents:LATEST_VERSION")
}
추가적인 설치 정보는 Koog 문서를 참조하세요.

Weave export 활성화 (OpenTelemetry)

Koog의 OpenTelemetry 기능을 설치하고 Weave exporter를 추가합니다. 이는 Weave의 OpenTelemetry 엔드포인트를 사용하여 Koog span을 Weave trace에 매핑합니다. 다음 예시는 addWeaveExporter를 사용하는 방법을 보여줍니다:
fun main() = runBlocking {
    val apiKey = "api-key"
    val entity = System.getenv()["WEAVE_ENTITY"] ?: throw IllegalArgumentException("WEAVE_ENTITY is not set")
    val projectName = System.getenv()["WEAVE_PROJECT_NAME"] ?: "koog-tracing"

    val agent = AIAgent(
        executor = simpleOpenAIExecutor(apiKey),
        llmModel = OpenAIModels.CostOptimized.GPT4oMini,
        systemPrompt = "You are a code assistant. Provide concise code examples."
    ) {
        install(OpenTelemetry) {
            addWeaveExporter()
        }
    }

    println("Running agent with Weave tracing")

    val result = agent.run("""
        Create a Python function to calculate fibonacci numbers efficiently,
        include error handling, type hints, and unit tests.
        Verify the implementation works for n=50.
    """)

    println("Result: $result\nSee traces on https://wandb.ai/$entity/$projectName/weave/traces")
}
이 함수는 Weave 환경 변수를 자동으로 읽어오지만, 다음과 같이 exporter에 대한 특정 파라미터를 구성할 수도 있습니다:
install(OpenTelemetry) {
    addWeaveExporter(
        weaveOtelBaseUrl = "https://trace.wandb.ai",
        weaveEntity = System.getenv()["WEAVE_ENTITY"],
        weaveProjectName = System.getenv()["WEAVE_PROJECT_NAME"],
        weaveApiKey = System.getenv()["WEAVE_API_KEY"],
        timeout = 10.seconds
    )
}
위의 예시는 다음과 같습니다:
  • weaveEntityweaveProjectName을 사용하여 특정 팀과 프로젝트로 trace를 라우팅합니다.
  • weaveOtelBaseUrl을 trace 엔드포인트로 설정합니다 (예: https://<your-subdomain>.wandb.io/<path>). 전용 Weave 인스턴스를 사용하는 경우 이 파라미터를 사용하세요.
Koog를 Weave와 처음 사용하신다면 다음 문서를 검토하는 것을 권장합니다:

추적되는 항목

활성화되면 Koog의 Weave exporter는 다음을 포함하여 Koog의 일반 OTEL 인테그레이션과 동일한 span을 캡처합니다:
  • 에이전트 수명 주기 이벤트 (시작, 중지, 오류)
  • LLM 상호작용 (프롬프트, 완료, 토큰 사용량, 지연 시간)
  • Tool 및 API 호출 (함수 호출 및 외부 요청)
  • 시스템 컨텍스트 (모델 이름, Koog 버전, 환경 메타데이터)
Weave UI에서 이러한 trace를 시각화하여 성능과 품질을 파악할 수 있습니다. Weave를 사용한 trace 캡처에 대한 도입부는 Weave의 tracing 개요를 참조하세요.

예제 노트북

Weave로 trace를 스트리밍하는 실행 가능한 노트북은 Koog 문서를 참조하세요.

문제 해결

  • trace가 누락된 경우, 먼저 WEAVE_API_KEY, WEAVE_ENTITY, WEAVE_PROJECT_NAME이 올바르게 설정되었는지 확인하세요.
  • 사용자 환경에서 https://trace.wandb.ai에 접속 가능한지, exporter가 위에 설명된 대로 구성되었는지 확인하세요.
  • 추가적인 문제 해결 및 샘플링 가이드는 Koog의 OpenTelemetry 지원을 참조하세요.