Référence du SDK Agent - TypeScript

​

Installation

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

​

Compiler en un seul exécutable

import binPath from "@anthropic-ai/claude-agent-sdk-darwin-arm64/claude" with { type: "file" };
import { extractFromBunfs } from "@anthropic-ai/claude-agent-sdk/extract";
import { query } from "@anthropic-ai/claude-agent-sdk";

const cliPath = extractFromBunfs(binPath);

for await (const message of query({
  prompt: "Hello",
  options: { pathToClaudeCodeExecutable: cliPath },
})) {
  console.log(message);
}

• Pour la compilation croisée, installez le package de plateforme non correspondant, par exemple npm install @anthropic-ai/claude-agent-sdk-linux-x64 --force.
• Sur Windows, le sous-chemin binaire est claude.exe, par exemple @anthropic-ai/claude-agent-sdk-win32-x64/claude.exe.

​

Importer l’entrée /core lors du regroupement du SDK Agent

​

Fonctions

​

query()

function query({
  prompt,
  options
}: {
  prompt: string | AsyncIterable<SDKUserMessage>;
  options?: Options;
}): Query;

​

Paramètres

​

Retours

​

startup()

function startup(params?: {
  options?: Options;
  initializeTimeoutMs?: number;
}): Promise<WarmQuery>;

​

Paramètres

​

Retours

​

Exemple

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

// Payez le coût de démarrage à l'avance
const warm = await startup({ options: { maxTurns: 3 } });

// Plus tard, quand un prompt est prêt, c'est immédiat
for await (const message of warm.query("What files are here?")) {
  console.log(message);
}

​

prewarm()

function prewarm(params?: {
  options?: Options;
  initializeTimeoutMs?: number;
}): Promise<SpareProcess>;

​

Exemple

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

// Au démarrage de l'application, avant que le dossier de la session soit connu
const spare = await prewarm({ options: { maxTurns: 3 } });

// Plus tard, quand l'utilisateur démarre une session dans un dossier
const claimedQuery = spare.claim({
  prompt: "What files are here?",
  options: { cwd: "/path/to/project" },
});

spare.claimed.catch((error: Error) => {
  // À moins que le message commence par « option_not_applied », le prompt n'a pas été exécuté :
  // démarrez cette session avec query() à la place
  console.error("Claim failed:", error.message);
});

try {
  for await (const message of claimedQuery) {
    console.log(message);
  }
} catch (error) {
  // Après une réclamation refusée, la requête réclamée lève une exception une fois qu'elle a produit le résultat d'erreur
  console.error(`Session ended with an error: ${error}`);
}

​

tool()

function tool<Schema extends AnyZodRawShape>(
  name: string,
  description: string,
  inputSchema: Schema,
  handler: (args: InferShape<Schema>, extra: unknown) => Promise<CallToolResult>,
  extras?: { annotations?: ToolAnnotations; searchHint?: string; alwaysLoad?: boolean }
): SdkMcpToolDefinition<Schema>;

​

Paramètres

​

ToolAnnotations

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

const searchTool = tool(
  "search",
  "Search the web",
  { query: z.string() },
  async ({ query }) => {
    return { content: [{ type: "text", text: `Results for: ${query}` }] };
  },
  { annotations: { readOnlyHint: true, openWorldHint: true } }
);

​

createSdkMcpServer()

function createSdkMcpServer(options: {
  name: string;
  version?: string;
  instructions?: string;
  tools?: Array<SdkMcpToolDefinition<any>>;
  alwaysLoad?: boolean;
  timeout?: number;
}): McpSdkServerConfigWithInstance;

​

Paramètres

​

listSessions()

function listSessions(options?: ListSessionsOptions): Promise<SDKSessionInfo[]>;

​

Paramètres

​

Type de retour : SDKSessionInfo

​

Exemple

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

const sessions = await listSessions({ dir: "/path/to/project", limit: 10 });

for (const session of sessions) {
  console.log(`${session.summary} (${session.sessionId})`);
}

​

getSessionMessages()

function getSessionMessages(
  sessionId: string,
  options?: GetSessionMessagesOptions
): Promise<SessionMessage[]>;

​

Paramètres

​

Type de retour : SessionMessage

​

Exemple

import { listSessions, getSessionMessages } from "@anthropic-ai/claude-agent-sdk";

const [latest] = await listSessions({ dir: "/path/to/project", limit: 1 });

if (latest) {
  const messages = await getSessionMessages(latest.sessionId, {
    dir: "/path/to/project",
    limit: 20
  });

  for (const msg of messages) {
    console.log(`[${msg.type}] ${msg.uuid}`);
  }
}

