Claude Agent SDK

Le Claude Agent SDK vous permet de créer rapidement des applications d’agents basées sur Claude. Vous pouvez intégrer Weave à 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. Weave affiche les données capturées dans la vue Agents de votre projet.

Tracer des agents Claude Agent SDK avec Weave

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 un agent Claude doté d’outils MCP sur plusieurs tours de conversation via query(). Weave 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.

Weave s’intègre à @anthropic-ai/claude-agent-sdk pour tracer automatiquement les appels query(), notamment 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 l’environnement d’exécution 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 Weave dans votre code

Python
TypeScript

Ajoutez weave.init au projet, mettez à jour les noms de votre équipe et de votre projet CoreWeave Forge, puis créez un agent comme vous le feriez habituellement. weave.init active le patching automatique qui capture les traces issues 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 afin que tous les tours soient regroupés en une seule conversation dans la vue Weave Agents. Les deux premiers tours déclenchent des recherches sur Wikipédia, tandis que le troisième s’appuie sur le contexte de la conversation précédente 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-name>")

@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 attribue le même gen_ai.conversation.id à tous les spans et les regroupe en une seule conversation dans la vue Agents. ResultMessage.session_id contient l’ID à réutiliser, et resume accepte None lors du premier tour, ce qui démarre une nouvelle session.Sans resume, chaque tour démarre sa propre session et apparaît comme une conversation distincte. ClaudeSDKClient fait exception : il maintient une même session ouverte pendant toute la durée du bloc async with, de sorte que les tours que vous envoyez via le même client sont déjà regroupés. Weave patche ces deux approches.

Weave instrumente automatiquement query() grâce aux hooks du chargeur de modules. La configuration requise diffère 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 du 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 la vue Weave Agents. Les deux premiers tours déclenchent des recherches sur Wikipédia, tandis que le troisième s’appuie sur le contexte de la conversation précédente 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-name>");

    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, Weave attribue le même gen_ai.conversation.id à tous les spans et les regroupe en une seule session dans la vue Agents.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

Consulter les traces de votre agent dans la vue Agents

Une fois le script exécuté, weave.init() affiche un lien vers votre projet. Ouvrez la vue Agents pour examiner :

Une session regroupant les tours de conversation.
Chaque tour de conversation, représenté par un span invoke_agent contenant des spans enfants imbriqués chat et execute_tool.
L’entrée complète, le modèle, la sortie, l’utilisation des jetons et les résultats des outils à chaque étape.

Pour en savoir plus sur l’affichage des données Agents dans Weave, consultez Afficher l’activité des agents.

Weights & Biases

Guides

Intégrations

Référence

Assistance

Tracer des agents Claude Agent SDK avec Weave

Prérequis

Prérequis

Installer les paquets

Initialiser Weave dans votre code

Consulter les traces de votre agent dans la vue Agents

​Tracer des agents Claude Agent SDK avec Weave

​Prérequis

​Prérequis

​Installer les paquets

​Initialiser Weave dans votre code

​Consulter les traces de votre agent dans la vue Agents

Tracer des agents Claude Agent SDK avec Weave

Prérequis

Prérequis

Installer les paquets

Initialiser Weave dans votre code

Consulter les traces de votre agent dans la vue Agents