메인 콘텐츠로 건너뛰기
Koog는 단일 실행 및 복잡한 워크플로 에이전트를 구축하기 위한 Kotlin 기반 프레임워크입니다. Koog에는 기본 제공 OpenTelemetry(OTEL) 지원이 포함되어 있으며, 트레이스를 Weave로 직접 전송할 수 있어 프롬프트, 응답, 툴 호출, 엔드-투-엔드 에이전트 실행에 대한 풍부한 가시성을 제공합니다. Weave exporter를 활성화하면 Koog가 OpenTelemetry span을 Weave project로 전달하므로 디버깅하고 성능을 분석하며 더 빠르게 반복 개선할 수 있습니다.
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 내보내기 활성화하기 (OpenTelemetry)

Koog의 OpenTelemetry 기능을 설치하고 Weave exporter를 추가하세요. 그러면 Koog 스팬이 Weave의 OpenTelemetry 엔드포인트를 사용하여 Weave 트레이스로 매핑됩니다. 다음 예제는 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
    )
}
위 예시에서는 다음을 수행합니다:
  • weaveEntity와 weaveProjectName을 사용해 트레이스를 특정 팀과 프로젝트로 라우팅합니다.
  • weaveOtelBaseUrl을 트레이스 엔드포인트(예: https://<your-subdomain>.wandb.io/<path>)로 설정합니다. 전용 Weave 인스턴스를 사용하는 경우 이 파라미터를 사용하세요.
Weave와 Koog 연동을 처음 사용하는 경우, 다음 문서를 먼저 검토하는 것을 권장합니다:

​
무엇이 트레이싱되는지

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

​
예제 노트북

Weave로 트레이스를 스트리밍하는 실행 가능한 노트북은 Koog 문서에서 확인하세요.

​
문제 해결

  • 트레이스가 누락된 경우, 먼저 WEAVE_API_KEY, WEAVE_ENTITY, WEAVE_PROJECT_NAME가 올바르게 설정되어 있는지 확인합니다.
  • 환경에서 https://trace.wandb.ai에 접속할 수 있는지, 그리고 exporter가 위에서 보여준 대로 구성되어 있는지 확인합니다.
  • 추가적인 문제 해결 및 샘플링에 대한 안내는 Koog의 OpenTelemetry 지원 문서를 참조하세요.