​

getSessionInfo()

function getSessionInfo(
  sessionId: string,
  options?: GetSessionInfoOptions
): Promise<SDKSessionInfo | undefined>;

​

Paramètres

​

renameSession()

function renameSession(
  sessionId: string,
  title: string,
  options?: SessionMutationOptions
): Promise<void>;

​

Paramètres

​

tagSession()

function tagSession(
  sessionId: string,
  tag: string | null,
  options?: SessionMutationOptions
): Promise<void>;

​

Paramètres

​

forkSession()

function forkSession(
  sessionId: string,
  options?: ForkSessionOptions
): Promise<ForkSessionResult>;

​

Paramètres

• sessionId n’est pas un UUID
• la session est introuvable ou ne contient aucun message
• upToMessageId ne correspond à aucun message de la transcription

​

resolveSettings()

• policyHelper : resolveSettings() lit les sources MDM, y compris la liste de propriétés macOS et Windows HKLM/HKCU, mais n’exécute pas le sous-processus policyHelper configuré par l’administrateur.
• Paramètres gérés par le serveur : resolveSettings() ne récupère pas les paramètres gérés par le serveur. Passez-les comme options.serverManagedSettings pour les inclure.
• defaultMode : l’instantané retourne permissions.defaultMode tel quel de chaque niveau, de sorte qu’il peut inclure les valeurs 'auto' et 'bypassPermissions' des paramètres de projet et locaux, que une session en direct ignore.

function resolveSettings(
  options?: ResolveSettingsOptions
): Promise<ResolvedSettings>;

​

Paramètres

​

Type de retour : ResolvedSettings

​

Exemple

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

const { effective, provenance } = await resolveSettings({
  cwd: "/path/to/project",
  settingSources: ["user", "project", "local"],
});

console.log(`Cleanup period: ${effective.cleanupPeriodDays} days`);
console.log(`Set by: ${provenance.cleanupPeriodDays?.source}`);

​

Types

​

Options

​

Gérer les réponses d’API lentes ou bloquées

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

const result = query({
  prompt: "Analyze this code",
  options: {
    env: {
      ...process.env,
      API_TIMEOUT_MS: "120000",
      CLAUDE_CODE_MAX_RETRIES: "2",
      CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: "120000",
    },
  },
});

• API_TIMEOUT_MS : délai d’expiration par requête sur le client Anthropic, en millisecondes. Par défaut 600000. S’applique à la boucle principale et à tous les sous-agents.
• CLAUDE_CODE_MAX_RETRIES : nombre maximal de nouvelles tentatives d’API. Valeur par défaut 10, plafonnée à 15. Chaque nouvelle tentative dispose de sa propre fenêtre API_TIMEOUT_MS. Pour les exécutions sans surveillance qui doivent attendre la fin de pannes plus longues, définissez CLAUDE_CODE_RETRY_WATCHDOG=1 : cette variable réessaie indéfiniment en cas d’erreurs de capacité transitoires et, sur Claude Code v2.1.199 ou ultérieur, porte la valeur par défaut à 300 pour les autres erreurs transitoires et supprime le plafond de cette variable.
• CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS : watchdog de blocage pour les sous-agents. Tant que le watchdog de flux est actif, la valeur par défaut est CLAUDE_STREAM_IDLE_TIMEOUT_MS plus 5 minutes, soit 600000 sauf si vous augmentez cette variable. Lorsque le watchdog de flux est désactivé, la valeur par défaut est 600000. Avant v2.1.257, la valeur par défaut était toujours 600000. Le minuteur est réinitialisé à chaque événement de flux. En cas de blocage, Claude Code interrompt le sous-agent et signale le blocage au parent. Pour un sous-agent en arrière-plan, il marque également la tâche comme échouée et joint tout résultat partiel.
• CLAUDE_ENABLE_STREAM_WATCHDOG avec CLAUDE_STREAM_IDLE_TIMEOUT_MS : watchdog de flux qui interrompt la requête lorsque les en-têtes sont arrivés mais que le corps de la réponse cesse d’être transmis. Le watchdog est activé par défaut pour tous les fournisseurs ; définissez CLAUDE_ENABLE_STREAM_WATCHDOG=0 pour le désactiver. CLAUDE_STREAM_IDLE_TIMEOUT_MS vaut 300000 par défaut et ne peut pas descendre en dessous de ce minimum. Après l’interruption, Nouvelles tentatives automatiques décrit ce que fait Claude Code, selon l’avancement de la réponse. Pendant que le watchdog attend une réponse qu’une passerelle derrière ANTHROPIC_BASE_URL maintient ouverte avec des pings keep-alive, un hôte qui définit includePartialMessages continue de recevoir des événements de flux ping ; interprétez donc ces trames comme des signes d’activité plutôt que de faire expirer la session en cas de silence. Avant v2.1.257, les trames s’arrêtaient 5 minutes après le dernier véritable événement de flux.

