Référencer des médias dans votre propre bucket (BYOB) à l’aide des spans d’agent

Utilisez cette technique lorsque les médias que vous souhaitez consulter dans Agent Lens se trouvent déjà dans votre propre bucket, par exemple :

Des images multimédias issues d’un pipeline vidéo.
Des captures d’écran d’un agent de navigation.
Des images écrites dans S3 par un modèle.

Au lieu de téléverser à nouveau ces octets, vous journalisez l’URI de l’objet sous forme de chaîne de caractères, et Agent Lens affiche l’image ou la vidéo directement depuis votre bucket. Seul l’URI est envoyé à Agent Lens ; les octets restent dans votre bucket. Journaliser une vidéo de 2 Go ne coûte pas plus cher que de journaliser son chemin.

Les buckets de référence sont distincts du connecteur de stockage sécurisé, sur lequel repose le stockage des artifacts et des runs de Weights & Biases. Les buckets de référence se configurent par équipe et ne nécessitent qu’un accès en lecture.

Fonctionnement

Le rendu des médias par référence s’effectue en trois étapes :

Vous stockez un objet multimédia dans votre bucket, par exemple s3://[YOUR-BUCKET]/frames/000123.png.
Vous journalisez cet URI sous forme de valeur de type chaîne dans un span, par exemple un résultat d’outil.
Lorsque vous ouvrez la conversation, Agent Lens résout l’URI en une URL présignée de courte durée et en affiche le rendu directement dans la page. C’est l’extension du fichier qui détermine le mode de rendu. Les formats d’image courants (comme .png, .jpg et .gif) et les formats vidéo (comme .mp4, .mov et .webm) s’affichent directement dans la page. Les autres formats s’affichent sous forme de lien de téléchargement.

Agent Lens ne résout que les URI qui pointent vers un bucket enregistré pour votre équipe. Les schémas pris en charge sont s3:// et gs://.

Prérequis

Un compte CoreWeave Forge et une clé API.
Un bucket de stockage cloud (S3 ou GCS) que vous gérez et qui contient au moins un objet.
Des autorisations d’administrateur de l’organisation. L’ajout d’un bucket de référence requiert la même autorisation que la création d’une équipe dans l’organisation.

Configurer votre bucket

Accordez à CoreWeave Forge un accès en lecture au bucket, puis autorisez le navigateur à récupérer les objets via CORS. Lorsque vous consultez une conversation, Forge génère une URL de téléchargement présignée de courte durée pour chaque objet référencé. Pour que la présignature aboutisse, accordez au principal d’intégration un accès en lecture sur le bucket. Cet accès en lecture seule sert uniquement à l’affichage intégré.

AWS S3
Google Cloud Storage

