TypeScript

Prérequis

Node.js 18+

Installation

Installez @anthropic-ai/claude-code depuis NPM :

npm install -g @anthropic-ai/claude-code

Pour voir le code source du SDK TypeScript, visitez la page @anthropic-ai/claude-code sur NPM.

Utilisation de base

L’interface principale via le SDK TypeScript est la fonction query, qui retourne un itérateur asynchrone qui diffuse les messages au fur et à mesure qu’ils arrivent :

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

for await (const message of query({
  prompt: "Analyser les performances du système",
  abortController: new AbortController(),
  options: {
    maxTurns: 5,
    systemPrompt: "Vous êtes un ingénieur en performance",
    allowedTools: ["Bash", "Read", "WebSearch"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

Options de configuration

Argument	Type	Description	Défaut
`abortController`	`AbortController`	Contrôleur d’abandon pour annuler les opérations	`new AbortController()`
`additionalDirectories`	`string[]`	Répertoires supplémentaires à inclure dans la session	`undefined`
`allowedTools`	`string[]`	Liste des outils que Claude est autorisé à utiliser	Tous les outils activés par défaut
`appendSystemPrompt`	`string`	Texte à ajouter au prompt système par défaut	`undefined`
`canUseTool`	`CanUseTool`	Fonction de permission personnalisée pour l’utilisation d’outils	`undefined`
`continue`	`boolean`	Continuer la session la plus récente	`false`
`customSystemPrompt`	`string`	Remplacer entièrement le prompt système par défaut	`undefined`
`cwd`	`string`	Répertoire de travail actuel	`process.cwd()`
`disallowedTools`	`string[]`	Liste des outils que Claude n’est pas autorisé à utiliser	`undefined`
`env`	`Dict<string>`	Variables d’environnement à définir	`undefined`
`executable`	`'bun' \| 'deno' \| 'node'`	Quel runtime JavaScript utiliser	`node` lors de l’exécution avec Node.js, `bun` lors de l’exécution avec Bun
`executableArgs`	`string[]`	Arguments à passer à l’exécutable	`[]`
`fallbackModel`	`string`	Modèle à utiliser si le modèle principal échoue	`undefined`
`maxThinkingTokens`	`number`	Tokens maximum pour le processus de réflexion de Claude	`undefined`
`maxTurns`	`number`	Nombre maximum de tours de conversation	`undefined`
`mcpServers`	`Record<string, McpServerConfig>`	Configurations des serveurs MCP	`undefined`
`model`	`string`	Modèle Claude à utiliser	Utilise la valeur par défaut de la configuration CLI
`pathToClaudeCodeExecutable`	`string`	Chemin vers l’exécutable Claude Code	Exécutable livré avec `@anthropic-ai/claude-code`
`permissionMode`	`PermissionMode`	Mode de permission pour la session	`"default"` (options : `"default"`, `"acceptEdits"`, `"bypassPermissions"`, `"plan"`)
`permissionPromptToolName`	`string`	Nom de l’outil MCP pour les prompts de permission	`undefined`
`resume`	`string`	ID de session à reprendre	`undefined`
`stderr`	`(data: string) => void`	Callback pour la sortie stderr	`undefined`
`strictMcpConfig`	`boolean`	Appliquer une validation stricte de la configuration MCP	`undefined`

Conversations multi-tours

Pour les conversations multi-tours, vous avez deux options.

Vous pouvez générer des réponses et les reprendre, ou vous pouvez utiliser le mode d’entrée en streaming qui accepte un async/générateur pour un tableau de messages. Pour l’instant, le mode d’entrée en streaming est la seule façon d’attacher des images via des messages.

Reprendre avec la gestion de session

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

// Continuer la conversation la plus récente
for await (const message of query({
  prompt: "Maintenant refactorisez ceci pour de meilleures performances",
  options: { continue: true }
})) {
  if (message.type === "result") console.log(message.result);
}

// Reprendre une session spécifique
for await (const message of query({
  prompt: "Mettre à jour les tests",
  options: {
    resume: "550e8400-e29b-41d4-a716-446655440000",
    maxTurns: 3
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Mode d’entrée en streaming

Le mode d’entrée en streaming vous permet de fournir des messages comme un itérable asynchrone au lieu d’une seule chaîne. Cela permet les conversations multi-tours, les pièces jointes d’images et la génération dynamique de messages :

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

// Créer un générateur asynchrone pour les messages en streaming
async function* generateMessages() {
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Commencer à analyser cette base de code"
    }
  };
  
  // Attendre une condition ou une entrée utilisateur
  await new Promise(resolve => setTimeout(resolve, 1000));
  
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Maintenant se concentrer sur le module d'authentification"
    }
  };
}

// Utiliser l'entrée en streaming
for await (const message of query({
  prompt: generateMessages(),
  options: {
    maxTurns: 5,
    allowedTools: ["Read", "Grep", "Bash"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

Entrée en streaming avec images

Le mode d’entrée en streaming est la seule façon d’attacher des images via des messages :

import { query } from "@anthropic-ai/claude-code";
import { readFileSync } from "fs";

async function* messagesWithImage() {
  // Envoyer une image avec du texte
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: [
        {
          type: "text",
          text: "Analyser cette capture d'écran et suggérer des améliorations"
        },
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/png",
            data: readFileSync("screenshot.png", "base64")
          }
        }
      ]
    }
  };
}

for await (const message of query({
  prompt: messagesWithImage()
})) {
  if (message.type === "result") console.log(message.result);
}

Prompts système personnalisés

Les prompts système définissent le rôle, l’expertise et le comportement de votre agent :

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

// Agent de réponse aux incidents SRE
for await (const message of query({
  prompt: "L'API est en panne, enquêter",
  options: {
    systemPrompt: "Vous êtes un expert SRE. Diagnostiquez les problèmes de manière systématique et fournissez des solutions exploitables.",
    maxTurns: 3
  }
})) {
  if (message.type === "result") console.log(message.result);
}

// Ajouter au prompt système par défaut
for await (const message of query({
  prompt: "Refactoriser cette fonction",
  options: {
    appendSystemPrompt: "Incluez toujours une gestion d'erreur complète et des tests unitaires.",
    maxTurns: 2
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Outils personnalisés via MCP

Le Model Context Protocol (MCP) vous permet de donner à vos agents des outils et capacités personnalisés :

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

// Agent SRE avec outils de surveillance
for await (const message of query({
  prompt: "Enquêter sur la panne du service de paiement",
  options: {
    mcpConfig: "sre-tools.json",
    allowedTools: ["mcp__datadog", "mcp__pagerduty", "mcp__kubernetes"],
    systemPrompt: "Vous êtes un SRE. Utilisez les données de surveillance pour diagnostiquer les problèmes.",
    maxTurns: 4
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Outils personnalisés utilisant les MCP

Vous pouvez implémenter des outils personnalisés en utilisant les MCP, par exemple voici comment vous pouvez créer un outil de gestion de permissions personnalisé.

const server = new McpServer({
  name: "Test permission prompt MCP Server",
  version: "0.0.1",
});

server.tool(
  "approval_prompt",
  'Simuler une vérification de permission - approuver si l\'entrée contient "allow", sinon refuser',
  {
    tool_name: z.string().describe("Le nom de l'outil demandant la permission"),
    input: z.object({}).passthrough().describe("L'entrée pour l'outil"),
    tool_use_id: z.string().optional().describe("L'ID unique de la demande d'utilisation d'outil"),
  },
  async ({ tool_name, input }) => {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            JSON.stringify(input).includes("allow")
              ? {
                  behavior: "allow",
                  updatedInput: input,
                }
              : {
                  behavior: "deny",
                  message: "Permission refusée par l'outil test approval_prompt",
                }
          ),
        },
      ],
    };
  }
);

// Utiliser dans le SDK
import { query } from "@anthropic-ai/claude-code";

for await (const message of query({
  prompt: "Analyser la base de code",
  options: {
    permissionPromptTool: "mcp__test-server__approval_prompt",
    mcpConfig: "my-config.json",
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Formats de sortie

Sortie texte (par défaut)

// Sortie texte par défaut
for await (const message of query({
  prompt: "Expliquer le fichier src/components/Header.tsx"
})) {
  if (message.type === "result") {
    console.log(message.result);
    // Sortie : Ceci est un composant React montrant...
  }
}

Sortie JSON

// Collecter tous les messages pour un accès de type JSON
const messages = [];
for await (const message of query({
  prompt: "Comment fonctionne la couche de données ?"
})) {
  messages.push(message);
}

// Accéder au message de résultat avec les métadonnées
const result = messages.find(m => m.type === "result");
console.log({
  result: result.result,
  cost: result.total_cost_usd,
  duration: result.duration_ms
});

Formats d’entrée

// Prompt direct
for await (const message of query({
  prompt: "Expliquer ce code"
})) {
  if (message.type === "result") console.log(message.result);
}

// Depuis une variable
const userInput = "Expliquer ce code";
for await (const message of query({ prompt: userInput })) {
  if (message.type === "result") console.log(message.result);
}

Exemples d’intégration d’agents

Agent de réponse aux incidents SRE

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

// Agent de réponse aux incidents automatisé
async function investigateIncident(
  incidentDescription: string,
  severity = "medium"
) {
  const messages = [];

  for await (const message of query({
    prompt: `Incident : ${incidentDescription} (Gravité : ${severity})`,
    options: {
      systemPrompt: "Vous êtes un expert SRE. Diagnostiquez le problème, évaluez l'impact et fournissez des éléments d'action immédiats.",
      maxTurns: 6,
      allowedTools: ["Bash", "Read", "WebSearch", "mcp__datadog"],
      mcpConfig: "monitoring-tools.json"
    }
  })) {
    messages.push(message);
  }

  return messages.find(m => m.type === "result");
}

// Utilisation
const result = await investigateIncident("L'API de paiement retourne des erreurs 500", "high");
console.log(result.result);

Révision de sécurité automatisée

import { query } from "@anthropic-ai/claude-code";
import { execSync } from "child_process";

async function auditPR(prNumber: number) {
  // Obtenir le diff de la PR
  const prDiff = execSync(`gh pr diff ${prNumber}`, { encoding: 'utf8' });

  const messages = [];
  for await (const message of query({
    prompt: prDiff,
    options: {
      systemPrompt: "Vous êtes un ingénieur en sécurité. Examinez cette PR pour les vulnérabilités, les modèles non sécurisés et les problèmes de conformité.",
      maxTurns: 3,
      allowedTools: ["Read", "Grep", "WebSearch"]
    }
  })) {
    messages.push(message);
  }

  return messages.find(m => m.type === "result");
}

// Utilisation
const report = await auditPR(123);
console.log(JSON.stringify(report, null, 2));

Assistant juridique multi-tours

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

async function legalReview() {
  // Démarrer la session de révision juridique
  let sessionId: string;

  for await (const message of query({
    prompt: "Démarrer la session de révision juridique",
    options: { maxTurns: 1 }
  })) {
    if (message.type === "system" && message.subtype === "init") {
      sessionId = message.session_id;
    }
  }

  // Révision en plusieurs étapes utilisant la même session
  const steps = [
    "Examiner contract.pdf pour les clauses de responsabilité",
    "Vérifier la conformité aux exigences RGPD",
    "Générer un résumé exécutif des risques"
  ];

  for (const step of steps) {
    for await (const message of query({
      prompt: step,
      options: { resume: sessionId, maxTurns: 2 }
    })) {
      if (message.type === "result") {
        console.log(`Étape : ${step}`);
        console.log(message.result);
      }
    }
  }
}

Schéma de messages

Les messages retournés par l’API JSON sont strictement typés selon le schéma suivant :

type SDKMessage =
  // Un message d'assistant
  | {
      type: "assistant";
      uuid: string;
      session_id: string;
      message: Message; // du SDK Anthropic
      parent_tool_use_id: string | null;
    }

  // Un message utilisateur (entrée)
  | {
      type: "user";
      uuid?: string;
      session_id: string;
      message: MessageParam; // du SDK Anthropic
      parent_tool_use_id: string | null;
    }

  // Un message utilisateur (sortie/relecture avec UUID requis)
  | {
      type: "user";
      uuid: string;
      session_id: string;
      message: MessageParam; // du SDK Anthropic
      parent_tool_use_id: string | null;
    }

  // Émis comme dernier message en cas de succès
  | {
      type: "result";
      subtype: "success";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      result: string;
      total_cost_usd: number;
      usage: Usage;
      permission_denials: SDKPermissionDenial[];
    }

  // Émis comme dernier message en cas d'erreur ou de tours maximum
  | {
      type: "result";
      subtype: "error_max_turns" | "error_during_execution";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      total_cost_usd: number;
      usage: Usage;
      permission_denials: SDKPermissionDenial[];
    }

  // Émis comme premier message au début d'une conversation
  | {
      type: "system";
      subtype: "init";
      uuid: UUID;
      session_id: string;
      apiKeySource: "user" | "project" | "org" | "temporary";
      cwd: string;
      tools: string[];
      mcp_servers: {
        name: string;
        status: string;
      }[];
      model: string;
      permissionMode: "default" | "acceptEdits" | "bypassPermissions" | "plan";
      slash_commands: string[];
      output_style: string;
    };

  type SDKPermissionDenial = {
    tool_name: string;
    tool_use_id: string;
    tool_input: Record<string, unknown>;
  }

Types de support supplémentaires :

Les types Message, MessageParam et Usage sont disponibles dans le SDK TypeScript Anthropic.

Ressources connexes

Utilisation et contrôles CLI - Documentation CLI complète
Intégration GitHub Actions - Automatisez votre flux de travail GitHub avec Claude
Flux de travail courants - Guides étape par étape pour les cas d’usage courants

Commencer

Créer avec Claude Code

SDK de Code Claude

Déploiement

Administration

Configuration

Référence

Ressources

Prérequis

Installation

Utilisation de base

Options de configuration

Conversations multi-tours

Reprendre avec la gestion de session

Mode d’entrée en streaming

Entrée en streaming avec images

Prompts système personnalisés

Outils personnalisés via MCP

Outils personnalisés utilisant les MCP

Formats de sortie

Sortie texte (par défaut)

Sortie JSON

Formats d’entrée

Exemples d’intégration d’agents

Agent de réponse aux incidents SRE

Révision de sécurité automatisée

Assistant juridique multi-tours

Schéma de messages

Ressources connexes

Commencer

Créer avec Claude Code

SDK de Code Claude

Déploiement

Administration

Configuration

Référence

Ressources

​Prérequis

​Installation

​Utilisation de base

​Options de configuration

​Conversations multi-tours

​Reprendre avec la gestion de session

​Mode d’entrée en streaming

​Entrée en streaming avec images

​Prompts système personnalisés

​Outils personnalisés via MCP

​Outils personnalisés utilisant les MCP

​Formats de sortie

​Sortie texte (par défaut)

​Sortie JSON

​Formats d’entrée

​Exemples d’intégration d’agents

​Agent de réponse aux incidents SRE

​Révision de sécurité automatisée

​Assistant juridique multi-tours

​Schéma de messages

​Ressources connexes

Prérequis

Installation

Utilisation de base

Options de configuration

Conversations multi-tours

Reprendre avec la gestion de session

Mode d’entrée en streaming

Entrée en streaming avec images

Prompts système personnalisés

Outils personnalisés via MCP

Outils personnalisés utilisant les MCP

Formats de sortie

Sortie texte (par défaut)

Sortie JSON

Formats d’entrée

Exemples d’intégration d’agents

Agent de réponse aux incidents SRE

Révision de sécurité automatisée

Assistant juridique multi-tours

Schéma de messages

Ressources connexes