​

Objet Query

interface Query extends AsyncGenerator<SDKMessage, void> {
  interrupt(): Promise<SDKControlInterruptResponse | undefined>;
  rewindFiles(
    userMessageId: string,
    options?: { dryRun?: boolean }
  ): Promise<RewindFilesResult>;
  setPermissionMode(mode: PermissionMode): Promise<void>;
  setModel(model?: string): Promise<void>;
  setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;
  applyFlagSettings(settings: {
    [K in keyof Settings]?: K extends 'effortLevel'
      ? 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null
      : Settings[K] | null;
  }): Promise<void>;
  updateSettings(
    source: 'localSettings' | 'userSettings',
    settings: Record<string, unknown>,
  ): Promise<void>;
  initializationResult(): Promise<SDKControlInitializeResponse>;
  reinitialize(): Promise<SDKControlInitializeResponse>;
  supportedCommands(): Promise<SlashCommand[]>;
  supportedModels(): Promise<ModelInfo[]>;
  supportedAgents(): Promise<AgentInfo[]>;
  mcpServerStatus(): Promise<McpServerStatus[]>;
  getContextUsage(opts?: {
    detail?: 'summary' | 'full';
  }): Promise<SDKControlGetContextUsageResponse>;
  readFile(
    path: string,
    options?: { maxBytes?: number; encoding?: 'utf-8' | 'base64' }
  ): Promise<SDKControlReadFileResponse | null>;
  reloadPlugins(options?: {
    holdOnCacheImpact?: boolean;
  }): Promise<SDKControlReloadPluginsResponse>;
  reloadSkills(): Promise<SDKControlReloadSkillsResponse>;
  reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;
  accountInfo(): Promise<AccountInfo>;
  reconnectMcpServer(serverName: string): Promise<void>;
  toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;
  setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;
  readMcpResource(serverName: string, uri: string): Promise<SDKControlMcpReadResourceResponse>;
  streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;
  stopTask(taskId: string): Promise<void>;
  close(): void;
}

​

Méthodes

​

applyFlagSettings()

• Appliquées au tour suivant : effortLevel, ultracode, permissions, hooks, skillOverrides, fastMode, agent. Changer d’agent applique également le remplacement de modèle et les hooks de cet agent au tour suivant. Son prompt système s’applique au tour suivant ou, dans une session qui réutilise un prompt système enregistré, une fois la session compactée.
• Appliquée pendant le tour en cours : model. Si vous changez de model pendant que Claude travaille sur un tour, la réponse que Claude est déjà en train de générer se termine avec l’ancien modèle, et le reste du tour, à partir du prochain appel que Claude Code adresse au modèle, utilise le nouveau. Les sous-agents conservent leur propre modèle. Avant v2.1.212, un changement en cours de tour attendait le tour suivant.
• Sans effet en cours de session : les options du prompt système. Elles sont résolues une seule fois au démarrage, de sorte que la session en cours conserve la valeur d’origine même si l’appel réussit. Pour les modifier, démarrez une nouvelle session.

• effortLevel: null ramène la session au niveau d’effort par défaut du modèle, et non à l’option effort de query() ni à un effortLevel provenant d’un fichier de paramètres.
• agent: null exécute le thread principal sans agent à partir du tour suivant, au lieu de restaurer l’option agent de query() ou un agent provenant d’un fichier de paramètres. Si l’agent effacé avait appliqué son propre modèle, la session revient au modèle résolu au démarrage.
• ultracode: null désactive ultracode, comme false, au lieu de restaurer une valeur ultracode provenant d’un fichier de paramètres. La session conserve son niveau d’effort actuel ; passez donc effortLevel dans le même appel pour le modifier.

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

const q = query({ prompt: messageStream });

// Override the model for the rest of the session
await q.applyFlagSettings({ model: "claude-opus-4-6" });

// Later: clear the override; the model resets to Claude Code's default
await q.applyFlagSettings({ model: null });

​

updateSettings()

• "localSettings" : accepte outputStyle et le fusionne dans le fichier de paramètres locaux du projet, .claude/settings.local.json. Le nouveau style prend effet à la prochaine requête de la session.
• "userSettings" : accepte effortLevel et l’enregistre comme niveau d’effort par défaut pour le modèle actuel de la session, sous modelSettings dans votre fichier de paramètres utilisateur. Passer max n’écrit rien, car max est limité à la session. La session en cours conserve son niveau d’effort actuel dans tous les cas ; appelez donc applyFlagSettings() si vous souhaitez également le modifier. Cette source nécessite TypeScript SDK v0.3.277 ou ultérieure, qui inclut Claude Code v2.1.277.

