Guides

Outils Personnalisés

Créez et intégrez des outils personnalisés pour étendre les fonctionnalités du Claude Agent SDK

Les outils personnalisés vous permettent d'étendre les capacités de Claude Code avec vos propres fonctionnalités via des serveurs MCP en processus, permettant à Claude d'interagir avec des services externes, des API, ou d'effectuer des opérations spécialisées.

Création d'Outils Personnalisés

Utilisez les fonctions d'aide createSdkMcpServer et tool pour définir des outils personnalisés type-safe :

TypeScript

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

// Créer un serveur MCP SDK avec des outils personnalisés
const customServer = createSdkMcpServer({
  name: "my-custom-tools",
  version: "1.0.0",
  tools: [
    tool(
      "get_weather",
      "Obtenir la température actuelle d'un lieu en utilisant les coordonnées",
      {
        latitude: z.number().describe("Coordonnée de latitude"),
        longitude: z.number().describe("Coordonnée de longitude")
      },
      async (args) => {
        const response = await fetch(`https://api.open-meteo.com/v1/forecast?latitude=${args.latitude}&longitude=${args.longitude}&current=temperature_2m&temperature_unit=fahrenheit`);
        const data = await response.json();

        return {
          content: [{
            type: "text",
            text: `Température : ${data.current.temperature_2m}°F`
          }]
        };
      }
    )
  ]
});

Python

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeSDKClient, ClaudeAgentOptions
from typing import Any
import aiohttp

# Définir un outil personnalisé en utilisant le décorateur @tool
@tool("get_weather", "Obtenir la température actuelle d'un lieu en utilisant les coordonnées", {"latitude": float, "longitude": float})
async def get_weather(args: dict[str, Any]) -> dict[str, Any]:
    # Appeler l'API météo
    async with aiohttp.ClientSession() as session:
        async with session.get(
            f"https://api.open-meteo.com/v1/forecast?latitude={args['latitude']}&longitude={args['longitude']}&current=temperature_2m&temperature_unit=fahrenheit"
        ) as response:
            data = await response.json()

    return {
        "content": [{
            "type": "text",
            "text": f"Température : {data['current']['temperature_2m']}°F"
        }]
    }

# Créer un serveur MCP SDK avec l'outil personnalisé
custom_server = create_sdk_mcp_server(
    name="my-custom-tools",
    version="1.0.0",
    tools=[get_weather]  # Passer la fonction décorée
)

Utilisation d'Outils Personnalisés

Passez le serveur personnalisé à la fonction query via l'option mcpServers comme un dictionnaire/objet.

Important : Les outils MCP personnalisés nécessitent le mode d'entrée en streaming. Vous devez utiliser un générateur/itérable asynchrone pour le paramètre prompt - une simple chaîne ne fonctionnera pas avec les serveurs MCP.

Format des Noms d'Outils

Lorsque les outils MCP sont exposés à Claude, leurs noms suivent un format spécifique :

Modèle : mcp__{server_name}__{tool_name}
Exemple : Un outil nommé get_weather dans le serveur my-custom-tools devient mcp__my-custom-tools__get_weather

Configuration des Outils Autorisés

Vous pouvez contrôler quels outils Claude peut utiliser via l'option allowedTools :

import { query } from "@anthropic-ai/claude-agent-sdk";

// Utiliser les outils personnalisés dans votre requête avec entrée en streaming
async function* generateMessages() {
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Quel temps fait-il à San Francisco ?"
    }
  };
}