Appliquez une stratégie de bucket qui accorde s3:GetObject au principal d’intégration. Enregistrez le contenu suivant sous le nom bucket-policy.json, en remplaçant [YOUR-BUCKET] par le nom de votre 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]/*"
  }]
}

Appliquez-la ensuite à votre bucket :

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

Appliquez une configuration CORS qui autorise l’application Forge à récupérer les objets depuis le navigateur. Enregistrez le contenu suivant sous le nom cors.json :

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

Appliquez-la ensuite à votre bucket :

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

Si un objet est chiffré avec une clé KMS gérée par le client, la stratégie de cette clé doit également accorder kms:Decrypt à arn:aws:iam::725579432336:role/WandbIntegration. La stratégie de bucket seule ne suffit pas.

Accordez au compte de service d’intégration le rôle roles/storage.objectViewer sur le bucket. Remplacez [YOUR-BUCKET] par le nom de votre bucket :

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

Appliquez une configuration CORS qui autorise l’application Forge à récupérer les objets depuis le navigateur. Enregistrez le contenu suivant sous le nom cors.json :

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

Appliquez-la ensuite à votre bucket :

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

Si vous avez déjà configuré le bucket pour Weave avec https://wandb.ai comme seule origine autorisée, ajoutez https://forge.coreweave.com. Sinon, le navigateur bloque la requête et les médias référencés ne s’affichent pas dans Agent Lens.

Enregistrer le bucket de référence

Enregistrez le bucket dans les paramètres de votre équipe afin qu’Agent Lens puisse générer des URL présignées et afficher les URI référencés :

Dans CoreWeave Forge, sélectionnez Weights & Biases dans le menu des produits.
Dans le menu latéral, sous Teams, sélectionnez votre équipe, puis l’onglet Settings. La page des paramètres de l’équipe se trouve à l’adresse https://forge.coreweave.com/wandb/[YOUR-TEAM]/settings.
Dans la section Reference buckets, sélectionnez Add bucket.
Sélectionnez votre fournisseur de cloud (AWS ou Google Cloud).
Pour le nom du bucket, saisissez uniquement [YOUR-BUCKET], sans le préfixe s3:// ou gs://.
Pour la clé d’objet, saisissez la clé d’un objet existant dans le bucket, par exemple photos/cat.png. Saisissez uniquement la clé d’objet, et non une URL complète. Forge lit cet objet pour vérifier qu’il dispose d’un accès en lecture et que CORS est correctement configuré. Une fois le bucket vérifié, la génération d’URL présignées fonctionne pour n’importe quel objet du bucket.
Si vous le souhaitez, sélectionnez Test connection pour valider la configuration sans l’enregistrer.
Sélectionnez Add bucket pour enregistrer.

Tant que le bucket n’est pas enregistré, les URI référencés ne s’affichent pas.

Journaliser une référence multimédia à l’aide des spans d’agent

Renvoyez un URI de bucket comme résultat d’outil d’agent : CoreWeave Agent Lens l’affiche directement dans l’onglet Conversations, sur l’appel d’outil qui l’a produit. L’exemple suivant ouvre une conversation, un tour de conversation et un span d’outil, puis définit un URI de bucket comme résultat de l’outil. Remplacez [YOUR-TEAM], [YOUR-PROJECT] et [YOUR-BUCKET] par vos propres valeurs.

Python
TypeScript

from coreweave.forge.agentlens import tracing

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

# Un outil qui renvoie un objet déjà présent dans votre 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:
            # Le résultat est une chaîne d'URI de bucket ; il s'affiche directement dans l'onglet Conversations.
            tool.result = get_frame(123)

tracing.shutdown()

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

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

// Un outil qui renvoie un objet déjà présent dans votre 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',
  });
  // Le résultat est une chaîne d'URI de bucket ; il s'affiche directement dans l'onglet Conversations.
  tool.end({ result: getFrame(123) });
  turn.end();
  conversation.end();
});

await tracing.shutdown();

Cet exemple utilise les spans d’agent d’Agent Lens. Pour la configuration complète sur plusieurs tours de conversation, avec les appels LLM et une boucle d’agent complète, consultez le démarrage rapide des agents personnalisés.

Le SDK Agent Lens ne téléverse pas de contenu multimédia dans le stockage d’Agent Lens. Il enregistre l’URI que vous renvoyez, puis Agent Lens le résout à partir de votre bucket enregistré lorsqu’un utilisateur consulte la conversation. Pour les contenus multimédias volumineux, privilégiez les URI plutôt que les octets intégrés, car le contenu intégré est comptabilisé dans la limite de taille de chaque requête d’exportation.

Afficher la référence dans Agent Lens

Ouvrez votre projet dans Agent Lens et sélectionnez la conversation dans l’onglet Conversations. L’image ou la vidéo référencée s’affiche directement dans l’onglet Thread, au niveau de l’appel d’outil qui a renvoyé l’URI. Si Agent Lens ne parvient pas à résoudre une URI, par exemple parce que l’objet est introuvable ou que le bucket n’est pas enregistré, il affiche simplement l’URI sous forme de chaîne brute.

​Fonctionnement

​Prérequis

​Configurer votre bucket

​Enregistrer le bucket de référence

​Journaliser une référence multimédia à l’aide des spans d’agent

​Afficher la référence dans Agent Lens

Fonctionnement

Prérequis

Configurer votre bucket

Enregistrer le bucket de référence

Journaliser une référence multimédia à l’aide des spans d’agent

Afficher la référence dans Agent Lens