​

toggleMcpServer()

• Un serveur stdio, SSE ou HTTP que vous avez ajouté en cours de session avec setMcpServers() : le retrait de ses outils nécessite Claude Code v2.1.285 ou ultérieure.
• Un serveur in-process que vous avez créé avec createSdkMcpServer(), que vous l’ayez passé dans mcpServers ou avec setMcpServers() : sa déconnexion et le retrait de ses outils nécessitent Claude Code v2.1.286 ou ultérieure. La désactivation d’un tel serveur fait également échouer ses appels d’outils encore en cours, de sorte que Claude reçoit immédiatement un résultat d’erreur pour chacun d’eux, sans attendre le retour de votre handler.

​

WarmQuery

interface WarmQuery extends AsyncDisposable {
  query(prompt: string | AsyncIterable<SDKUserMessage>): Query;
  close(): void;
}

​

Méthodes

​

SpareProcess

interface SpareProcess extends AsyncDisposable {
  claim(params: {
    prompt: string | AsyncIterable<SDKUserMessage>;
    options: ClaimOptions;
  }): Query;
  readonly claimed: Promise<{ cwd: string; sessionId: string; parkedMs?: number; sdkMcpSettled: boolean }>;
  readonly exited: Promise<void>;
  close(): void;
}

​

Membres

​

SDKControlInitializeResponse

type SDKControlInitializeResponse = {
  commands: SlashCommand[];
  agents: AgentInfo[];
  output_style: string;
  available_output_styles: string[];
  models: ModelInfo[];
  account: AccountInfo;
  fast_mode_state?: "off" | "cooldown" | "on";
  fast_mode_disabled_reason?: FastModeDisabledReason;
  hooks_applied?: boolean;
  sdk_mcp_manifests_parked?: Record<
    string,
    | "parked"
    | "already_connected"
    | "protocol_version_mismatch"
    | "malformed"
    | "not_honoured"
  >;
  claude_code_version?: string;
};

• true : Claude Code a enregistré les hooks. Le premier initialize d’une session renvoie cette valeur. Un initialize répété envoyé via le stdin de la CLI renvoie également true. Dans ce cas, les hooks de la nouvelle requête remplacent ceux enregistrés précédemment.
• false : Claude Code a ignoré les hooks. Un initialize répété envoyé à une session distante renvoie cette valeur, de sorte qu’un second client qui rejoint une session ne peut pas remplacer les hooks enregistrés par le premier client.

• Ce champ nécessite Agent SDK v0.3.296 ou ultérieur, qui inclut Claude Code v2.1.296.
• Si le champ vaut undefined et que vous définissez pathToClaudeCodeExecutable, faites-le pointer vers Claude Code v2.1.296 ou ultérieur.

​

SDKControlInterruptResponse

type SDKControlInterruptResponse = {
  still_queued: string[];
  cancelled?: string[];
};

• Seuls les messages mis en file d’attente avec un UUID apparaissent. Un tableau vide ne signifie pas que rien d’autre ne s’exécutera.
• Seuls les messages du thread principal sont listés. Les messages adressés à un sous-agent sont hors du périmètre.
• La liste peut inclure des UUID que votre client n’a jamais envoyés, comme les déclencheurs de tâches planifiées. Ignorez les UUID que vous ne reconnaissez pas au lieu de les traiter comme une erreur.

​

SDKControlGetContextUsageResponse

• 'full' : la valeur par défaut. Claude Code compte chaque catégorie avec des requêtes API de comptage de tokens. Ces requêtes n’apparaissent pas dans le flux de messages, de sorte que le suivi des coûts qui lit le flux ne les verra pas. Sur l’API Anthropic, le comptage de tokens n’est pas facturé.
• 'summary' : passez { detail: 'summary' } pour obtenir plutôt une réponse basée sur l’utilisation de la dernière réponse et sur des estimations locales. Aucune requête de comptage de tokens n’est envoyée, et les nombres par catégorie sont approximatifs.

