Skip to main content
Koog は、シングル run 型のエージェントや複雑なワークフロー型のエージェントを構築するための Kotlin ベースのフレームワークです。Koog は OpenTelemetry (OTEL) のサポートを標準で備えており、トレースを Weave に直接エクスポートできます。これにより、プロンプト、完了結果、ツール呼び出し、エージェントの実行全体をエンドツーエンドで可視化できます。 このガイドでは、Koog の Weave エクスポーターを設定し、Kotlin エージェントから OpenTelemetry のスパンを Weave プロジェクトに転送する方法を説明します。エクスポーターを有効にすると、エージェントの run のデバッグやパフォーマンスの分析が可能になり、改善サイクルを速められます。このガイドは、すでに Koog でエージェントを構築しており、Weave によるトレースを導入したい Kotlin 開発者を対象としています。
Koog

前提条件

Weave エクスポーターが認証を行い、トレースを正しい project にルーティングできるように、エージェントを実行する前に次の環境変数を設定してください。 [YOUR-API-KEY] を CoreWeave Forge の APIキーに、[YOUR-ENTITY] を CoreWeave Forge のチーム名または entity 名に置き換えてください。WEAVE_PROJECT_NAME の値には任意のプロジェクト名を指定できます。project は初回使用時に Weave によって自動的に作成されます。

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

環境変数を設定したら、Kotlin プロジェクトに Koog を追加して、エージェントとそのエクスポーターを設定できるようにします (以下は Kotlin DSL の例です)。
インストールの詳細については、Koog のドキュメントを参照してください。

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

Koog をインストールしたら、Koog の OpenTelemetry 機能をインストールし、Weave エクスポーターを追加します。これにより、Weave の OpenTelemetry エンドポイントを介して、Koog のスパンが Weave のトレースにマッピングされます。 次の例は、addWeaveExporter の使い方を示しています。
この関数は Weave の環境変数を自動的に読み取りますが、次の例のように、エクスポーターの特定のパラメーターを明示的に設定することもできます。
上記の例では、次のことを行っています。
  • weaveEntity と weaveProjectName を使用して、トレースを特定のチームと project に送信します。
  • weaveOtelBaseUrl にトレースのエンドポイント (例: https://[YOUR-SUBDOMAIN].wandb.io/[PATH]) を設定します。専用クラウドの Weave インスタンスを使用する場合は、このパラメーターを指定してください。
Koog と Weave を初めて使用する場合は、次のドキュメントを参照してください。

トレースされる内容

エクスポーターを有効にしてエージェントを実行すると、Koog はトレースを Weave プロジェクトに転送します。Koog の Weave エクスポーターは、Koog の汎用 OTEL インテグレーションと同じスパンを取得します。主な内容は次のとおりです。
  • エージェントのライフサイクルイベント (開始、停止、エラー)
  • LLM とのやり取り (プロンプト、完了結果、トークン使用量、レイテンシー)
  • ツールおよび API の呼び出し (関数の Call と外部リクエスト)
  • システムコンテキスト (モデル名、Koog のバージョン、環境のメタデータ)
これらのトレースを Weights & Biases UI で可視化すると、パフォーマンスと品質を把握できます。Weave でトレースを取得する方法の概要については、Weave のトレースの概要を参照してください。

サンプルノートブック

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

トラブルシューティング

Koog エージェントからトレースが想定どおりにエクスポートされない場合は、以下を確認してください。
  • トレースが表示されない場合は、まず WEAVE_API_KEY、WEAVE_ENTITY、WEAVE_PROJECT_NAME が正しく設定されているかを確認してください。
  • 環境から https://trace.wandb.ai にアクセスできること、およびエクスポーターが前述の例のとおりに設定されていることを確認してください。
  • その他のトラブルシューティングやサンプリングに関するガイダンスについては、Koog の OpenTelemetry サポートを参照してください。
最終更新日 2026年9月30日