Démarrage rapide : configurer l’observabilité d’un agent personnalisé

Le SDK CoreWeave Forge vous permet de tracer des agents conçus avec des SDK populaires ou des harness personnalisés. Ce guide de démarrage rapide explique comment intégrer manuellement CoreWeave Agent Lens à un agent personnalisé fonctionnant sur plusieurs tours de conversation, afin d’émettre et de capturer des spans OpenTelemetry. Pour découvrir les concepts d’Agent Lens appliqués aux agents, consultez Tracer vos agents. Si vous souhaitez plutôt intégrer Agent Lens à des SDK ou à des harness tels que le Claude Agent SDK ou Codex, consultez Choisir une intégration d’agent. Agent Lens s’intègre automatiquement, par patch, à plusieurs SDK de création d’agents et harness d’agents, ce qui permet une intégration rapide.

Ce que vous allez apprendre

À la fin de ce démarrage rapide, vous disposerez d’un agent fonctionnel sur plusieurs tours de conversation qui émet des spans OTel compatibles avec Agent Lens. Vous comprendrez également comment Agent Lens fait correspondre les conversations, les tours de conversation, les appels LLM et les appels d’outil au code de votre agent, afin d’appliquer le même modèle à vos propres agents personnalisés. Le code de ce guide met en place un petit agent de recherche en Python ou en TypeScript capable de consulter Wikipédia. Il pose trois questions (trois tours de conversation) et laisse le LLM choisir quand effectuer une recherche sur Wikipédia pour trouver une réponse. Agent Lens enregistre chaque étape (la conversation, chaque question, chaque réponse de l’IA et chaque recherche sur Wikipédia) afin que vous puissiez voir ce qui s’est passé dans l’onglet Conversations d’Agent Lens. Ce guide vous montre comment :

Initialiser Agent Lens pour le traçage d’agents avec tracing.init().
Ouvrir une conversation et un tour de conversation avec start_conversation / startConversation et start_turn / startTurn.
Encapsuler les appels LLM avec start_llm / startLLM et enregistrer l’utilisation.
Encapsuler les exécutions d’outils avec start_tool / startTool et enregistrer les résultats.
Enregistrer l’utilisation complète des jetons et un modèle tarifable afin que le nombre de jetons et le coût s’affichent.
Afficher la conversation, les tours de conversation et les appels d’outil qui en résultent dans l’onglet Conversations.

Fonctionnement du SDK Agent Lens avec les agents

Le SDK Agent Lens intègre un système générique d’ingestion OTel pour les agents : Agent Lens peut donc capturer les informations de n’importe quel span OTel dans le code de votre agent. Toutefois, Agent Lens nécessite une gestion particulière des spans suivants pour effectuer le rendu des traces de votre agent dans l’onglet Conversations de l’interface Agent Lens.

Concept	Python	TypeScript	Span OTel
Une conversation	`tracing.start_conversation(...)`	`tracing.startConversation(...)`	(aucun span, regroupe les tours de conversation)
Un échange de l’utilisateur ou de l’agent	`tracing.start_turn(...)`	`tracing.startTurn(...)`	`invoke_agent`
Un appel d’API LLM	`tracing.start_llm(...)`	`tracing.startLLM(...)`	`chat`
Une exécution d’outil	`tracing.start_tool(...)`	`tracing.startTool(...)`	`execute_tool`

En Python, les quatre fonctions s’utilisent comme gestionnaires de contexte (with tracing.start_*(...) as obj:). À la sortie, elles terminent le span et vident les attributs, y compris en cas d’exception. En TypeScript, appelez .end() sur chaque objet renvoyé. Utilisez try { ... } finally { obj.end(); } pour garantir le nettoyage en cas d’exception, et encapsulez chaque run de l’agent dans tracing.runIsolated() afin que des runs simultanés ne partagent pas la même conversation. D’autres attributs des conventions sémantiques GenAI, tels que gen_ai.usage.* et gen_ai.agent.name, enrichissent le rendu, mais ils sont facultatifs.

Prérequis

