> ## 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

> OpenTelemetry を使用して Kotlin ベースの Koog エージェントを Weave でトレースし、AI アプリケーションのツール呼び出し、プロンプト、完了結果を取得します。

[Koog](https://docs.koog.ai/) は、シングル run 型のエージェントや複雑なワークフロー型のエージェントを構築するための Kotlin ベースのフレームワークです。Koog は OpenTelemetry (OTEL) のサポートを標準で備えており、トレースを Weave に直接エクスポートできます。これにより、プロンプト、完了結果、ツール呼び出し、エージェントの実行全体をエンドツーエンドで可視化できます。

このガイドでは、Koog の Weave エクスポーターを設定し、Kotlin エージェントから OpenTelemetry のスパンを 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 エクスポーターが認証を行い、トレースを正しい project にルーティングできるように、エージェントを実行する前に次の環境変数を設定してください。

`[YOUR-API-KEY]` を CoreWeave Forge の APIキーに、`[YOUR-ENTITY]` を CoreWeave Forge のチーム名または entity 名に置き換えてください。`WEAVE_PROJECT_NAME` の値には任意のプロジェクト名を指定できます。project は初回使用時に 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")
}
```

[インストールの詳細](https://docs.koog.ai/)については、Koog のドキュメントを参照してください。

<h2 id="enable-weave-export-opentelemetry">
  Weave エクスポートを有効にする (OpenTelemetry)
</h2>

Koog をインストールしたら、Koog の OpenTelemetry 機能をインストールし、Weave エクスポーターを追加します。これにより、Weave の OpenTelemetry エンドポイントを介して、Koog のスパンが 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` を使用して、トレースを特定のチームと project に送信します。
* `weaveOtelBaseUrl` にトレースのエンドポイント (例: `https://[YOUR-SUBDOMAIN].wandb.io/[PATH]`) を設定します。専用クラウドの Weave インスタンスを使用する場合は、このパラメーターを指定してください。

Koog と Weave を初めて使用する場合は、次のドキュメントを参照してください。

* [Koog の Weave エクスポーターガイド](https://docs.koog.ai/opentelemetry-weave-exporter/): エクスポーターに関する詳細情報
* [Koog の OpenTelemetry サポートガイド](https://docs.koog.ai/opentelemetry-support/): Koog における OpenTelemetry の動作に関する基本概念
* [Weave OTEL ドキュメント](/ja/products/wandb/weave/guides/tracking/otel): Weave による OTLP データの取り込みに関する情報

<h2 id="what-gets-traced">
  トレースされる内容
</h2>

エクスポーターを有効にしてエージェントを実行すると、Koog はトレースを Weave プロジェクトに転送します。Koog の Weave エクスポーターは、Koog の汎用 OTEL インテグレーションと同じスパンを取得します。主な内容は次のとおりです。

* エージェントのライフサイクルイベント (開始、停止、エラー)
* LLM とのやり取り (プロンプト、完了結果、トークン使用量、レイテンシー)
* ツールおよび API の呼び出し (関数の Call と外部リクエスト)
* システムコンテキスト (モデル名、Koog のバージョン、環境のメタデータ)

これらのトレースを Weights & Biases UI で可視化すると、パフォーマンスと品質を把握できます。Weave でトレースを取得する方法の概要については、[Weave のトレースの概要](/ja/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 サポート](https://docs.koog.ai/opentelemetry-support/)を参照してください。