type SDKControlGetContextUsageResponse = {
  categories: {
    name: string;
    tokens: number;
    color: string;
    isDeferred?: boolean;
    kind: "used" | "free" | "buffer" | "deferred";
  }[];
  totalTokens: number;
  maxTokens: number;
  rawMaxTokens: number;
  percentage: number;
  gridRows: {
    color: string;
    isFilled: boolean;
    categoryName: string;
    tokens: number;
    percentage: number;
    squareFullness: number;
  }[][];
  model: string;
  memoryFiles: {
    path: string;
    type: string;
    tokens: number;
  }[];
  mcpTools: {
    name: string;
    serverName: string;
    tokens: number;
    isLoaded?: boolean;
  }[];
  deferredBuiltinTools?: {
    name: string;
    tokens: number;
    isLoaded: boolean;
  }[];
  systemTools?: {
    name: string;
    tokens: number;
  }[];
  systemPromptSections?: {
    name: string;
    tokens: number;
  }[];
  agents: {
    agentType: string;
    source: string;
    tokens: number;
  }[];
  slashCommands?: {
    totalCommands: number;
    includedCommands: number;
    tokens: number;
  };
  skills?: {
    totalSkills: number;
    includedSkills: number;
    tokens: number;
    skillFrontmatter: {
      name: string;
      source: string;
      tokens: number;
    }[];
  };
  autoCompactThreshold?: number;
  isAutoCompactEnabled: boolean;
  messageBreakdown?: {
    toolCallTokens: number;
    toolResultTokens: number;
    attachmentTokens: number;
    assistantMessageTokens: number;
    userMessageTokens: number;
    redirectedContextTokens: number;
    unattributedTokens: number;
    toolCallsByType: {
      name: string;
      callTokens: number;
      resultTokens: number;
    }[];
    attachmentsByType: {
      name: string;
      tokens: number;
    }[];
  };
  apiUsage: {
    input_tokens: number;
    output_tokens: number;
    cache_creation_input_tokens: number;
    cache_read_input_tokens: number;
  } | null;
};

• categories contient les totaux par catégorie. Le kind de chaque entrée classe la ligne avec les mêmes valeurs que SDKContextUsageCategory. Classez les lignes selon ce champ plutôt que selon le name d’affichage. Le champ nécessite Agent SDK v0.3.268 ou ultérieure.
• mcpTools et agents attribuent les tokens à des outils MCP et à des sous-agents individuels.
• memoryFiles liste chaque fichier de mémoire chargé avec son coût.
• skills.skillFrontmatter attribue les tokens de la liste des skills à chaque skill inclus. Les nombres par skill mesurent l’entrée de chaque skill dans la liste telle que Claude Code l’envoie réellement, qui peut être plus courte que le frontmatter complet du skill. Comparez skills.totalSkills à skills.includedSkills pour vérifier si chaque skill découvert figure dans la liste.

​

SDKControlReadFileResponse

type SDKControlReadFileResponse = {
  contents: string;
  absPath: string;
  truncated?: boolean;
  encoding?: 'base64';
};

​

Ce que readFile() peut lire

• Un fichier ordinaire situé dans l’un des répertoires de travail de la session, tels que cwd et additionalDirectories
• Quelques fichiers propres à Claude Code pour la session, tels que les résultats d’outils

​

SDKControlReloadPluginsResponse

type SDKControlReloadPluginsResponse = {
  commands: SlashCommand[];
  agents: AgentInfo[];
  plugins: {
    name: string;
    path: string;
    source?: string;
    version?: string;
  }[];
  mcpServers: McpServerStatus[];
  error_count: number;
  held?: boolean;
  cache_impact?: {
    mcp_servers_added: string[];
    mcp_servers_removed: string[];
    lsp_tool_change: ("adds" | "may-add" | "removes" | "may-remove") | null;
  };
};

• commands, agents et mcpServers : les commandes, les sous-agents et l’état des serveurs MCP de la session, sous les mêmes formes que celles renvoyées par supportedCommands(), supportedAgents() et mcpServerStatus(). supportedAgents() continue de renvoyer la liste capturée lors de l’initialisation ; lisez donc agents ici pour obtenir l’ensemble après un rechargement
• plugins : chaque plugin chargé avec son name et son path d’installation. version reprend ce que déclare le manifeste du plugin et est contrôlé par l’auteur du plugin ; validez-le donc avant de vous y fier. Il est omis lorsque le manifeste n’en déclare aucune
• error_count : le nombre d’erreurs survenues lors du chargement des plugins

• true : le rechargement n’a pas été appliqué, et les champs de collection décrivent la session telle qu’elle est toujours. cache_impact indique ce que l’application changerait. Pour appliquer malgré tout, appelez de nouveau reloadPlugins() sans l’option.
• false : la vérification n’a trouvé aucun impact sur le cache, et le rechargement a été appliqué.
• Absent : vous n’avez pas passé l’option, ou l’exécutable Claude Code est antérieur à v2.1.268 et a appliqué le rechargement.

