SpyBara
Go Premium

agent-sdk/configuration.md 2026-09-17 05:00 UTC to 2026-09-18 23:58 UTC

This page contains 315 additions and 0 deletions.

2026
Fri 18 23:58 Tue 22 23:59

Configurer votre agent

Configurez les sessions du SDK Agent : composez l'objet options, définissez le modèle, l'environnement et les limites, et trouvez la page de chaque option de fonctionnalité.

Une session du SDK Agent lit la configuration à partir des fichiers de paramètres, des variables d'environnement et de l'objet options que vous transmettez au démarrage. Cette page montre comment composer l'objet options et quels fichiers de paramètres et variables d'environnement le contrôlent.

Pour chaque type d'option et sa valeur par défaut, consultez les références Options (TypeScript) et ClaudeAgentOptions (Python).

Transmettre les options à une session

Chaque appel query() accepte un objet options : Options en TypeScript, ClaudeAgentOptions en Python. Chaque champ est facultatif, et une session démarrée sans options s'exécute avec les valeurs par défaut du SDK. L'exemple ci-dessous configure une session en lecture seule qui résume les TODOs ouverts d'un projet. Les paires se lisent comme TypeScript / Python où les orthographes diffèrent :

  • model : choisit le modèle
  • allowedTools / allowed_tools : pré-approuve une liste d'outils en lecture seule
  • maxTurns / max_turns : limite le nombre de tours
  • cwd : définit le répertoire de travail
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Summarize the open TODOs in this repo",
options: {
model: "claude-sonnet-5",
allowedTools: ["Read", "Glob", "Grep"],
maxTurns: 8,
cwd: "/path/to/repo",
},
})) {
if (message.type === "result" && message.subtype === "success" && !message.is_error) {
console.log(message.result);
}
}

Pointez cwd vers l'un de vos propres projets et exécutez l'exemple. Le résumé des TODOs ouverts de ce projet s'affiche à l'arrivée du message de résultat.

allowedTools (TypeScript) ou allowed_tools (Python) pré-approuve les outils listés, de sorte que les appels à ces outils s'exécutent sans attendre d'approbation. Les outils en dehors de la liste restent disponibles. Lorsque Claude appelle un outil non listé, le mode de permission décide si l'appel s'exécute. Pour plus d'informations, consultez Règles d'autorisation et de refus.

Charger les fichiers de paramètres

Les fichiers de paramètres fournissent une configuration au-delà de l'objet options. Deux options contrôlent la façon dont ils se chargent :

  • settingSources / setting_sources : contrôle quelles sources du système de fichiers se chargent : utilisateur, projet et local. Les fichiers de paramètres et les fichiers CLAUDE.md arrivent par ces sources.
  • settings : charge un chemin de fichier de paramètres ou une chaîne JSON en ligne dans l'une ou l'autre langue, et TypeScript accepte également un objet de paramètres. Quelle que soit la forme que vous transmettez, elle remplace les paramètres du système de fichiers utilisateur, projet et local ; seuls les paramètres de politique gérée ont un rang plus élevé. Les références documentent l'ordre de précédence complet sous Précédence des paramètres pour TypeScript et Précédence des paramètres pour Python.

Passez [] pour désactiver les paramètres utilisateur, projet et local. Pour plus d'informations, consultez Utiliser les fonctionnalités de Claude Code dans le SDK.

Choisir un modèle

À moins que l'option model, vos paramètres ou votre environnement ne sélectionnent un modèle, une nouvelle session démarre sur le modèle par défaut de Claude Code. Pour l'ordre de ces sources, consultez Définir votre modèle. Définissez model pour épingler un modèle spécifique, ou pour en choisir un plus petit pour des agents plus rapides et moins chers. La valeur prend un alias de modèle ou un nom de modèle complet ; les alias et les versions qu'ils résolvent sont listés sous Alias de modèles.

Définissez fallbackModel (TypeScript) ou fallback_model (Python) pour nommer un modèle de secours. Lorsque le modèle principal est surchargé ou indisponible, la session bascule vers le modèle de secours. Le modèle principal est réessayé au début de chaque tour utilisateur, de sorte que la session y revient une fois la panne résolue.

Dans l'une ou l'autre langue, l'option accepte un seul modèle ou une liste de secours séparée par des virgules. Pour l'ordre et la limite de chaîne, consultez Chaînes de modèles de secours. En TypeScript, un modèle de secours égal à model lève une erreur au démarrage.