Un compte CoreWeave Forge et une clé API.
Une clé API OpenAI.
Python 3.9 ou version ultérieure (pour les exemples Python).
Node.js 18 ou version ultérieure et un exécuteur TypeScript tel que tsx (les exemples TypeScript nécessitent la fonction fetch intégrée et ne sont pas du JavaScript pur).

Installer les packages

Installez les packages suivants dans votre environnement de développement :

pip install coreweave openai requests

npm install @coreweave/forge-sdk openai
npm install --save-dev tsx

Enregistrez les exemples TypeScript dans des fichiers .mts, puis exécutez-les avec npx tsx [FILENAME].mts.

Initialiser Agent Lens

tracing.init() s’authentifie à l’aide de votre clé API et configure l’exporteur OTel qui envoie les spans d’agent à Agent Lens. Le nom du projet doit inclure votre équipe. Le SDK lit la clé API dans la variable d’environnement WANDB_API_KEY, mais vous pouvez aussi la transmettre avec l’argument api_key / apiKey.

import getpass
import os

os.environ["WANDB_API_KEY"] = getpass.getpass("Enter your API key: ")
os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter your OpenAI API key: ")

TEAM = input("Enter your team name: ")
PROJECT = input("Enter your project name: ")

from coreweave.forge.agentlens import tracing
tracing.init(f"{TEAM}/{PROJECT}", autopatch_integrations=False)

// Définissez WANDB_API_KEY et OPENAI_API_KEY dans votre environnement avant d’exécuter ce projet
import { tracing } from '@coreweave/forge-sdk/agentlens';

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

Définir un outil

Le code suivant définit l’outil de recherche Wikipédia de l’agent, ainsi qu’un schéma d’outil OpenAI qui indique quand et comment l’utiliser.

import json
import requests

def wikipedia_search(query: str) -> str:
    r = requests.get(
        "https://en.wikipedia.org/w/api.php",
        params={
            "action": "query", "generator": "search", "gsrsearch": query, "gsrlimit": 1,
            "prop": "extracts", "exintro": True, "explaintext": True, "format": "json",
        },
        headers={"User-Agent": "agent-lens-demo"},
    ).json()
    return next(iter(r["query"]["pages"].values()))["extract"]

wikipedia_tool_schema = {
    "type": "function",
    "function": {
        "name": "wikipedia_search",
        "description": "Search Wikipedia for a topic and return its intro paragraph.",
        "parameters": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
        },
    },
}

async function wikipediaSearch(query: string): Promise<string> {
  const url = new URL('https://en.wikipedia.org/w/api.php');
  url.search = new URLSearchParams({
    action: 'query',
    generator: 'search',
    gsrsearch: query,
    gsrlimit: '1',
    prop: 'extracts',
    exintro: 'true',
    explaintext: 'true',
    format: 'json',
  }).toString();
  const res = await fetch(url, { headers: { 'User-Agent': 'agent-lens-demo' } });
  const data = (await res.json()) as {
    query: { pages: Record<string, { extract: string }> };
  };
  return Object.values(data.query.pages)[0].extract;
}

const wikipediaToolSchema = {
  type: 'function' as const,
  function: {
    name: 'wikipedia_search',
    description: 'Search Wikipedia for a topic and return its intro paragraph.',
    parameters: {
      type: 'object',
      properties: { query: { type: 'string' } },
      required: ['query'],
    },
  },
};

Exécuter un agent tracé sur plusieurs tours de conversation

Une fois l’outil et l’initialisation d’Agent Lens en place, l’étape suivante consiste à les réunir dans une boucle d’agent complète. Cette boucle montre comment les conversations, les tours de conversation, les appels LLM et les appels d’outil s’imbriquent. L’exemple suivant exécute trois tours de conversation au sein d’une même conversation. À chaque tour, l’agent :

Ouvre un span chat et laisse le LLM décider s’il doit appeler l’outil.
Si le LLM demande un outil, ouvre un span execute_tool autour de l’appel et renvoie le résultat au LLM.
Ouvre un second span chat pour produire la réponse finale.