for await (const message of query({
  prompt: generateMessages(),  // Utiliser un générateur asynchrone pour l'entrée en streaming
  options: {
    mcpServers: {
      "my-custom-tools": customServer  // Passer comme objet/dictionnaire, pas comme tableau
    },
    // Spécifier optionnellement quels outils Claude peut utiliser
    allowedTools: [
      "mcp__my-custom-tools__get_weather",  // Autoriser l'outil météo
      // Ajouter d'autres outils selon les besoins
    ],
    maxTurns: 3
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Exemple avec Plusieurs Outils

Lorsque votre serveur MCP a plusieurs outils, vous pouvez les autoriser sélectivement :

const multiToolServer = createSdkMcpServer({
  name: "utilities",
  version: "1.0.0",
  tools: [
    tool("calculate", "Effectuer des calculs", { /* ... */ }, async (args) => { /* ... */ }),
    tool("translate", "Traduire du texte", { /* ... */ }, async (args) => { /* ... */ }),
    tool("search_web", "Rechercher sur le web", { /* ... */ }, async (args) => { /* ... */ })
  ]
});

// Autoriser seulement des outils spécifiques avec entrée en streaming
async function* generateMessages() {
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Calcule 5 + 3 et traduis 'bonjour' en espagnol"
    }
  };
}

for await (const message of query({
  prompt: generateMessages(),  // Utiliser un générateur asynchrone pour l'entrée en streaming
  options: {
    mcpServers: {
      utilities: multiToolServer
    },
    allowedTools: [
      "mcp__utilities__calculate",   // Autoriser la calculatrice
      "mcp__utilities__translate",   // Autoriser le traducteur
      // "mcp__utilities__search_web" n'est PAS autorisé
    ]
  }
})) {
  // Traiter les messages
}

Sécurité de Type avec Python

Le décorateur @tool prend en charge diverses approches de définition de schéma pour la sécurité de type :

import { z } from "zod";

tool(
  "process_data",
  "Traiter des données structurées avec sécurité de type",
  {
    // Le schéma Zod définit à la fois la validation d'exécution et les types TypeScript
    data: z.object({
      name: z.string(),
      age: z.number().min(0).max(150),
      email: z.string().email(),
      preferences: z.array(z.string()).optional()
    }),
    format: z.enum(["json", "csv", "xml"]).default("json")
  },
  async (args) => {
    // args est entièrement typé basé sur le schéma
    // TypeScript sait : args.data.name est string, args.data.age est number, etc.
    console.log(`Traitement des données de ${args.data.name} en tant que ${args.format}`);
    
    // Votre logique de traitement ici
    return {
      content: [{
        type: "text",
        text: `Données traitées pour ${args.data.name}`
      }]
    };
  }
)

Gestion des Erreurs

Gérez les erreurs avec élégance pour fournir un retour significatif :

tool(
  "fetch_data",
  "Récupérer des données depuis une API",
  {
    endpoint: z.string().url().describe("URL du point de terminaison API")
  },
  async (args) => {
    try {
      const response = await fetch(args.endpoint);
      
      if (!response.ok) {
        return {
          content: [{
            type: "text",
            text: `Erreur API : ${response.status} ${response.statusText}`
          }]
        };
      }
      
      const data = await response.json();
      return {
        content: [{
          type: "text",
          text: JSON.stringify(data, null, 2)
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Échec de récupération des données : ${error.message}`
        }]
      };
    }
  }
)

Exemples d'Outils

Outil de Requête de Base de Données

const databaseServer = createSdkMcpServer({
  name: "database-tools",
  version: "1.0.0",
  tools: [
    tool(
      "query_database",
      "Exécuter une requête de base de données",
      {
        query: z.string().describe("Requête SQL à exécuter"),
        params: z.array(z.any()).optional().describe("Paramètres de requête")
      },
      async (args) => {
        const results = await db.query(args.query, args.params || []);
        return {
          content: [{
            type: "text",
            text: `Trouvé ${results.length} lignes :\n${JSON.stringify(results, null, 2)}`
          }]
        };
      }
    )
  ]
});

Outil de Passerelle API

const apiGatewayServer = createSdkMcpServer({
  name: "api-gateway",
  version: "1.0.0",
  tools: [
    tool(
      "api_request",
      "Effectuer des requêtes API authentifiées vers des services externes",
      {
        service: z.enum(["stripe", "github", "openai", "slack"]).describe("Service à appeler"),
        endpoint: z.string().describe("Chemin du point de terminaison API"),
        method: z.enum(["GET", "POST", "PUT", "DELETE"]).describe("Méthode HTTP"),
        body: z.record(z.any()).optional().describe("Corps de la requête"),
        query: z.record(z.string()).optional().describe("Paramètres de requête")
      },
      async (args) => {
        const config = {
          stripe: { baseUrl: "https://api.stripe.com/v1", key: process.env.STRIPE_KEY },
          github: { baseUrl: "https://api.github.com", key: process.env.GITHUB_TOKEN },
          openai: { baseUrl: "https://api.openai.com/v1", key: process.env.OPENAI_KEY },
          slack: { baseUrl: "https://slack.com/api", key: process.env.SLACK_TOKEN }
        };
        
        const { baseUrl, key } = config[args.service];
        const url = new URL(`${baseUrl}${args.endpoint}`);
        
        if (args.query) {
          Object.entries(args.query).forEach(([k, v]) => url.searchParams.set(k, v));
        }
        
        const response = await fetch(url, {
          method: args.method,
          headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
          body: args.body ? JSON.stringify(args.body) : undefined
        });
        
        const data = await response.json();
        return {
          content: [{
            type: "text",
            text: JSON.stringify(data, null, 2)
          }]
        };
      }
    )
  ]
});

Outil Calculatrice

const calculatorServer = createSdkMcpServer({
  name: "calculator",
  version: "1.0.0",
  tools: [
    tool(
      "calculate",
      "Effectuer des calculs mathématiques",
      {
        expression: z.string().describe("Expression mathématique à évaluer"),
        precision: z.number().optional().default(2).describe("Précision décimale")
      },
      async (args) => {
        try {
          // Utiliser une bibliothèque d'évaluation mathématique sécurisée en production
          const result = eval(args.expression); // Exemple seulement !
          const formatted = Number(result).toFixed(args.precision);
          
          return {
            content: [{
              type: "text",
              text: `${args.expression} = ${formatted}`
            }]
          };
        } catch (error) {
          return {
            content: [{
              type: "text",
              text: `Erreur : Expression invalide - ${error.message}`
            }]
          };
        }
      }
    ),
    tool(
      "compound_interest",
      "Calculer les intérêts composés pour un investissement",
      {
        principal: z.number().positive().describe("Montant d'investissement initial"),
        rate: z.number().describe("Taux d'intérêt annuel (en décimal, ex : 0,05 pour 5%)"),
        time: z.number().positive().describe("Période d'investissement en années"),
        n: z.number().positive().default(12).describe("Fréquence de composition par an")
      },
      async (args) => {
        const amount = args.principal * Math.pow(1 + args.rate / args.n, args.n * args.time);
        const interest = amount - args.principal;
        
        return {
          content: [{
            type: "text",
            text: `Analyse d'Investissement :\n` +
                  `Principal : ${args.principal.toFixed(2)}$\n` +
                  `Taux : ${(args.rate * 100).toFixed(2)}%\n` +
                  `Durée : ${args.time} années\n` +
                  `Composition : ${args.n} fois par an\n\n` +
                  `Montant Final : ${amount.toFixed(2)}$\n` +
                  `Intérêts Gagnés : ${interest.toFixed(2)}$\n` +
                  `Rendement : ${((interest / args.principal) * 100).toFixed(2)}%`
          }]
        };
      }
    )
  ]
});

