Koog

OpenTelemetry を使用して Kotlin ベースの Koog エージェントを Weave でトレースし、AI アプリケーションのツール call、プロンプト、コンプリーションを収集します。

Koog は、単一実行のエージェントから複雑なワークフローエージェントまで構築できる、Kotlin ベースのフレームワークです。Koog には OpenTelemetry (OTEL) サポートが組み込まれており、トレースを Weave に直接エクスポートできるため、プロンプト、コンプリーション、ツール call、エージェントのエンドツーエンドの実行を詳細に可視化できます。

Weave エクスポーターを有効にすると、Koog は OpenTelemetry のスパンを Weave のプロジェクトに転送するため、デバッグ、パフォーマンス分析、改善の反復をより迅速に行えます。

​

前提条件

エージェントを実行する前に、以下の環境変数を設定してください。

export WEAVE_API_KEY="<your-api-key>"
export WEAVE_ENTITY="<your-entity>"           # W&B のチーム/entity
export WEAVE_PROJECT_NAME="koog-tracing"      # 任意のプロジェクト名。初回使用時に作成されます

​

Koog をインストールする (Gradle)

Koog を Kotlin プロジェクトに追加します (Kotlin DSL の例を使用) :

dependencies {
    implementation("ai.koog:koog-agents:LATEST_VERSION")
}

追加のインストール情報については、Koog のドキュメントを参照してください。

​

Weave エクスポートを有効にする (OpenTelemetry)

Koog の OpenTelemetry 機能をインストールし、Weave エクスポーターを追加します。これにより、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 の環境変数を自動的に読み取りますが、エクスポーターについては、特定のパラメーター を指定して、次のように設定することもできます。

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 exporter ガイド
• OpenTelemetry が Koog とどのように連携するかの基本概念については、Koog の OpenTelemetry サポートガイド
• Weave が OTLP データをどのように取り込むかについては、Weave OTEL ドキュメント

​

トレースされる内容

有効にすると、Koog の Weave エクスポーター は、Koog の一般的な OTEL インテグレーションと同じスパンをキャプチャします。これには次が含まれます。

• エージェントのライフサイクルイベント (開始、停止、エラー)
• LLM とのやり取り (プロンプト、コンプリーション、token 使用量、レイテンシ)
• ツールおよび API の call (function call と外部リクエスト)
• システムコンテキスト (モデル名、Koog バージョン、環境メタデータ)

これらのトレースは Weave UI で可視化でき、パフォーマンスと品質の把握に役立ちます。Weave でトレースをキャプチャする方法の概要については、Weave のトレース概要 を参照してください。

​

サンプルノートブック

Weave にトレースをストリーミングする実行可能なノートブックについては、Koog のドキュメントを参照してください。

​

トラブルシューティング

• トレースが表示されない場合は、まず WEAVE_API_KEY、WEAVE_ENTITY、WEAVE_PROJECT_NAME が正しく設定されていることを確認してください。
• お使いの環境から https://trace.wandb.ai にアクセスできること、およびエクスポーターが上記のとおりに設定されていることを確認してください。
• 追加のトラブルシューティングとサンプリングのガイダンスについては、Koog の OpenTelemetry サポート を参照してください。