Le SDK Agent Lens trace automatiquement les appels effectués avec les bibliothèques clientes OpenAI, Anthropic et Google Gen AI. Ce démarrage rapide enregistre manuellement chaque appel LLM avec start_llm() afin de montrer comment les spans s’articulent entre eux ; il transmet donc autopatch_integrations=False à init(). Sans cet argument, chaque appel serait enregistré deux fois : une fois par votre span start_llm() et une fois par l’intégration automatique. Transmettez cet argument dès votre premier appel à init(), car un appel ultérieur avec autopatch_integrations=False ne supprime pas les patchs appliqués par un appel précédent. Dans votre propre code, laissez le patching automatique enregistrer vos appels LLM, ou bien désactivez-le et enregistrez-les vous-même.

from coreweave.forge.agentlens import tracing
from openai import OpenAI

openai_client = OpenAI()
MODEL = "gpt-4o-mini"

def run_turn(history, user_message):
    history.append({"role": "user", "content": user_message})

    with tracing.start_turn(user_message=user_message, model=MODEL):
        # Appel LLM 1 : le modèle peut décider d’utiliser un outil.
        with tracing.start_llm(model=MODEL, provider_name="openai") as llm:
            resp = openai_client.chat.completions.create(
                model=MODEL, messages=history, tools=[wikipedia_tool_schema],
            )
            msg = resp.choices[0].message
            llm.output(msg.content or "")
            # record() définit en un seul appel l’utilisation, le modèle servant à la tarification et l’ID de réponse.
            llm.record(
                usage=tracing.Usage(
                    input_tokens=resp.usage.prompt_tokens,
                    output_tokens=resp.usage.completion_tokens,
                    cache_read_input_tokens=getattr(
                        resp.usage.prompt_tokens_details, "cached_tokens", 0
                    ),
                ),
                response_id=resp.id,
                response_model=resp.model,
            )
            history.append(msg.model_dump(exclude_none=True))

        # Si aucun outil n’a été demandé, la première réponse du LLM constitue la réponse finale.
        if not msg.tool_calls:
            return msg.content

        # Exécuter chaque appel d’outil demandé.
        for tc in msg.tool_calls:
            with tracing.start_tool(
                name=tc.function.name,
                arguments=tc.function.arguments,
                tool_call_id=tc.id,
            ) as tool:
                tool.result = wikipedia_search(**json.loads(tc.function.arguments))
                history.append({
                    "role": "tool",
                    "tool_call_id": tc.id,
                    "content": tool.result,
                })

        # Appel LLM 2 : synthétiser la réponse finale.
        with tracing.start_llm(model=MODEL, provider_name="openai") as llm:
            resp = openai_client.chat.completions.create(model=MODEL, messages=history)
            msg = resp.choices[0].message
            llm.output(msg.content)
            llm.record(
                usage=tracing.Usage(
                    input_tokens=resp.usage.prompt_tokens,
                    output_tokens=resp.usage.completion_tokens,
                    cache_read_input_tokens=getattr(
                        resp.usage.prompt_tokens_details, "cached_tokens", 0
                    ),
                ),
                response_id=resp.id,
                response_model=resp.model,
            )
            history.append({"role": "assistant", "content": msg.content})
            return msg.content

tracing.init(f"{TEAM}/{PROJECT}", autopatch_integrations=False)

with tracing.start_conversation(agent_name="research-bot") as conversation:
    history = []
    for question in [
        "Who founded Anthropic?",
        "What is Claude (the AI assistant)?",
        "Summarize what we discussed in one sentence.",
    ]:
        print(f"USER: {question}")
        print(f"AGENT: {run_turn(history, question)}\n")

tracing.shutdown()

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

const openaiClient = new OpenAI();
const MODEL = 'gpt-4o-mini';