​

SDKControlReloadSkillsResponse

type SDKControlReloadSkillsResponse = {
  skills: SlashCommand[];
};

​

SDKControlReloadOutputStylesResponse

type SDKControlReloadOutputStylesResponse = {
  available_output_styles: string[];
};

​

SDKControlMcpReadResourceResponse

type SDKControlMcpReadResourceResponse = {
  contents: {
    uri: string;
    mimeType?: string;
    text?: string;
    blob?: string;
    _meta?: Record<string, unknown>;
  }[];
};

​

AgentDefinition

type AgentDefinition = {
  description: string;
  tools?: string[];
  disallowedTools?: string[];
  prompt: string;
  model?: string;
  mcpServers?: AgentMcpServerSpec[];
  skills?: string[];
  initialPrompt?: string;
  maxTurns?: number;
  autoCompactWindow?: number;
  background?: boolean;
  omitClaudeMd?: boolean;
  memory?: "user" | "project" | "local";
  effort?: "low" | "medium" | "high" | "xhigh" | "max" | number;
  permissionMode?: PermissionMode;
  criticalSystemReminder_EXPERIMENTAL?: string;
};

​

AgentMcpServerSpec

type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;

​

SettingSource

type SettingSource = "user" | "project" | "local";

​

Comportement par défaut

​

Pourquoi utiliser settingSources

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

// Do not load user, project, or local settings from disk
const result = query({
  prompt: "Analyze this code",
  options: { settingSources: [] }
});

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

// Load only project settings, ignore user and local
const result = query({
  prompt: "Run CI checks",
  options: {
    settingSources: ["project"] // Only .claude/settings.json
  }
});

​

Priorité des paramètres

1. Paramètres locaux (.claude/settings.local.json)
2. Paramètres de projet (.claude/settings.json)
3. Paramètres utilisateur (~/.claude/settings.json)

​

PermissionMode

type PermissionMode =
  | "default" // Standard permission behavior
  | "acceptEdits" // Auto-accept file edits
  | "bypassPermissions" // Bypass permission checks; explicit ask rules still prompt
  | "plan" // Planning mode - explore without editing
  | "dontAsk" // Don't prompt for permissions, deny if not pre-approved
  | "auto"; // A model classifier reviews actions such as shell commands and network requests

​

CanUseTool

type CanUseTool = (
  toolName: string,
  input: Record<string, unknown>,
  options: {
    signal: AbortSignal;
    suggestions?: PermissionUpdate[];
    blockedPath?: string;
    mcpServer?: { name: string; source: string };
    decisionReason?: string;
    defaultToNo?: boolean;
    suppressAlwaysAllowRule?: boolean;
    toolUseID: string;
    agentID?: string;
    requestId: string;
  }
) => Promise<PermissionResult | null>;

​

PermissionResult

type PermissionResult =
  | {
      behavior: "allow";
      updatedInput?: Record<string, unknown>;
      updatedPermissions?: PermissionUpdate[];
      toolUseID?: string;
    }
  | {
      behavior: "deny";
      message: string;
      interrupt?: boolean;
      toolUseID?: string;
    };

​

ToolConfig

type ToolConfig = {
  askUserQuestion?: {
    previewFormat?: "markdown" | "html";
  };
};

​

McpServerConfig

type McpServerConfig =
  | McpStdioServerConfig
  | McpSSEServerConfig
  | McpHttpServerConfig
  | McpSdkServerConfigWithInstance;

​

McpStdioServerConfig

type McpStdioServerConfig = {
  type?: "stdio";
  command: string;
  args?: string[];
  env?: Record<string, string>;
};

​

McpSSEServerConfig

type McpSSEServerConfig = {
  type: "sse";
  url: string;
  headers?: Record<string, string>;
};

​

McpHttpServerConfig

type McpHttpServerConfig = {
  type: "http";
  url: string;
  headers?: Record<string, string>;
};

​

McpSdkServerConfigWithInstance

type McpSdkServerConfigWithInstance = {
  type: "sdk";
  name: string;
  timeout?: number;
  instance: McpServer;
};

​

McpClaudeAIProxyServerConfig

type McpClaudeAIProxyServerConfig = {
  type: "claudeai-proxy";
  url: string;
  id: string;
};

​

SdkPluginConfig

type SdkPluginConfig = {
  type: "local";
  path: string;
  skipMcpDiscovery?: boolean;
};

plugins: [
  { type: "local", path: "./my-plugin" },
  { type: "local", path: "/absolute/path/to/plugin" }
];

​

Types de messages

​

SDKMessage

