> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Koog

> Weave로 Kotlin 기반 Koog 에이전트를 OpenTelemetry를 사용해 트레이스하여 AI 애플리케이션의 도구 Call, 프롬프트, 완료를 캡처하세요.

[Koog](https://docs.koog.ai/)는 single-run 및 복잡한 워크플로 에이전트를 구축하기 위한 Kotlin 기반 프레임워크입니다. Koog에는 OpenTelemetry(OTEL) 지원이 내장되어 있으며 트레이스를 Weave로 직접 내보낼 수 있어 프롬프트, 완료, 도구 Call 및 엔드투엔드 에이전트 실행에 대한 가시성을 제공합니다.

이 가이드에서는 Kotlin 에이전트가 OpenTelemetry span을 Weave 프로젝트로 전달하도록 Koog의 Weave 익스포터를 설정하는 방법을 설명합니다. 익스포터를 사용하면 run을 디버그하고, 성능을 분석하며, 더 빠르게 반복할 수 있습니다. 이 가이드는 이미 Koog로 에이전트를 구축하고 Weave 트레이싱을 추가하려는 Kotlin 개발자를 위한 것입니다.

<Frame>
  <img src="https://mintcdn.com/coreweave-dbfa0e8d/3Dv_sw2eg8feUJlx/products/wandb/weave/_media/koog.png?fit=max&auto=format&n=3Dv_sw2eg8feUJlx&q=85&s=e2624702f5b971815babd601d66448b0" alt="Koog" width="3333" height="1756" data-path="products/wandb/weave/_media/koog.png" />
</Frame>

<h2 id="prerequisites">
  사전 요구 사항
</h2>

에이전트를 실행하기 전에 다음 환경 변수를 설정해야 Weave 익스포터가 트레이스를 인증하고 올바른 프로젝트로 라우팅할 수 있도록 합니다:

`[YOUR-API-KEY]`를 CoreWeave Forge API 키로, `[YOUR-ENTITY]`를 CoreWeave Forge 팀 또는 entity 이름으로 바꾸세요. `WEAVE_PROJECT_NAME` 값은 임의의 프로젝트 이름일 수 있습니다. Weave는 처음 사용 시 프로젝트를 생성합니다.

```bash theme={"system"}
export WEAVE_API_KEY="[YOUR-API-KEY]"
export WEAVE_ENTITY="[YOUR-ENTITY]"
export WEAVE_PROJECT_NAME="koog-tracing"
```

<h2 id="install-koog-gradle">
  Koog 설치 (Gradle)
</h2>

환경 변수가 준비되면, Kotlin 프로젝트에 Koog를 추가하여 에이전트와 그 익스포터를 설정할 수 있습니다 (Kotlin DSL 예시):

```kotlin theme={"system"}
dependencies {
    implementation("ai.koog:koog-agents:LATEST_VERSION")
}
```

Koog의 문서에서 [추가 설치 정보](https://docs.koog.ai/)를 참조하세요.

<h2 id="enable-weave-export-opentelemetry">
  Weave 내보내기 활성화 (OpenTelemetry)
</h2>

Koog를 설치한 후 Koog의 OpenTelemetry 기능을 설치하고 Weave 익스포터를 추가하세요. 이는 Weave의 OpenTelemetry 엔드포인트를 사용하여 Koog spans를 Weave 트레이스로 매핑합니다.

다음 예제는 `addWeaveExporter`를 사용하는 방법을 보여줍니다:

```kotlin theme={"system"}
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://forge.coreweave.com/wandb/$entity/$projectName/weave/traces")
}
```

이 함수는 Weave 환경 변수를 자동으로 읽어 오지만, 다음 예시처럼 익스포터의 [특정 매개변수](https://api.koog.ai/agents/agents-features/agents-features-opentelemetry/ai.koog.agents.features.opentelemetry.integration.weave/add-weave-exporter.html?query=fun%20OpenTelemetryConfig.addWeaveExporter\(weaveOtelBaseUrl:%20String?%20=%20null,%20weaveEntity:%20String?%20=%20null,%20weaveProjectName:%20String?%20=%20null,%20weaveApiKey:%20String?%20=%20null,%20timeout:%20Duration%20=%2010.seconds\))를 직접 설정할 수도 있습니다.

```kotlin theme={"system"}
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 인스턴스에 이 매개변수를 사용하세요.

Koog를 Weave와 함께 처음 사용하는 경우 다음 문서를 검토하세요:

* 익스포터에 대한 추가 정보는 [Koog의 Weave 익스포터 가이드](https://docs.koog.ai/opentelemetry-weave-exporter/)를 참조하세요.
* Koog에서 OpenTelemetry가 작동하는 방식에 대한 핵심 개념은 [Koog의 OpenTelemetry 지원 가이드](https://docs.koog.ai/opentelemetry-support/)를 참조하세요.
* Weave가 OTLP 데이터를 수집하는 방법에 대한 정보는 [Weave OTEL 문서](/ko/products/wandb/weave/guides/tracking/otel)를 참조하세요.

<h2 id="what-gets-traced">
  트레이스 대상
</h2>

익스포터를 활성화한 상태로 에이전트를 실행하면 Koog가 트레이스를 Weave 프로젝트로 전달합니다. Koog의 Weave 익스포터는 Koog의 일반 OTEL 인테그레이션과 동일한 span을 캡처하며, 여기에는 다음 항목이 포함됩니다.

* 에이전트 라이프사이클 이벤트(시작, 중지, 오류)
* LLM 상호작용(프롬프트, 완료, 토큰 사용량, 지연 시간)
* 도구 및 API 호출(함수 호출 및 외부 요청)
* 시스템 컨텍스트(모델 이름, Koog 버전, 환경 메타데이터)

Weights & Biases UI에서 이러한 트레이스를 시각화하여 성능과 품질을 파악할 수 있습니다. Weave로 트레이스를 캡처하는 방법은 [Weave 트레이싱 개요](/ko/products/wandb/weave/guides/tracking/tracing)를 참조하세요.

<h2 id="example-notebook">
  예시 노트북
</h2>

Weave로 트레이스를 스트리밍하는 [실행 가능한 노트북](https://docs.koog.ai/examples/Weave/)에 대한 Koog의 문서를 참조하세요.

<h2 id="troubleshooting">
  문제 해결
</h2>

Koog 에이전트가 예상대로 트레이스를 내보내지 않는 경우 다음을 확인하세요:

* 트레이스가 누락된 경우 먼저 `WEAVE_API_KEY`, `WEAVE_ENTITY`, `WEAVE_PROJECT_NAME`이 올바르게 설정되었는지 확인하세요.
* 환경이 `https://trace.wandb.ai`에 도달할 수 있는지, 그리고 앞의 예시에서 보여준 대로 익스포터가 설정되었는지 확인하세요.
* 추가 문제 해결 및 샘플링 지침은 Koog의 [OpenTelemetry support](https://docs.koog.ai/opentelemetry-support/)를 참조하세요.


## Related topics

- [인테그레이션 개요](/ko/products/wandb/weave/guides/integrations.md)