// history est une liste de messages de chat OpenAI ; typage volontairement souple par souci de concision.
async function runTurn(history: any[], userMessage: string): Promise<string | null> {
  history.push({ role: 'user', content: userMessage });

  const turn = tracing.startTurn({ userMessage, model: MODEL });
  try {
    // Appel LLM 1 : le modèle peut choisir d'utiliser un outil.
    const llm1 = tracing.startLLM({ model: MODEL, providerName: 'openai' });
    let msg;
    try {
      const resp = await openaiClient.chat.completions.create({
        model: MODEL,
        messages: history,
        tools: [wikipediaToolSchema],
      });
      msg = resp.choices[0].message;
      llm1.output(msg.content ?? '');
      // record() définit l'utilisation, le modèle facturé et l'ID de réponse en un seul appel.
      llm1.record({
        usage: {
          inputTokens: resp.usage?.prompt_tokens,
          outputTokens: resp.usage?.completion_tokens,
          cacheReadInputTokens: resp.usage?.prompt_tokens_details?.cached_tokens,
        },
        responseId: resp.id,
        responseModel: resp.model,
      });
      history.push(msg);
    } finally {
      llm1.end();
    }

    // Si aucun outil n'a été demandé, la première réponse du LLM est la réponse finale.
    if (!msg.tool_calls?.length) {
      return msg.content ?? null;
    }

    // Exécuter chaque appel d'outil demandé.
    for (const tc of msg.tool_calls) {
      if (tc.type !== 'function') continue;
      const tool = tracing.startTool({
        name: tc.function.name,
        args: tc.function.arguments,
        toolCallId: tc.id,
      });
      try {
        const { query } = JSON.parse(tc.function.arguments);
        tool.result = await wikipediaSearch(query);
        history.push({ role: 'tool', tool_call_id: tc.id, content: tool.result });
      } finally {
        tool.end();
      }
    }

    // Appel LLM 2 : synthétiser la réponse finale.
    const llm2 = tracing.startLLM({ model: MODEL, providerName: 'openai' });
    try {
      const resp = await openaiClient.chat.completions.create({
        model: MODEL,
        messages: history,
      });
      const msg2 = resp.choices[0].message;
      llm2.output(msg2.content ?? '');
      llm2.record({
        usage: {
          inputTokens: resp.usage?.prompt_tokens,
          outputTokens: resp.usage?.completion_tokens,
          cacheReadInputTokens: resp.usage?.prompt_tokens_details?.cached_tokens,
        },
        responseId: resp.id,
        responseModel: resp.model,
      });
      history.push({ role: 'assistant', content: msg2.content });
      return msg2.content ?? null;
    } finally {
      llm2.end();
    }
  } finally {
    turn.end();
  }
}

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

await tracing.runIsolated(async () => {
  const conversation = tracing.startConversation({ agentName: 'research-bot' });
  try {
    const history: any[] = [];
    for (const question of [
      'Who founded Anthropic?',
      'What is Claude (the AI assistant)?',
      'Summarize what we discussed in one sentence.',
    ]) {
      console.log(`USER: ${question}`);
      console.log(`AGENT: ${await runTurn(history, question)}\n`);
    }
  } finally {
    conversation.end();
  }
});

await tracing.shutdown();

Enregistrer l’utilisation des jetons et le coût

Chaque span chat contient l’utilisation des jetons et un ID du modèle. Agent Lens affiche le nombre de jetons à partir de l’utilisation et calcule le coût à partir de l’utilisation et de l’ID du modèle. Une valeur incomplète ou impossible à tarifer affiche donc 0 in / 0 out jetons ou Cost -, même si le reste de la trace semble correct. record(...) définit ces champs (ainsi que output_messages, response_id, reasoning, etc.) en un seul appel. Seuls les champs que vous transmettez sont appliqués. Deux conditions doivent être remplies pour que le coût s’affiche :