Documentation Connexe

Guides

Outils Personnalisés

Créez et intégrez des outils personnalisés pour étendre les fonctionnalités du Claude Agent SDK

Création d'Outils Personnalisés

Utilisez les fonctions d'aide createSdkMcpServer et tool pour définir des outils personnalisés type-safe :

TypeScript

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

// Créer un serveur MCP SDK avec des outils personnalisés
const customServer = createSdkMcpServer({
  name: "my-custom-tools",
  version: "1.0.0",
  tools: [
    tool(
      "get_weather",
      "Obtenir la température actuelle d'un lieu en utilisant les coordonnées",
      {
        latitude: z.number().describe("Coordonnée de latitude"),
        longitude: z.number().describe("Coordonnée de longitude")
      },
      async (args) => {
        const response = await fetch(`https://api.open-meteo.com/v1/forecast?latitude=${args.latitude}&longitude=${args.longitude}&current=temperature_2m&temperature_unit=fahrenheit`);
        const data = await response.json();

        return {
          content: [{
            type: "text",
            text: `Température : ${data.current.temperature_2m}°F`
          }]
        };
      }
    )
  ]
});

Python

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeSDKClient, ClaudeAgentOptions
from typing import Any
import aiohttp

# Définir un outil personnalisé en utilisant le décorateur @tool
@tool("get_weather", "Obtenir la température actuelle d'un lieu en utilisant les coordonnées", {"latitude": float, "longitude": float})
async def get_weather(args: dict[str, Any]) -> dict[str, Any]:
    # Appeler l'API météo
    async with aiohttp.ClientSession() as session:
        async with session.get(
            f"https://api.open-meteo.com/v1/forecast?latitude={args['latitude']}&longitude={args['longitude']}&current=temperature_2m&temperature_unit=fahrenheit"
        ) as response:
            data = await response.json()

    return {
        "content": [{
            "type": "text",
            "text": f"Température : {data['current']['temperature_2m']}°F"
        }]
    }

