Configurer votre agent

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);
  }
}

import asyncio

from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query

async def main():
    options = ClaudeAgentOptions(
        model="claude-sonnet-5",
        allowed_tools=["Read", "Glob", "Grep"],
        max_turns=8,
        cwd="/path/to/repo",
    )

    async for message in query(
        prompt="Summarize the open TODOs in this repo",
        options=options,
    ):
        if isinstance(message, ResultMessage) and not message.is_error:
            print(message.result)

asyncio.run(main())

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",
};

options = ClaudeAgentOptions(
    model="claude-fable-5",
    fallback_model="claude-opus-5",
)

Les paramètres de requête de l’API Messages temperature, top_p et max_tokens n’ont pas de champs sur l’objet options dans l’une ou l’autre langue. Définissez plutôt le niveau d’effort ou un plafond de dépenses, ou appelez l’API Messages lorsque vous avez besoin de ces paramètres directement.

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" },
};

options = ClaudeAgentOptions(
    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 :

Paramètres et hooks du projet : quels paramètres et hooks du projet se chargent
Compétences : où les compétences de session sont découvertes
Stockage de session : à quel projet une session stockée appartient

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;
    }
  }
}

import asyncio

from claude_agent_sdk import AssistantMessage, ClaudeAgentOptions, ClaudeSDKClient

async def main():
    options = ClaudeAgentOptions(model="claude-sonnet-5")

    async with ClaudeSDKClient(options=options) as client:
        await client.query("Reply with exactly: ready")
        first_model = ""
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                first_model = message.model

        await client.set_model("claude-opus-5")
        await client.set_permission_mode("acceptEdits")

        await client.query("Reply with exactly: done")
        second_model = ""
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                second_model = message.model

    print(f"First turn model: {first_model}")
    print(f"Second turn model: {second_model}")

asyncio.run(main())

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

Chaque modèle a son propre cache de prompt, donc après un basculement en cours de session, la prochaine requête recalcule la conversation complète sans cache aux tarifs du nouveau modèle. Pour plus d’informations, consultez Basculer les modèles.

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

Agent SDK

Créer des agents

Concepts fondamentaux

Entrée et sortie

Étendre avec des outils

Personnaliser le comportement

Contrôle et observabilité

Déploiement

Références SDK

Transmettre les options à une session

Charger les fichiers de paramètres

Choisir un modèle

Définir les variables d’environnement

Définir le répertoire de travail

Limiter les tours et les dépenses

Modifier la configuration en cours de session

Configurer des fonctionnalités spécifiques

Étapes suivantes

​Transmettre les options à une session

​Charger les fichiers de paramètres

​Choisir un modèle

​Définir les variables d’environnement

​Définir le répertoire de travail

​Limiter les tours et les dépenses

​Modifier la configuration en cours de session

​Configurer des fonctionnalités spécifiques

​Étapes suivantes

Transmettre les options à une session

Charger les fichiers de paramètres

Choisir un modèle

Définir les variables d’environnement

Définir le répertoire de travail

Limiter les tours et les dépenses

Modifier la configuration en cours de session

Configurer des fonctionnalités spécifiques

Étapes suivantes