Claude Agent SDK - CoreWeave Docs

Le Claude Agent SDK vous permet de créer rapidement des applications d’agents basées sur Claude. Vous pouvez intégrer CoreWeave Agent Lens à vos agents Claude pour tracer automatiquement leurs appels, notamment les requêtes des agents, les réponses du modèle, l’utilisation d’outils et les conversations sur plusieurs tours de conversation.

This integration uses the Weights & Biases Weave SDK (weave), because the CoreWeave Forge SDK doesn’t support this framework yet. Traces you send with Weave appear in Agent Lens, because both products share the same trace data.

Tracer des agents Claude Agent SDK avec Agent Lens

Python
TypeScript

Le SDK Weave patche automatiquement le Claude Agent SDK pour Python, ce qui vous permet de capturer les traces de vos agents Claude avec une configuration minimale.Ce guide explique comment initialiser Weave et exécuter, via query(), un agent Claude sur plusieurs tours de conversation doté d’outils MCP. Agent Lens trace automatiquement de bout en bout la conversation, les appels de modèle et les appels d’outil.

Prérequis

Un compte CoreWeave Forge et une clé API définie dans la variable d’environnement WANDB_API_KEY.
Une clé API Anthropic définie dans la variable d’environnement ANTHROPIC_API_KEY.
Python 3.10 ou version ultérieure.

Le SDK Weave s’intègre à @anthropic-ai/claude-agent-sdk pour tracer automatiquement les appels query(), y compris les spans d’agent, les réponses du modèle et les appels d’outil.

Prérequis

Un compte CoreWeave Forge et une clé API définie dans la variable d’environnement WANDB_API_KEY.
Une clé API Anthropic définie dans la variable d’environnement ANTHROPIC_API_KEY.
Node.js 18 ou version ultérieure.
@anthropic-ai/claude-agent-sdk version 0.3.178 ou ultérieure.

Installer les paquets

Installez les paquets suivants dans votre environnement de développement. Le paquet weave capture les traces, claude-agent-sdk fournit le runtime de l’agent et les autres paquets sont nécessaires à l’outil d’exemple.

pip install weave claude-agent-sdk requests

npm install weave @anthropic-ai/claude-agent-sdk zod

Initialiser Agent Lens dans votre code

Python
TypeScript

Ajoutez weave.init au projet, mettez à jour les noms de votre équipe et de votre projet Forge, puis créez un agent comme vous le feriez habituellement. weave.init active le patching automatique qui capture les traces du Claude Agent SDK.Cet exemple définit un outil MCP wikipedia_search et exécute une conversation en trois tours. Chaque tour de conversation correspond à un appel query() distinct, mais les tours suivants transmettent resume avec l’ID de session du premier tour, de sorte que tous les tours sont regroupés en une seule conversation dans l’onglet Conversations d’Agent Lens. Les deux premiers tours déclenchent des recherches sur Wikipédia, tandis que le troisième s’appuie sur le contexte de la conversation pour produire une synthèse sans appel d’outil.

import anyio
import requests
import weave

from claude_agent_sdk import (
    ClaudeAgentOptions,
    ResultMessage,
    create_sdk_mcp_server,
    query,
    tool,
)

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

@tool(
    "wikipedia_search",
    "Search Wikipedia for a topic and return its title and intro paragraph.",
    {"query": str},
)
async def wikipedia_search(args: dict) -> dict:
    r = requests.get(
        "https://en.wikipedia.org/w/api.php",
        params={
            "action": "query", "generator": "search", "gsrsearch": args["query"], "gsrlimit": 1,
            "prop": "extracts", "exintro": True, "explaintext": True, "format": "json",
        },
        headers={"User-Agent": "weave-demo"},
    ).json()
    page = next(iter(r["query"]["pages"].values()))
    return {"content": [{"type": "text", "text": f"{page['title']}: {page['extract']}"}]}

wiki_server = create_sdk_mcp_server(
    name="wiki",
    version="1.0.0",
    tools=[wikipedia_search],
)

async def main():
    session_id = None

    for question in [
        "Who founded Anthropic?",
        "What is Claude (the AI assistant)?",
        "Summarize what we discussed in one sentence.",
    ]:
        options = ClaudeAgentOptions(
            mcp_servers={"wiki": wiki_server},
            allowed_tools=["mcp__wiki__wikipedia_search"],
            resume=session_id,
        )
        print(f"USER: {question}")

        async for message in query(prompt=question, options=options):
            if isinstance(message, ResultMessage):
                session_id = message.session_id
                print(f"AGENT: {message.result}\n")


anyio.run(main)