Les exemples ci-dessous montrent une liste de secours en TypeScript et un seul modèle de secours en Python :

const options = {
model: "claude-fable-5",
fallbackModel: "claude-opus-5,claude-sonnet-5",
};

Définir les variables d'environnement

L'option env définit les variables d'environnement pour le processus Claude Code qui exécute votre session. Le fait que vos valeurs remplacent l'environnement hérité ou le fusionnent diffère selon la langue :

  • TypeScript : env remplace l'environnement du sous-processus
  • Python : le SDK fusionne vos valeurs sur l'environnement hérité, et vos valeurs remplacent les valeurs héritées

En TypeScript, propagez process.env dans env pour conserver les variables héritées telles que PATH, HOME et ANTHROPIC_API_KEY. Lorsque vous laissez env non défini, le sous-processus hérite de votre environnement dans les deux langues.

L'exemple achemine le trafic API via une passerelle en définissant ANTHROPIC_BASE_URL.

const options = {
env: { ...process.env, ANTHROPIC_BASE_URL: "https://gateway.example.com" },
};

Les variables que vous transmettez peuvent également configurer Claude Code lui-même. Pour les variables que le processus Claude Code lit, consultez Variables d'environnement. Pour régler les délais d'expiration de l'API et la détection de blocage de cette façon, suivez la section Gérer les réponses API lentes ou bloquées dans la référence TypeScript ou la référence Python.

Définir le répertoire de travail

Définissez cwd pour exécuter la session dans un répertoire spécifique. Lorsque vous laissez cwd non défini, la session s'exécute dans le répertoire de travail de votre processus. Aucun SDK n'a de setter pour cwd. Pour exécuter dans un répertoire différent, démarrez une autre session avec ce cwd.

Claude Code lit le répertoire de travail pour déterminer :

Pour permettre aux outils d'accéder aux fichiers en dehors du répertoire de travail, ajoutez des chemins avec additionalDirectories (TypeScript) ou add_dirs (Python). Pour la portée de cette autorisation, consultez Les répertoires supplémentaires accordent l'accès aux fichiers, pas la configuration.

Limiter les tours et les dépenses

Limitez les tours et les dépenses avec maxTurns / max_turns et maxBudgetUsd / max_budget_usd. Les deux limites sont désactivées lorsqu'elles ne sont pas définies. Lorsqu'une session atteint une limite, l'exécution se termine par un message de résultat dont le sous-type nomme la limite, error_max_turns ou error_max_budget_usd. Ce qui se passe ensuite diffère selon le mode d'entrée :

  • query() en un seul coup : le SDK produit le résultat de la limite, puis lève une exception, donc enveloppez la boucle dans un bloc try pour continuer au-delà de l'erreur
  • Entrée en streaming : la session reste active au-delà d'un résultat de limite, et le nombre de tours maximum recommence pour chaque message en file d'attente. Le total du budget s'accumule sur les messages, et une fois que les dépenses atteignent la limite, les messages ultérieurs dans la même conversation se terminent par le même résultat de budget. Un /clear recommence le budget

Les deux limites traitent 0 différemment :

  • maxTurns / max_turns : 0 exécute la session sans limite de tours, comme laisser l'option non définie
  • maxBudgetUsd / max_budget_usd : l'interface de ligne de commande rejette 0 comme un montant invalide au démarrage, et la session ne s'exécute jamais

Pour plus d'informations sur les deux limites, y compris les dépenses des sous-agents, consultez Tours et budget.

Modifier la configuration en cours de session

Lorsque vous démarrez une session avec entrée en streaming, vous pouvez basculer son modèle et son mode de permission pendant qu'elle s'exécute. L'endroit où vous appelez les setters diffère selon la langue :

  • TypeScript : méthodes sur l'objet que query() retourne
  • Python : méthodes sur ClaudeSDKClient, puisque query() retourne un itérateur simple sans méthodes de contrôle

Les deux langues ont les mêmes setters :

  • setModel() / set_model() : bascule le modèle. Appelez-le sans modèle pour basculer vers le modèle par défaut de Claude Code plutôt que le model que vous avez transmis dans les options.
  • setPermissionMode() / set_permission_mode() : bascule le mode de permission

