Reference media in your own bucket (BYOB) using agent spans

Use this technique when the media you want to see in Agent Lens already lives in your own bucket, such as:

Frames from a video pipeline.
Screenshots from a browser agent.
Images a model wrote to S3.

Instead of re-uploading those bytes, you log the object’s URI as a string, and Agent Lens renders the image or video inline from your bucket. Only the URI is sent to Agent Lens; the bytes stay in your bucket. Logging a 2 GB video costs the same as logging its path.

Reference buckets are separate from the secure storage connector, which backs Weights & Biases artifact and run storage. Reference buckets are configured per team and only need read access.

How it works

Reference media rendering works in three steps:

You store a media object in your bucket, for example s3://[YOUR-BUCKET]/frames/000123.png.
You log that URI as a string value in a span, such as a tool result.
When you open the conversation, Agent Lens resolves the URI to a short-lived presigned URL and renders it inline. The file extension decides how it renders. Common image formats (such as .png, .jpg, and .gif) and video formats (such as .mp4, .mov, and .webm) render inline. Other formats render as a download link.

Agent Lens only resolves URIs that point at a bucket registered for your team. Supported schemes are s3:// and gs://.

Prerequisites

A CoreWeave Forge account and API key.
A cloud storage bucket you control (S3 or GCS), containing at least one object.
Organization admin permissions. Adding a reference bucket requires the same permission as creating a team in the organization.

Configure your bucket

Grant CoreWeave Forge read access to the bucket, and allow the browser to fetch objects with CORS. When you view a conversation, Forge presigns a short-lived download URL for each referenced object. Grant the integration principal read access on the bucket so that presigning can succeed. This is read-only access for inline rendering.

AWS S3
Google Cloud Storage

Apply a bucket policy that grants the integration principal s3:GetObject. Save the following as bucket-policy.json, replacing [YOUR-BUCKET] with your bucket name:

{
  "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]/*"
  }]
}

Then apply it to your bucket:

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

Apply a CORS configuration that allows the Forge app to fetch objects in the browser. Save the following as cors.json:

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

Then apply it to your bucket:

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

If an object is encrypted with a customer-managed KMS key, its key policy must also grant arn:aws:iam::725579432336:role/WandbIntegration kms:Decrypt. The bucket policy alone isn’t sufficient.

Grant the integration service account roles/storage.objectViewer on the bucket. Replace [YOUR-BUCKET] with your bucket name:

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

Apply a CORS configuration that allows the Forge app to fetch objects in the browser. Save the following as cors.json:

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

Then apply it to your bucket:

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

If you configured the bucket earlier for Weave with only https://wandb.ai as an allowed origin, add https://forge.coreweave.com. Without it, the browser blocks the request, and referenced media doesn’t render in Agent Lens.

Register the reference bucket

In CoreWeave Forge, select Weights & Biases from the product menu.
In the side menu, under Teams, select your team, and then select the Settings tab. The team settings page is at https://forge.coreweave.com/wandb/[YOUR-TEAM]/settings.
In the Reference buckets section, select Add bucket.
Select your cloud provider (AWS or Google Cloud).
For the bucket name, enter [YOUR-BUCKET] only, without the s3:// or gs:// prefix.
For the object key, enter the key of an existing object in the bucket, for example photos/cat.png. Enter the object key only, not a full URL. Forge reads this one object to confirm that it has read access and that CORS is configured correctly. After the bucket is verified, presigning works for any object in the bucket.
Optionally, select Test connection to validate the configuration without saving.
Select Add bucket to save.

Until the bucket is registered, referenced URIs don’t render.

Log a media reference using agent spans

Return a bucket URI as an agent tool result and CoreWeave Agent Lens renders it inline in the Conversations tab, on the tool call that produced it. The following example opens a conversation, a turn, and a tool span, and sets a bucket URI as the tool’s result. Replace [YOUR-TEAM], [YOUR-PROJECT], and [YOUR-BUCKET] with your own values.

Python
TypeScript

from coreweave.forge.agentlens import tracing

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

# A tool that returns an object that already lives in your bucket.
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:
            # The result is a bucket URI string; it renders inline in the Conversations tab.
            tool.result = get_frame(123)

tracing.shutdown()

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

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

// A tool that returns an object that already lives in your bucket.
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',
  });
  // The result is a bucket URI string; it renders inline in the Conversations tab.
  tool.end({ result: getFrame(123) });
  turn.end();
  conversation.end();
});

await tracing.shutdown();

This example uses Agent Lens agent spans. For the full multi-turn setup, including LLM calls and a complete agent loop, see the custom agents quickstart.

The Agent Lens SDK doesn’t upload media into Agent Lens storage. It records the URI you return and Agent Lens resolves it against your registered bucket when someone views the conversation. Prefer URIs over inline bytes for large media, because inline content counts toward the size limit of each export request.

View the reference in Agent Lens

Open your project in Agent Lens and select the conversation on the Conversations tab. The referenced image or video renders inline in the Thread tab, on the tool call that returned the URI. If Agent Lens can’t resolve a URI, for example because the object is missing or the bucket isn’t registered, it shows the plain URI string.

​How it works

​Prerequisites

​Configure your bucket

​Register the reference bucket

​Log a media reference using agent spans

​View the reference in Agent Lens

How it works

Prerequisites

Configure your bucket

Register the reference bucket

Log a media reference using agent spans

View the reference in Agent Lens