Une utilisation complète. input_tokens correspond à l’entrée totale, jetons mis en cache compris. Agent Lens facture les lectures et les écritures de cache à leurs propres tarifs et les soustrait du total d’entrée : cache_read_input_tokens et cache_creation_input_tokens doivent donc être indiqués en plus d’un total input_tokens qui les inclut. Chez les fournisseurs proposant la mise en cache des prompts (par exemple, Anthropic), les jetons mis en cache représentent souvent l’essentiel de l’entrée : si vous les omettez, l’utilisation et le coût affichés seront quasi nuls.
Un ID du modèle tarifable. Transmettez l’ID précis renvoyé par la réponse (resp.model) en tant que response_model. Le coût est déterminé à partir du modèle. Agent Lens privilégie response_model (le modèle exact servi par le fournisseur) et, à défaut, utilise le model que vous avez transmis à start_llm. Un alias tel que opus ou sonnet n’est pas tarifable et affiche Cost -.

OpenAI inclut les jetons mis en cache dans prompt_tokens : l’exemple ci-dessus s’applique donc tel quel. Anthropic indique les jetons mis en cache séparément de input_tokens ; réintégrez-les donc dans le total sur lequel Agent Lens calcule le prix :

with tracing.start_llm(model=MODEL, provider_name="anthropic") as llm:
    resp = anthropic_client.messages.create(
        model=MODEL, max_tokens=1024, messages=history,
    )
    u = resp.usage
    llm.output(resp.content[0].text)
    llm.record(
        usage=tracing.Usage(
            input_tokens=u.input_tokens
            + u.cache_read_input_tokens
            + u.cache_creation_input_tokens,
            output_tokens=u.output_tokens,
            cache_read_input_tokens=u.cache_read_input_tokens,
            cache_creation_input_tokens=u.cache_creation_input_tokens,
        ),
        response_id=resp.id,
        response_model=resp.model,
    )

const u = resp.usage;
llm.record({
  usage: {
    inputTokens:
      u.input_tokens + u.cache_read_input_tokens + u.cache_creation_input_tokens,
    outputTokens: u.output_tokens,
    cacheReadInputTokens: u.cache_read_input_tokens,
    cacheCreationInputTokens: u.cache_creation_input_tokens,
  },
  responseId: resp.id,
  responseModel: resp.model,
});

Afficher les traces de votre agent dans l’onglet Conversations

Ouvrez votre projet dans Agent Lens et sélectionnez Conversations. Vous y trouverez :

Une conversation pour research-bot comportant trois tours de conversation.
Pour chaque tour de conversation (invoke_agent), deux spans chat et un span execute_tool imbriqués.
Pour chaque chat, le nombre de jetons, la latence, le modèle et l’échange de messages complet.

Sélectionnez la conversation pour examiner les entrées, les sorties, les arguments et les résultats des outils dans les onglets Thread et Spans.

Créer un lien vers une conversation depuis votre application

Pour créer un lien profond (deep link) depuis votre propre interface vers une conversation dans Agent Lens, vous avez besoin de l’ID de la conversation. start_conversation / startConversation l’expose via conversation_id / conversationId. Vous pouvez ainsi le journaliser ou le stocker avec votre propre ID de requête, puis ouvrir la conversation plus tard depuis l’onglet Conversations.

with tracing.start_conversation(agent_name="research-bot") as conversation:
    # ... exécuter les tours de conversation ...
    print(f"Agent Lens conversation ID: {conversation.conversation_id}")

await tracing.runIsolated(async () => {
  const conversation = tracing.startConversation({ agentName: 'research-bot' });
  try {
    // ... exécuter les tours de conversation ...
    console.log(`Agent Lens conversation ID: ${conversation.conversationId}`);
  } finally {
    conversation.end();
  }
});

Étapes suivantes

Découvrez comment tracer des agents avec Agent Lens, ainsi que les fonctionnalités et options disponibles dans le SDK Agent Lens.
Consultez Choisir une intégration d’agent pour découvrir d’autres façons d’intégrer Agent Lens à vos agents.

​Ce que vous allez apprendre

​Fonctionnement du SDK Agent Lens avec les agents

​Prérequis

​Installer les packages

​Initialiser Agent Lens

​Définir un outil

​Exécuter un agent tracé sur plusieurs tours de conversation

​Enregistrer l’utilisation des jetons et le coût

​Afficher les traces de votre agent dans l’onglet Conversations

​Créer un lien vers une conversation depuis votre application

​Étapes suivantes