type SDKMessage =
  | SDKAssistantMessage
  | SDKUserMessage
  | SDKUserMessageReplay
  | SDKResultMessage
  | SDKSystemMessage
  | SDKPartialAssistantMessage
  | SDKCompactBoundaryMessage
  | SDKStatusMessage
  | SDKLocalCommandOutputMessage
  | SDKHookStartedMessage
  | SDKHookProgressMessage
  | SDKHookResponseMessage
  | SDKPluginInstallMessage
  | SDKToolProgressMessage
  | SDKAuthStatusMessage
  | SDKTaskNotificationMessage
  | SDKTaskStartedMessage
  | SDKTaskProgressMessage
  | SDKTaskUpdatedMessage
  | SDKBackgroundTasksChangedMessage
  | SDKThinkingTokensMessage
  | SDKSessionStateChangedMessage
  | SDKWorkerShuttingDownMessage
  | SDKCommandsChangedMessage
  | SDKNotificationMessage
  | SDKFilesPersistedEvent
  | SDKToolUseSummaryMessage
  | SDKMemoryRecallMessage
  | SDKRateLimitEvent
  | SDKElicitationCompleteMessage
  | SDKPermissionDeniedMessage
  | SDKPromptSuggestionMessage
  | SDKAPIRetryMessage
  | SDKMirrorErrorMessage
  | SDKInformationalMessage
  | SDKConversationResetMessage;

​

SDKAssistantMessage

type SDKAssistantMessage = {
  type: "assistant";
  uuid: UUID;
  session_id: string;
  message: BetaMessage; // From Anthropic SDK
  parent_tool_use_id: string | null;
  error?: SDKAssistantMessageError;
  aborted?: true;
  agent_id?: string;
  timestamp?: string;
  context_usage?: SDKContextUsage;
  usage_report?: SDKUsageReport;
  user_message_uuid?: string;
  user_message_uuids?: string[];
  resume_reason?: string;
};

• 'model_not_found' : le modèle sélectionné n’existe pas ou n’est pas disponible pour votre compte ou déploiement
• 'overloaded' : l’API a retourné un 529 parce que le serveur est à capacité, contrairement à 'rate_limit', qui est un 429 contre votre quota
• 'account_on_hold' : votre compte est suspendu
• 'cloud_credential_error' : Claude Code n’a pas pu obtenir des identifiants AWS ou Google Cloud utilisables sur la machine sur laquelle il s’exécute, donc aucune requête n’a atteint le fournisseur cloud. La cause habituelle est une connexion cloud qui a expiré ou n’a jamais été complétée sur cette machine, bien qu’un service d’identifiants brièvement inaccessible rapporte la même valeur. Voir Impossible de charger les identifiants AWS ou Google Cloud. Nécessite TypeScript Agent SDK v0.3.267 ou ultérieur, qui regroupe Claude Code v2.1.267

• La session s’authentifie avec des identifiants claude.ai
• Les identifiants indiquent un type de forfait connu ou portent le scope user:profile
• Le compte n’est pas en facturation à l’usage

​

SDKUserMessage

type SDKUserMessage = {
  type: "user";
  uuid?: UUID;
  session_id?: string;
  agent_id?: string;
  message: MessageParam; // From Anthropic SDK
  pasted_content?: MessageParam["content"][];
  parent_tool_use_id: string | null;
  isSynthetic?: boolean;
  shouldQuery?: boolean;
  client_composed?: true;
  tool_use_result?: unknown;
  priority?: "now" | "next" | "later";
  origin?: SDKMessageOrigin;
  inline_pastes?: string[];
};

• pasted_content : si les entrées et les blocs de contenu qu’elles contiennent dépassent 1 000 au total, Claude Code ignore l’ensemble du champ.
• inline_pastes : Claude Code utilise les 100 premières entrées non vides et ignore le reste.

