エージェントスパンを使用して独自のバケット (BYOB) 内のメディアを参照する

Agent Lens で表示したいメディアがすでに独自のバケットに保存されている場合は、この手法を使用します。たとえば、次のようなケースです。

動画パイプラインから出力されたフレーム
ブラウザーエージェントが撮影したスクリーンショット
モデルが S3 に書き込んだ画像

データを再アップロードする代わりに、オブジェクトの URI を string としてログすると、Agent Lens がバケットから画像や動画を直接インラインでレンダリングします。Agent Lens に送信されるのは URI のみで、データ本体はバケット内に保持されたままです。そのため、2 GB の動画をログしても、そのパスをログするのと同じコストしかかかりません。

参照バケットは、Weights & Biases のアーティファクトと run のストレージとして使用されるセキュアストレージコネクタとは別の機能です。参照バケットはチームごとに設定し、読み取りアクセス権のみが必要です。

仕組み

参照メディアのレンダリングは、次の 3 つのステップで行われます。

メディアオブジェクトをバケットに保存します (例: s3://[YOUR-BUCKET]/frames/000123.png) 。
その URI を、ツール結果などのスパン内に string 値としてログします。
会話を開くと、Agent Lens が URI を有効期間の短い事前署名付き URL に解決し、インラインでレンダリングします。レンダリング方法はファイルの拡張子によって決まります。一般的な画像形式 (.png、.jpg、.gif など) と動画形式 (.mp4、.mov、.webm など) はインラインでレンダリングされ、それ以外の形式はダウンロードリンクとして表示されます。

Agent Lens は、チームに登録されたバケットを指す URI のみを解決します。サポートされるスキームは s3:// と gs:// です。

前提条件

CoreWeave Forge アカウントと APIキー。
自身が管理するクラウドストレージバケット (S3 または GCS) 。バケットには 1 つ以上のオブジェクトが含まれている必要があります。
組織管理者の権限。参照バケットを追加するには、組織内でチームを作成する場合と同じ権限が必要です。

バケットを設定する

CoreWeave Forge にバケットへの読み取りアクセス権を付与し、ブラウザーが CORS を使用してオブジェクトを取得できるようにします。会話を表示すると、Forge は参照される各オブジェクトについて、有効期間の短い署名付きダウンロード URL を生成します。署名付き URL を正しく生成できるよう、インテグレーションのプリンシパルにバケットへの読み取りアクセス権を付与してください。このアクセス権は、インラインでレンダリングするための読み取り専用のものです。

AWS S3
Google Cloud Storage

インテグレーションのプリンシパルに s3:GetObject を付与するバケットポリシーを適用します。次の内容を bucket-policy.json として保存し、[YOUR-BUCKET] をバケット名に置き換えます。

{
  "Version": "2012-10-17",
  "Id": "WandBAccess",
  "Statement": [{
    "Sid": "WandbAccess",
    "Effect": "Allow",
    "Principal": {"AWS": "arn:aws:iam::725579432336:role/WandbIntegration"},
    "Action": "s3:GetObject",
    "Resource": "arn:aws:s3:::[YOUR-BUCKET]/*"
  }]
}

次に、このポリシーをバケットに適用します。

aws s3api put-bucket-policy --bucket [YOUR-BUCKET] --policy file://bucket-policy.json

Forge アプリがブラウザーでオブジェクトを取得できるように、CORS 設定を適用します。次の内容を cors.json として保存します。

{
  "CORSRules": [{
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "HEAD"],
    "AllowedOrigins": ["https://forge.coreweave.com"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3000
  }]
}

次に、この設定をバケットに適用します。

aws s3api put-bucket-cors --bucket [YOUR-BUCKET] --cors-configuration file://cors.json

オブジェクトがカスタマー管理の KMS キーで暗号化されている場合は、そのキーポリシーでも arn:aws:iam::725579432336:role/WandbIntegration に kms:Decrypt を付与する必要があります。バケットポリシーだけでは不十分です。

インテグレーションのサービスアカウントに、バケットに対する roles/storage.objectViewer を付与します。[YOUR-BUCKET] はバケット名に置き換えてください。

gcloud storage buckets add-iam-policy-binding gs://[YOUR-BUCKET] \
  --member="serviceAccount:wandb-integration@wandb-production.iam.gserviceaccount.com" \
  --role="roles/storage.objectViewer"

Forge アプリがブラウザーでオブジェクトを取得できるように、CORS 設定を適用します。次の内容を cors.json として保存します。

[{
  "origin": ["https://forge.coreweave.com"],
  "method": ["GET", "HEAD"],
  "responseHeader": ["ETag"],
  "maxAgeSeconds": 3000
}]

次に、この設定をバケットに適用します。

gcloud storage buckets update gs://[YOUR-BUCKET] --cors-file=cors.json

以前に Weave 用のバケットを設定した際、許可するオリジンとして https://wandb.ai のみを指定していた場合は、https://forge.coreweave.com を追加してください。追加しないとブラウザーがリクエストをブロックするため、参照先のメディアが Agent Lens でレンダリングされません。

参照バケットを登録する

Agent Lens が参照先の URI の署名付き URL を生成して表示できるように、チーム設定でバケットを登録します。

CoreWeave Forge で、プロダクトメニューから Weights & Biases を選択します。
サイドメニューの Teams でチームを選択し、Settings タブを選択します。チーム設定ページの URL は https://forge.coreweave.com/wandb/[YOUR-TEAM]/settings です。
Reference buckets セクションで、Add bucket を選択します。
クラウドプロバイダー (AWS または Google Cloud) を選択します。
バケット名には、s3:// や gs:// の接頭辞を付けずに [YOUR-BUCKET] のみを入力します。
オブジェクトキーには、バケット内に存在するオブジェクトのキー (例: photos/cat.png) を入力します。完全な URL ではなく、オブジェクトキーのみを入力してください。Forge はこのオブジェクトを 1 つ読み取り、読み取りアクセス権があることと CORS が正しく設定されていることを確認します。バケットが検証されると、バケット内のどのオブジェクトに対しても署名付き URL を生成できるようになります。
必要に応じて Test connection を選択すると、保存せずに設定を検証できます。
Add bucket を選択して保存します。

バケットを登録するまで、参照先の URI はレンダリングされません。

エージェントスパンを使用してメディア参照をログする

エージェントのツール結果としてバケット URI を返すと、CoreWeave Agent Lens は Conversations タブで、その URI を生成したツール呼び出しにインラインでレンダリングします。次の例では、会話、ターン、ツールスパンを開始し、バケット URI をツールの結果として設定します。[YOUR-TEAM]、[YOUR-PROJECT]、[YOUR-BUCKET] はご自身の値に置き換えてください。

Python
TypeScript

from coreweave.forge.agentlens import tracing

tracing.init("[YOUR-TEAM]/[YOUR-PROJECT]")

# バケット内にすでに存在するオブジェクトを返すツール。
def get_frame(frame_id: int) -> str:
    return f"s3://[YOUR-BUCKET]/frames/{frame_id:06d}.png"

with tracing.start_conversation(agent_name="frame-labeler") as conversation:
    with tracing.start_turn(user_message="Show me frame 123", model="gpt-4o-mini"):
        with tracing.start_tool(
            name="get_frame",
            arguments='{"frame_id": 123}',
            tool_call_id="call_1",
        ) as tool:
            # 結果はバケット URI 文字列で、Conversations タブにインラインでレンダリングされます。
            tool.result = get_frame(123)

tracing.shutdown()

import { tracing } from '@coreweave/forge-sdk/agentlens';

await tracing.init('[YOUR-TEAM]/[YOUR-PROJECT]');

// バケット内にすでに存在するオブジェクトを返すツール。
function getFrame(frameId: number): string {
  return `s3://[YOUR-BUCKET]/frames/${String(frameId).padStart(6, '0')}.png`;
}

await tracing.runIsolated(async () => {
  const conversation = tracing.startConversation({ agentName: 'frame-labeler' });
  const turn = tracing.startTurn({ userMessage: 'Show me frame 123', model: 'gpt-4o-mini' });
  const tool = tracing.startTool({
    name: 'getFrame',
    args: JSON.stringify({ frameId: 123 }),
    toolCallId: 'call_1',
  });
  // 結果はバケット URI 文字列で、Conversations タブにインラインでレンダリングされます。
  tool.end({ result: getFrame(123) });
  turn.end();
  conversation.end();
});

await tracing.shutdown();

この例では Agent Lens のエージェントスパンを使用しています。LLM Call や完全なエージェントループを含む、マルチターンの完全なセットアップについては、カスタムエージェントのクイックスタートを参照してください。

Agent Lens SDK は、メディアを Agent Lens のストレージにアップロードしません。SDK は返された URI を記録するだけで、会話が表示される際に Agent Lens が登録済みのバケットを参照してその URI を解決します。インラインのコンテンツは各エクスポートリクエストのサイズ上限に含まれるため、サイズの大きいメディアにはインラインのバイトデータではなく URI を使用することをお勧めします。

Agent Lens で参照を表示する

Agent Lens で project を開き、Conversations タブで会話を選択します。参照先の画像や動画は、Thread タブで、その URI を返したツール呼び出しの箇所にインラインでレンダリングされます。オブジェクトが存在しない、バケットが登録されていないなどの理由で Agent Lens が URI を解決できない場合は、URI 文字列がそのまま表示されます。

​仕組み

​前提条件

​バケットを設定する

​参照バケットを登録する

​エージェント スパンを使用してメディア参照をログする

​Agent Lens で参照を表示する

仕組み

前提条件

バケットを設定する

参照バケットを登録する

エージェントスパンを使用してメディア参照をログする

Agent Lens で参照を表示する