Chaque appel à query() produit un span racine invoke_agent. Comme les tours de conversation suivants reprennent la même session, Weave appose le même gen_ai.conversation.id sur tous les spans, et Agent Lens les regroupe en une seule conversation. ResultMessage.session_id contient l’ID à réutiliser, et resume accepte None au premier tour de conversation, ce qui démarre une nouvelle session.Sans resume, chaque tour de conversation démarre sa propre session et apparaît comme une conversation distincte. ClaudeSDKClient fait exception : il maintient une session ouverte pendant toute la durée de vie du bloc async with, si bien que les tours de conversation que vous envoyez via le même client sont déjà regroupés. Weave patche ces deux approches.

Weave instrumente automatiquement query() au moyen de hooks du chargeur de modules. La configuration requise varie légèrement selon le système de modules. Pour plus d’informations sur les différences entre CommonJS et ESM et sur le fonctionnement des hooks de chargeur de Weave, consultez le guide d’intégration tierce du SDK TypeScript.

Projets CommonJS : aucune configuration supplémentaire n’est nécessaire. Chargez weave avec require avant @anthropic-ai/claude-agent-sdk afin que l’instrumentation automatique s’exécute en premier.
Projets ESM : démarrez Node avec l’option --import=weave/instrument afin que l’instrumentation se charge avant tout autre module.

Cet exemple définit un outil MCP wikipedia_search et exécute une conversation en trois tours. Chaque tour de conversation correspond à un appel query() distinct, mais les tours suivants transmettent resume avec le session_id du premier tour afin que tous les tours soient regroupés en une seule session dans les Conversations d’Agent Lens. Les deux premiers tours déclenchent des recherches sur Wikipédia, et le troisième s’appuie sur le contexte de la conversation pour produire une synthèse sans appel d’outil.

main.mjs

import * as weave from "weave";
import { createSdkMcpServer, query, tool, type Options } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const wikipediaSearch = tool(
    "wikipedia_search",
    "Search Wikipedia for a topic and return its title and intro paragraph.",
    { query: z.string().describe("The topic to search for") },
    async ({ query }) => {
    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 response = await fetch(url, { headers: { "User-Agent": "weave-demo" } });
    const data = await response.json();
    const page = Object.values(data.query.pages)[0] as { title: string; extract: string };
    return { content: [{ type: "text" as const, text: `${page.title}: ${page.extract}` }] };
    },
);

const wikiServer = createSdkMcpServer({
    name: "wiki",
    version: "1.0.0",
    tools: [wikipediaSearch],
});

async function main() {
    await weave.init("[YOUR-TEAM]/[YOUR-PROJECT]");

    const baseOptions: Options = {
    model: "claude-sonnet-4-5",
    maxTurns: 4,
    mcpServers: { wiki: wikiServer },
    allowedTools: ["mcp__wiki__wikipedia_search"],
    };

    const questions = [
    "Who founded Anthropic?",
    "What is Claude (the AI assistant)?",
    "Summarize what we discussed in one sentence.",
    ];

    let sessionId: string | undefined;

    for (const prompt of questions) {
    const options: Options = sessionId
        ? { ...baseOptions, resume: sessionId }
        : baseOptions;

    console.log(`USER: ${prompt}`);
    for await (const message of query({ prompt, options })) {
        if (message.type === "system" && message.subtype === "init") {
        sessionId ??= message.session_id;
        }
        if (message.type === "result" && message.subtype === "success") {
        console.log(`AGENT: ${message.result}\n`);
        }
    }
    }
}

main().catch(console.error);

Chaque appel à query() produit un span racine invoke_agent. Comme les tours de conversation suivants reprennent le même session_id, Agent Lens appose le même gen_ai.conversation.id sur tous les spans et les regroupe en une seule session dans la vue Conversations.Enregistrez l’exemple sous le nom main.mjs et exécutez-le avec l’option --import=weave/instrument afin que le hook du chargeur s’exécute avant tout autre module :

node --import=weave/instrument main.mjs

View your traces in Agent Lens

After the script runs, weave.init() prints a link to your project in Weave. The same traces appear in Agent Lens, because both products share the same trace data. To view them in Agent Lens:

Navigate to CoreWeave Forge and select Agent Lens from the product menu.
Select your project.
In the Agent Lens side menu, select Conversations, and then select your conversation.

Each turn renders as an invoke_agent span with nested chat and execute_tool spans. Each span shows its input, model, output, token usage, and tool results. For more information, see View agent activity.

​Tracer des agents Claude Agent SDK avec Agent Lens

​Prérequis

​Prérequis

​Installer les paquets

​Initialiser Agent Lens dans votre code

​View your traces in Agent Lens

Tracer des agents Claude Agent SDK avec Agent Lens

Prérequis

Prérequis

Installer les paquets

Initialiser Agent Lens dans votre code

View your traces in Agent Lens