Agent Lens は Weights & Biases と同じバックエンドで動作するため、一部の設定名には
wandb 接頭辞が付いたままになっています。該当するのは、WANDB_API_KEY 環境変数、wandb-api-key ヘッダー、wandb.entity および wandb.project リソース属性です。これらの名前は記載どおりに使用してください。認証
スパンは次のエンドポイントに送信できます。- パス:
/agents/otel/v1/traces - メソッド:
POST - Content-Type:
application/x-protobuf - ベース URL: Multi-tenant Cloud の場合は
https://trace.wandb.ai
opentelemetry-exporter-otlp-proto-http (Python) や @opentelemetry/exporter-trace-otlp-proto (TypeScript) などの protobuf HTTP エクスポーターを使用してください。また、gzip および deflate のコンテンツエンコーディングも受け入れます。
エンドポイントで認証するには、OTLPSpanExporter の設定で、次のいずれかの値を使用して APIキー を指定します。
wandb-api-key: 値に Forge の APIキーを指定します。Authorization: ユーザーをapi、パスワードを Forge の APIキーとする HTTP Basic 認証を使用します。エクスポーターまたはコレクターが標準の認証ヘッダーしかサポートしていない場合は、この形式が便利です。
project のルーティング
Agent Lens は、OTel のリソース属性またはリクエストヘッダーを使用して、スパンを project にルーティングします。- リソース属性 (推奨) :
TracerProviderのリソースで、wandb.entityに Forge のチーム名またはユーザー名を、wandb.projectにプロジェクト名を設定します。 project_idヘッダー: 値を[YOUR-TEAM]/[YOUR-PROJECT]に設定します。
Conversations タブ向けにスパンを構成する
Agent Lens は任意の OTel スパンを受け入れ、そのすべての属性を保存しますが、Conversations タブでレンダリングされるのは OTel GenAI セマンティック規約に準拠したスパンです。各スパンにgen_ai.operation.name を設定して、そのスパンが何を表すかを Agent Lens に指定します。
グループ化は、さらに次の 2 つの属性で制御します。
gen_ai.conversation.id: ターンを会話にまとめます。会話の有効期間中は固定の ID を使用してください。gen_ai.agent.name: Conversations タブで、会話を名前付きのエージェントごとにまとめます。
gen_ai.request.model、gen_ai.usage.input_tokens、gen_ai.usage.output_tokens など、その他の GenAI セマンティック規約の属性を設定すると、モデル名やトークン数が表示に加わりますが、これらは必須ではありません。これらのスパンが対応するエージェントのデータモデルについては、エージェントをトレースするを参照してください。
環境変数のみで設定する
アプリケーションまたはコレクターが OTel 標準のエクスポーター用環境変数を読み取る場合は、以下の変数を設定するだけで、コードを一切変更せずにスパンを Agent Lens に送信できます。OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: エクスポーターがスパンを送信する Agent Lens のエンドポイントです。OTEL_EXPORTER_OTLP_TRACES_HEADERS: Forge の APIキーを使用して各リクエストを認証します。APIキーはwandb-api-keyヘッダーで送信されます。OTEL_RESOURCE_ATTRIBUTES: スパンの送信先 project を指定します。wandb.entityには Forge のチーム名またはユーザー名を、wandb.projectにはプロジェクト名を設定します。OTEL_EXPORTER_OTLP_TRACES_PROTOCOL: エクスポーターが HTTP 経由で OTLP protobuf を送信するように設定します。エンドポイントは protobuf ペイロードのみを受け入れるため、値にはhttp/protobufを指定する必要があります。
例: Agent Lens SDK を使わずにエージェント スパンを送信する
次の例では、OTel パッケージのみを使用して、最小構成のエージェントのターンをインストルメントします。ターンにはinvoke_agent スパン、LLM Call には chat スパン、ツール呼び出しには execute_tool スパンを送信し、それらを Agent Lens のエージェント エンドポイントにエクスポートします。
まず、必要な依存関係をインストールします。
YOUR-TEAM、YOUR-PROJECT、YOUR_API_KEY を実際の値に置き換えてから、コードを実行します。
gen_ai.conversation.id を持つ invoke_agent スパンを追加で出力します。各ターンはそれぞれ独立したトレースのルートスパンとなるため、ターン間で親スパンを共有する必要はありません。
アプリケーションがスパンをエクスポートしたら、Agent Lens project の Conversations ビューを開きます。