• shouldQuery : définissez-le à false pour ajouter le message à la transcription sans déclencher un tour d’assistant. Le message est conservé et fusionné dans le prochain message utilisateur qui déclenche un tour. Utilisez ceci pour injecter du contexte, comme la sortie d’une commande que vous avez exécutée hors bande, sans dépenser un appel de modèle pour cela.
• client_composed : définissez-le à true pour que Claude Code livre le texte du message tel qu’écrit. Claude Code n’étend alors pas les mentions @path ou @server:resource, et n’exécute pas le texte qui commence par / comme une commande. Tandis que l’option verbatimPrompts est activée, le SDK définit le champ sur chaque message. Nécessite TypeScript Agent SDK v0.3.280 ou ultérieur et Claude Code v2.1.248 ou ultérieur.
• priority : contrôle le moment où un message que vous envoyez pendant un tour en cours parvient à Claude :
  • 'next', ou aucun champ priority : Claude lit le message dans le même tour, dès que les appels d’outils en cours se terminent. Si le tour se termine avant, le message démarre le tour suivant.
  • 'later' : Claude Code conserve le message jusqu’à la fin du tour et l’envoie comme un nouveau tour.
  • 'now' avec origin: { kind: "human" } : sur Claude Code v2.1.286 ou version ultérieure, le travail qui peut se poursuivre en arrière-plan y est déplacé, et Claude lit le message dans le même tour. Le travail déplaçable comprend les commandes shell, les sous-agents et les appels d’outils MCP. Sur v2.1.287 ou version ultérieure, il comprend également les appels WebFetch et WebSearch. Lorsque Claude est seulement en train de rédiger une réponse, ou que le travail en cours ne peut pas être déplacé, Claude Code interrompt plutôt le tour et Claude lit le message ensuite.
  • 'now' sans cette origine : Claude Code interrompt le tour et Claude lit le message ensuite.

const message: SDKUserMessage = {
  type: "user",
  message: { role: "user", content: "Skip the integration tests and summarize what you have so far" },
  parent_tool_use_id: null,
  priority: "now",
  origin: { kind: "human" },
};

• L’outil Agent : tool_use_result est AgentOutput. Effectuez le rendu à partir de celui-ci plutôt que d’analyser le texte du tool_result. Le content d’un résultat completed contient le rapport du sous-agent ou, pour un sous-agent dont le rapport passe par un appel d’outil SubagentHandback, une courte note sur cette remise à la place du rapport. En mode auto sur Claude Code v2.1.271 ou version ultérieure, tout sous-agent qui produit un résultat completed fait son rapport de cette façon, sauf s’il s’agit d’un fork, et Claude reçoit le rapport sous la forme d’un message distinct provenant du sous-agent.
• Un appel WebFetch ou WebSearch que Claude Code a déplacé en arrière-plan pour livrer un message 'now' : le message utilisateur qui porte le tool_result de cet appel a tool_use_result défini sur { detachedToolCall: true }. L’appel est toujours en cours et Claude reçoit son résultat une fois qu’il est terminé. Aucun second tool_result pour ce tool_use_id ne suit : si votre application affiche une ligne pour chaque appel d’outil, marquez donc cette ligne comme déplacée en arrière-plan lorsque ce message arrive. Nécessite Claude Code v2.1.287 ou version ultérieure.
• Un outil MCP dont le résultat contient des blocs resource_link : tool_use_result est un objet doté d’un tableau resourceLinks d’entrées SDKMcpResourceLink. Claude reçoit chaque lien sous la forme d’une ligne de texte dans le bloc tool_result : lisez donc resourceLinks pour afficher les fichiers renvoyés par le serveur au lieu d’analyser ce texte. Claude Code omet resourceLinks lorsque le résultat ne contient aucun lien ainsi que sur les résultats provenant de sous-agents, conserve au maximum 50 liens par résultat et cesse d’ajouter des liens une fois que le tableau atteint 64 Kio de JSON sérialisé. resourceLinks nécessite Agent SDK v0.3.257 ou version ultérieure.
• Un outil MCP qui renvoie structuredContent : tool_use_result est un objet dont le membre structuredContent contient ce que le serveur a envoyé et dont le membre content contient la valeur McpOutput. Les résultats provenant de sous-agents ne portent pas structuredContent.
• Un outil MCP dont le structuredContent se sérialise en plus de 1 048 576 caractères de JSON : Claude Code omet structuredContent de tool_use_result et définit à la place structuredContentOmitted: true, afin que votre application puisse distinguer un objet abandonné d’un outil qui n’en a envoyé aucun. Les autres membres, comme content et resourceLinks, sont conservés, et ce que Claude reçoit ne change pas. Claude Code v2.1.287 ou une version ultérieure applique ce plafond. Deux types d’outils font exception :
  • Les outils provenant de serveurs SDK en processus en sont exemptés et transmettent l’objet entier.
  • Un outil dont l’entrée tools/list déclare une ressource MCP Apps ui:// a une limite de 8 388 608 caractères avec Claude Code v2.1.295 ou une version ultérieure, et les versions antérieures à v2.1.295 l’en exemptent.

​

SDKUserMessageReplay

type SDKUserMessageReplay = {
  type: "user";
  uuid: UUID;
  session_id: string;
  message: MessageParam;
  parent_tool_use_id: string | null;
  isSynthetic?: boolean;
  client_composed?: true;
  tool_use_result?: unknown;
  origin?: SDKMessageOrigin;
  isReplay: true;
};