Passer au contenu principal
Le Claude Agent SDK est un SDK Python d’Anthropic conçu pour créer des applications agentiques avec Claude. W&B Weave trace automatiquement les appels du Claude Agent SDK lorsque vous appelez weave.init(), en capturant les requêtes, l’utilisation d’outils et les conversations sur plusieurs tours de conversation. Ce guide vous montre comment instrumenter une application Claude Agent SDK avec Weave afin d’inspecter chaque requête, chaque appel d’outil et chaque tour de conversation dans l’interface Weave. Il s’adresse aux développeurs qui créent des agents basés sur Claude et qui souhaitent une observabilité de bout en bout sans avoir à écrire de code de traçage personnalisé.

Prérequis

Avant d’exécuter l’exemple de code, effectuez la configuration suivante afin que Weave puisse s’authentifier et acheminer les traces vers votre projet :
  • Remplacez your-team-name dans l’appel à weave.init() par le nom de votre équipe W&B.
  • Définissez WANDB_API_KEY et ANTHROPIC_API_KEY dans votre environnement. Pour plus d’informations sur les clés API W&B, voir Clés API.

Installation

Installez les dépendances requises avec pip afin que Weave et le Claude Agent SDK soient tous deux disponibles dans votre environnement :
pip install weave claude-agent-sdk

Premiers pas

Cette section présente un exemple complet montrant comment Weave trace différents modes d’utilisation du Claude Agent SDK dans une seule exécution. Lorsque vous appelez weave.init() avant d’utiliser le Claude Agent SDK, Weave applique automatiquement un patch au SDK et trace chaque requête. L’exemple suivant met en évidence trois fonctionnalités :
  • Requêtes ponctuelles simples avec la fonction query(), y compris les réponses du modèle et le coût.
  • Utilisation d’outils MCP avec ClaudeSDKClient. Le Claude Agent SDK prend en charge les outils personnalisés via des serveurs MCP intégrés au processus.
    • Weave trace les définitions d’outils, les invocations d’outils et les résultats, en plus des requêtes de l’agent.
    • La démo MCP définit deux outils MCP et exécute une requête qui les utilise.
  • Conversations sur plusieurs tours de conversation que weave.thread() regroupe dans une trace unique. Weave capture chaque tour de conversation comme élément enfant du thread, afin que vous puissiez voir le déroulement complet de la conversation dans l’interface Weave.
"""Weave + Claude Agent SDK: tracing queries, tools, and conversations.

Call `weave.init()` to auto-patch the SDK — every query, tool call, and
multi-turn conversation is recorded as a trace you can inspect in the Weave UI.
"""

import anyio

import weave
from claude_agent_sdk import (
    AssistantMessage,
    ClaudeAgentOptions,
    ClaudeSDKClient,
    ResultMessage,
    TextBlock,
    ToolUseBlock,
    create_sdk_mcp_server,
    tool,
)

# --- 1. Définir les outils MCP ---

@tool("add", "Add two numbers", {"a": float, "b": float})
async def add(args: dict) -> dict:
    return {"content": [{"type": "text", "text": str(args["a"] + args["b"])}]}


@tool("multiply", "Multiply two numbers", {"a": float, "b": float})
async def multiply(args: dict) -> dict:
    return {"content": [{"type": "text", "text": str(args["a"] * args["b"])}]}


math_server = create_sdk_mcp_server(
    name="math", version="1.0.0", tools=[add, multiply],
)


# --- 2. Requête simple one-shot ---

async def simple_query():
    from claude_agent_sdk import query

    async for msg in query(prompt="What is 2+2?"):
        if isinstance(msg, AssistantMessage):
            for block in msg.content:
                if isinstance(block, TextBlock):
                    print(block.text, end="")
        elif isinstance(msg, ResultMessage):
            print(f"\ncost=${msg.total_cost_usd:.4f}")


# --- 3. Utilisation des outils MCP ---

async def tool_query():
    options = ClaudeAgentOptions(
        mcp_servers={"math": math_server},
        allowed_tools=["mcp__math__add", "mcp__math__multiply"],
    )

    async with ClaudeSDKClient(options=options) as client:
        await client.query("Using the math tools, compute (3 + 7) * 2.")
        async for msg in client.receive_response():
            if isinstance(msg, AssistantMessage):
                for block in msg.content:
                    if isinstance(block, ToolUseBlock):
                        print(f"  [tool] {block.name}({block.input})")
                    elif isinstance(block, TextBlock):
                        print(block.text, end="")
            elif isinstance(msg, ResultMessage):
                print(f"\ncost=${msg.total_cost_usd:.4f}")


# --- 4. Conversation sur plusieurs tours de conversation avec contexte de thread ---

async def threaded_conversation():
    with weave.thread("my-conversation") as t:
        print(f"thread_id={t.thread_id}")

        async with ClaudeSDKClient() as client:
            for prompt in [
                "Name a famous sorting algorithm.",
                "What is its time complexity?",
            ]:
                await client.query(prompt)
                reply = ""
                async for msg in client.receive_response():
                    if isinstance(msg, AssistantMessage):
                        reply += "".join(
                            b.text for b in msg.content if isinstance(b, TextBlock)
                        )
                    elif isinstance(msg, ResultMessage):
                        print(f"Q: {prompt}\nA: {reply.strip()[:120]}\n")


# --- Exécuter tous les exemples ---

async def main():
    print("=== Simple Query ===")
    await simple_query()

    print("\n=== MCP Tool Use ===")
    await tool_query()

    print("\n=== Multi-Turn Thread ===")
    await threaded_conversation()


if __name__ == "__main__":
    weave.init("your-team-name/claude-agent-sdk-demo")
    anyio.run(main)

Voir les traces

Après avoir exécuté l’exemple, Weave enregistre un ensemble de traces dans votre projet, que vous pouvez utiliser pour déboguer et analyser le comportement de votre agent. Lorsque vous exécutez l’exemple, Weave affiche des liens vers le tableau de bord Weave. Suivez-les pour voir vos traces, notamment les entrées de requête, les réponses du modèle, les appels d’outils et les fils de conversation.