# Créer un serveur MCP SDK avec l'outil personnalisé
custom_server = create_sdk_mcp_server(
    name="my-custom-tools",
    version="1.0.0",
    tools=[get_weather]  # Passer la fonction décorée
)

Utilisation d'Outils Personnalisés

Passez le serveur personnalisé à la fonction query via l'option mcpServers comme un dictionnaire/objet.

Format des Noms d'Outils

Lorsque les outils MCP sont exposés à Claude, leurs noms suivent un format spécifique :

Modèle : mcp__{server_name}__{tool_name}
Exemple : Un outil nommé get_weather dans le serveur my-custom-tools devient mcp__my-custom-tools__get_weather

Configuration des Outils Autorisés

Vous pouvez contrôler quels outils Claude peut utiliser via l'option allowedTools :

import { query } from "@anthropic-ai/claude-agent-sdk";

// Utiliser les outils personnalisés dans votre requête avec entrée en streaming
async function* generateMessages() {
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Quel temps fait-il à San Francisco ?"
    }
  };
}

for await (const message of query({
  prompt: generateMessages(),  // Utiliser un générateur asynchrone pour l'entrée en streaming
  options: {
    mcpServers: {
      "my-custom-tools": customServer  // Passer comme objet/dictionnaire, pas comme tableau
    },
    // Spécifier optionnellement quels outils Claude peut utiliser
    allowedTools: [
      "mcp__my-custom-tools__get_weather",  // Autoriser l'outil météo
      // Ajouter d'autres outils selon les besoins
    ],
    maxTurns: 3
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Exemple avec Plusieurs Outils

Lorsque votre serveur MCP a plusieurs outils, vous pouvez les autoriser sélectivement :

const multiToolServer = createSdkMcpServer({
  name: "utilities",
  version: "1.0.0",
  tools: [
    tool("calculate", "Effectuer des calculs", { /* ... */ }, async (args) => { /* ... */ }),
    tool("translate", "Traduire du texte", { /* ... */ }, async (args) => { /* ... */ }),
    tool("search_web", "Rechercher sur le web", { /* ... */ }, async (args) => { /* ... */ })
  ]
});

// Autoriser seulement des outils spécifiques avec entrée en streaming
async function* generateMessages() {
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Calcule 5 + 3 et traduis 'bonjour' en espagnol"
    }
  };
}

for await (const message of query({
  prompt: generateMessages(),  // Utiliser un générateur asynchrone pour l'entrée en streaming
  options: {
    mcpServers: {
      utilities: multiToolServer
    },
    allowedTools: [
      "mcp__utilities__calculate",   // Autoriser la calculatrice
      "mcp__utilities__translate",   // Autoriser le traducteur
      // "mcp__utilities__search_web" n'est PAS autorisé
    ]
  }
})) {
  // Traiter les messages
}

Sécurité de Type avec Python

Le décorateur @tool prend en charge diverses approches de définition de schéma pour la sécurité de type :

import { z } from "zod";

tool(
  "process_data",
  "Traiter des données structurées avec sécurité de type",
  {
    // Le schéma Zod définit à la fois la validation d'exécution et les types TypeScript
    data: z.object({
      name: z.string(),
      age: z.number().min(0).max(150),
      email: z.string().email(),
      preferences: z.array(z.string()).optional()
    }),
    format: z.enum(["json", "csv", "xml"]).default("json")
  },
  async (args) => {
    // args est entièrement typé basé sur le schéma
    // TypeScript sait : args.data.name est string, args.data.age est number, etc.
    console.log(`Traitement des données de ${args.data.name} en tant que ${args.format}`);
    
    // Votre logique de traitement ici
    return {
      content: [{
        type: "text",
        text: `Données traitées pour ${args.data.name}`
      }]
    };
  }
)

Gestion des Erreurs

Gérez les erreurs avec élégance pour fournir un retour significatif :

tool(
  "fetch_data",
  "Récupérer des données depuis une API",
  {
    endpoint: z.string().url().describe("URL du point de terminaison API")
  },
  async (args) => {
    try {
      const response = await fetch(args.endpoint);
      
      if (!response.ok) {
        return {
          content: [{
            type: "text",
            text: `Erreur API : ${response.status} ${response.statusText}`
          }]
        };
      }
      
      const data = await response.json();
      return {
        content: [{
          type: "text",
          text: JSON.stringify(data, null, 2)
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Échec de récupération des données : ${error.message}`
        }]
      };
    }
  }
)

Exemples d'Outils

Outil de Requête de Base de Données

const databaseServer = createSdkMcpServer({
  name: "database-tools",
  version: "1.0.0",
  tools: [
    tool(
      "query_database",
      "Exécuter une requête de base de données",
      {
        query: z.string().describe("Requête SQL à exécuter"),
        params: z.array(z.any()).optional().describe("Paramètres de requête")
      },
      async (args) => {
        const results = await db.query(args.query, args.params || []);
        return {
          content: [{
            type: "text",
            text: `Trouvé ${results.length} lignes :\n${JSON.stringify(results, null, 2)}`
          }]
        };
      }
    )
  ]
});

Outil de Passerelle API

const apiGatewayServer = createSdkMcpServer({
  name: "api-gateway",
  version: "1.0.0",
  tools: [
    tool(
      "api_request",
      "Effectuer des requêtes API authentifiées vers des services externes",
      {
        service: z.enum(["stripe", "github", "openai", "slack"]).describe("Service à appeler"),
        endpoint: z.string().describe("Chemin du point de terminaison API"),
        method: z.enum(["GET", "POST", "PUT", "DELETE"]).describe("Méthode HTTP"),
        body: z.record(z.any()).optional().describe("Corps de la requête"),
        query: z.record(z.string()).optional().describe("Paramètres de requête")
      },
      async (args) => {
        const config = {
          stripe: { baseUrl: "https://api.stripe.com/v1", key: process.env.STRIPE_KEY },
          github: { baseUrl: "https://api.github.com", key: process.env.GITHUB_TOKEN },
          openai: { baseUrl: "https://api.openai.com/v1", key: process.env.OPENAI_KEY },
          slack: { baseUrl: "https://slack.com/api", key: process.env.SLACK_TOKEN }
        };
        
        const { baseUrl, key } = config[args.service];
        const url = new URL(`${baseUrl}${args.endpoint}`);
        
        if (args.query) {
          Object.entries(args.query).forEach(([k, v]) => url.searchParams.set(k, v));
        }
        
        const response = await fetch(url, {
          method: args.method,
          headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
          body: args.body ? JSON.stringify(args.body) : undefined
        });
        
        const data = await response.json();
        return {
          content: [{
            type: "text",
            text: JSON.stringify(data, null, 2)
          }]
        };
      }
    )
  ]
});

Outil Calculatrice

const calculatorServer = createSdkMcpServer({
  name: "calculator",
  version: "1.0.0",
  tools: [
    tool(
      "calculate",
      "Effectuer des calculs mathématiques",
      {
        expression: z.string().describe("Expression mathématique à évaluer"),
        precision: z.number().optional().default(2).describe("Précision décimale")
      },
      async (args) => {
        try {
          // Utiliser une bibliothèque d'évaluation mathématique sécurisée en production
          const result = eval(args.expression); // Exemple seulement !
          const formatted = Number(result).toFixed(args.precision);
          
          return {
            content: [{
              type: "text",
              text: `${args.expression} = ${formatted}`
            }]
          };
        } catch (error) {
          return {
            content: [{
              type: "text",
              text: `Erreur : Expression invalide - ${error.message}`
            }]
          };
        }
      }
    ),
    tool(
      "compound_interest",
      "Calculer les intérêts composés pour un investissement",
      {
        principal: z.number().positive().describe("Montant d'investissement initial"),
        rate: z.number().describe("Taux d'intérêt annuel (en décimal, ex : 0,05 pour 5%)"),
        time: z.number().positive().describe("Période d'investissement en années"),
        n: z.number().positive().default(12).describe("Fréquence de composition par an")
      },
      async (args) => {
        const amount = args.principal * Math.pow(1 + args.rate / args.n, args.n * args.time);
        const interest = amount - args.principal;
        
        return {
          content: [{
            type: "text",
            text: `Analyse d'Investissement :\n` +
                  `Principal : ${args.principal.toFixed(2)}$\n` +
                  `Taux : ${(args.rate * 100).toFixed(2)}%\n` +
                  `Durée : ${args.time} années\n` +
                  `Composition : ${args.n} fois par an\n\n` +
                  `Montant Final : ${amount.toFixed(2)}$\n` +
                  `Intérêts Gagnés : ${interest.toFixed(2)}$\n` +
                  `Rendement : ${((interest / args.principal) * 100).toFixed(2)}%`
          }]
        };
      }
    )
  ]
});