TypeScript a également applyFlagSettings() et updateSettings() :

  • applyFlagSettings() : applique les paramètres à l'exécution, comme dans await session.applyFlagSettings({ effortLevel: "high" }). La méthode prend les clés du fichier de paramètres plutôt que les champs d'options, donc consultez la référence applyFlagSettings() pour le schéma et pour savoir quelles clés prennent effet en cours de session.
  • updateSettings() : écrit un ensemble de clés autorisées dans le fichier de paramètres locaux du projet, comme dans await session.updateSettings("localSettings", { outputStyle: "Explanatory" }). Les clés écrites prennent effet à la prochaine requête de la session et persistent pour les sessions ultérieures qui chargent les paramètres local. La ligne de la méthode dans le tableau des méthodes nomme les clés autorisées et le plancher de version.

L'exemple ci-dessous exécute une session de deux tours, modifie la configuration entre les tours et affiche le modèle qui a répondu à chaque tour. En TypeScript, le flux de prompt maintient le deuxième message jusqu'à ce que les setters aient été exécutés, et le deuxième tour s'exécute sur le nouveau modèle.

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

function userMessage(text: string): SDKUserMessage {
return { type: "user", message: { role: "user", content: text }, parent_tool_use_id: null };
}

// Hold the second prompt until the setters have run.
let startSecondTurn!: () => void;
const secondTurnReady = new Promise<void>((resolve) => {
startSecondTurn = resolve;
});

async function* turnPrompts(): AsyncGenerator<SDKUserMessage, void> {
yield userMessage("Reply with exactly: ready");
await secondTurnReady;
yield userMessage("Reply with exactly: done");
}

const session = query({
prompt: turnPrompts(),
options: {
model: "claude-sonnet-5",
},
});

let turnModel = "";
let completedTurns = 0;

for await (const message of session) {
if (message.type === "assistant") {
turnModel = message.message.model;
} else if (message.type === "result") {
completedTurns += 1;
if (completedTurns === 1) {
console.log(`First turn model: ${turnModel}`);
await session.setModel("claude-opus-5");
await session.setPermissionMode("acceptEdits");
startSecondTurn();
} else {
console.log(`Second turn model: ${turnModel}`);
break;
}
}
}

Sur l'API Claude, le programme affiche First turn model: claude-sonnet-5, puis Second turn model: claude-opus-5 après le basculement.

Configurer des fonctionnalités spécifiques

Le tableau ci-dessous mappe chaque option à la fonctionnalité qu'elle configure. Pour les options que cette page ne couvre pas, consultez les références TypeScript et Python. Si vous connaissez votre objectif mais pas quelle option le sert, commencez par Choisir la bonne fonctionnalité.

TypeScript Python Contrôle Couvert dans
permissionMode permission_mode Ce que l'agent peut faire sans approbation Configurer les permissions
allowedTools allowed_tools Quels appels d'outils sont pré-approuvés Configurer les permissions
canUseTool can_use_tool Votre rappel d'approbation pour les appels d'outils Gérer les demandes d'approbation d'outils
systemPrompt system_prompt Les instructions de l'agent Modification des invites système
settingSources setting_sources Quels paramètres du système de fichiers se chargent Utiliser les fonctionnalités de Claude Code dans le SDK
mcpServers mcp_servers Serveurs d'outils externes Connecter à des outils externes avec MCP
agents agents Définitions des sous-agents Sous-agents
hooks hooks Rappels aux points du cycle de vie Hooks
skills skills Quelles compétences se chargent Étendre les agents avec des compétences
plugins plugins Quels plugins se chargent Plugins
outputFormat output_format Schémas de sortie structurée Sorties structurées
resume resume Continuation d'une session stockée Sessions
forkSession fork_session Branchement d'une session Sessions
sessionStore session_store Persistance de session externe Stockage de session
enableFileCheckpointing enable_file_checkpointing Éditions de fichiers rembobinables Checkpointing de fichiers
effort effort Combien de travail Claude met dans les réponses Niveau d'effort
sandbox sandbox Comportement du sandbox pour l'exécution des outils Références TypeScript et Python, avec contexte de déploiement dans Déploiement sécurisé

Étapes suivantes

Pour voir la configuration composée dans des agents fonctionnels :

  • Démarrage rapide : construisez et exécutez un premier agent de bout en bout
  • Exemples : trouvez un projet complet et exécutable ou une recette guidée Claude Cookbook qui correspond à ce que vous voulez construire
  • Isolation multi-locataire : isolez les paramètres et la mémoire de chaque locataire avec settingSources / setting_sources, env et cwd