Skip to main content
W&B Weave のエージェント オブザーバビリティは、OpenTelemetry (OTel) を基盤としています。Weave には、スパンを Agents ビューに取り込む専用の OTLP エンドポイントがあります。エージェントがすでに OTel スパンを出力している場合は、Weave SDK をインストールしなくても、既存の OTel パイプラインの送信先をこのエンドポイントに設定するだけで Weave に送信できます。 このページでは、エンドポイントへの認証方法と、エンドポイントにスパンを送信する方法について説明します。

認証

スパンは次のエンドポイントに送信できます。
  • Path: /agents/otel/v1/traces
  • Method: POST
  • Content-Type: application/x-protobuf
  • Base URL: Multi-tenant Cloud の場合は https://trace.wandb.ai
このエンドポイントは、OTLP protobuf ペイロードのみを受け付けます。opentelemetry-exporter-otlp-proto-http (Python) や @opentelemetry/exporter-trace-otlp-proto (TypeScript) などの protobuf HTTP exporter を使用してください。また、このエンドポイントはコンテンツエンコーディングとして gzipdeflate も受け付けます。 エンドポイントで認証するには、次のいずれかの値を使用して、OTLPSpanExporter の設定に W&B APIキー を指定します。
  • wandb-api-key: 値に W&B APIキーを指定します。
  • Authorization: ユーザー名に api、パスワードに W&B APIキーを使用する HTTP Basic 認証です。この形式は、exporter または collector が標準の Authorization ヘッダーしかサポートしていない場合に便利です。

project のルーティング

Weave は、OTel のリソース属性またはリクエストヘッダーを使用して、スパンを project にルーティングします。
  • リソース属性 (推奨) : TracerProvider のリソースで、wandb.entity にご利用の W&B チーム名またはユーザー名を、wandb.project にプロジェクト名を設定します。
  • project_id ヘッダー: 値に [YOUR-TEAM]/[YOUR-PROJECT] を設定します。
両方が存在する場合は、リソース属性が優先されます。entity と project が指定されていないスパンは破棄されます。

Agents ビュー向けにスパンを整形する

Weave は任意の OTel スパンを受け入れ、すべての属性を保存しますが、Agents ビューで表示されるのは OTel GenAI semantic conventions に従ったスパンです。各スパンが何を表すかを Weave に伝えるには、各スパンで gen_ai.operation.name を設定します。 グループ化を制御する属性が、ほかに 2 つあります。
  • gen_ai.conversation.id: ターンを 1 つの会話にグループ化します。会話の存続期間を通じて安定した ID を使用してください。
  • gen_ai.agent.name: Agents タブで、会話を名前付きエージェントの下にグループ化します。
gen_ai.request.modelgen_ai.usage.input_tokensgen_ai.usage.output_tokens など、ほかの GenAI semantic-convention 属性を指定すると、モデル名やトークン数が表示に追加されますが、これらは省略可能です。これらのスパンがマッピングされるエージェントのデータモデルについては、Trace your agents を参照してください。

環境変数のみで設定する

お使いのアプリケーションまたは collector が標準の OTel exporter 用環境変数を読み取る場合は、コードを一切変更せずに、次の環境変数を設定するだけでスパンを Weave に送信できます。

例: Weave SDK を使わずにエージェント スパンを送信する

次の例では、OTel パッケージのみを使用して、最小限のエージェント ターンをインストルメントします。ターンに対して invoke_agent スパン、LLM Call に対して chat スパン、ツール呼び出し に対して execute_tool スパンを送信し、その後それらを Weave Agents エンドポイントにエクスポートします。 まず、必要な依存関係をインストールします。
次に、以下のコードで WANDB_API_KEYENTITYPROJECT の値を設定してから実行します。
同じ会話にさらにターンを追加するには、同じ gen_ai.conversation.id を持つ invoke_agent スパンを追加で生成します。各ターンはそれぞれ独立したトレースのルートスパンであるため、ターン間で親スパンを共有する必要はありません。 アプリケーションがスパンをエクスポートしたら、Weave projectの Agents タブを開きます。