메인 콘텐츠로 건너뛰기
Koog는 단일 실행 및 복잡한 워크플로를 수행하는 에이전트를 구축하기 위한 Kotlin 기반 프레임워크입니다. Koog에는 내장 OpenTelemetry(OTEL) 지원이 포함되어 있어 트레이스를 Weave로 직접 내보낼 수 있으며, 이를 통해 프롬프트, 컴플리션, 툴 호출, 에이전트의 엔드 투 엔드 실행 전 과정을 세밀하게 가시화할 수 있습니다. Weave exporter를 활성화하면 Koog가 OpenTelemetry 스팬을 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 내보내기 활성화 (OpenTelemetry)

Koog의 OpenTelemetry 기능을 설치하고 Weave exporter를 추가합니다. 이렇게 하면 Koog span이 Weave의 OpenTelemetry 엔드포인트를 통해 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
    )
}
위 예제는 다음을 수행합니다:
  • 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 지원 문서를 참고하세요.