Démarrer une session

Une session est une instance d'agent au sein d'un environnement. Chaque session référence un agent et un environnement (tous deux créés séparément), et conserve l'historique de conversation au fil de multiples interactions. Les sessions suivent un cycle de vie en deux étapes : d'abord créer la session, puis envoyer un événement utilisateur pour démarrer le travail. Vous pouvez également regrouper les deux étapes en un seul appel avec initial_events.

Créer une session

Une session nécessite un ID d'agent et un ID d'environment. Les agents sont des ressources versionnées ; transmettre l'ID de l'agent sous forme de chaîne crée la session avec la dernière version de l'agent.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

Pour épingler une session à une version spécifique de l'agent, transmettez un objet. Cela vous permet de contrôler exactement quelle version s'exécute et d'échelonner le déploiement de nouvelles versions de manière indépendante.

pinned_session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": 1},
    environment_id=environment.id,
)

Amorcer la session avec des événements initiaux

Vous pouvez créer une session et démarrer son travail en un seul appel. initial_events est un tableau facultatif d'événements initiaux à envoyer à la session lors de sa création, traités dans l'ordre. Il prend en charge les événements user.message et user.define_outcome, et accepte un maximum de 50 événements. Une liste non vide démarre la boucle de l'agent dans le même appel : la session est créée directement avec le statut running, sans requête supplémentaire.

L'exemple suivant crée une session avec un seul user.message dans initial_events :

seeded_session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    initial_events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)
# Les initial_events ne sont pas renvoyés dans la réponse de création ; relisez-les
# depuis la liste d'événements de la session.
for event in client.beta.sessions.events.list(seeded_session.id):
    if event.type == "user.message":
        for block in event.content:
            if block.type == "text":
                print(f"Seeded event: {block.text}")

Aucun autre type d'événement n'est accepté. Les événements qui répondent à un tour de l'agent (user.tool_confirmation, user.tool_result et user.custom_tool_result) ne sont pas acceptés car aucun tour de l'agent n'existe encore, et user.interrupt n'est pas accepté car il n'y a aucun tour à arrêter. Contrairement aux initial_events d'un déploiement planifié, les initial_events d'une session n'acceptent pas system.message.

Chaque événement dans initial_events est validé et persisté avant le retour de la réponse de création, dans l'ordre de la liste, avec un ID attribué par le serveur, exactement comme si vous l'aviez envoyé au point de terminaison d'envoi d'événements immédiatement après la création. Les règles de contenu par événement sont également les mêmes que sur ce point de terminaison. Une liste vide équivaut à omettre le champ. La validation fonctionne en tout ou rien : si un événement échoue à la validation, la requête entière est rejetée et aucune session n'est créée.

La requête de création est rejetée dans les cas suivants :

Un événement user.define_outcome dans initial_events est accepté dans les mêmes conditions que l'envoi d'un tel événement à une session existante ; consultez Définir des résultats.

Remplacer la configuration de l'agent pour une session

Vous pouvez transmettre agent sous trois formes : une chaîne d'ID d'agent, un objet à version épinglée (type: "agent") ou un objet de remplacements (overrides). La forme avec remplacements modifie des parties de la configuration de l'agent pour une seule session. Utilisez-la pour essayer un modèle différent ou accorder un outil supplémentaire dans une session sans versionner l'agent. Pour la forme avec remplacements, définissez type sur agent_with_overrides et transmettez l'id de l'agent et, facultativement, une version (omettez version pour utiliser la dernière version de l'agent). Incluez ensuite n'importe lesquels des champs model, system, tools, mcp_servers ou skills avec les valeurs que la session doit utiliser.

Chaque champ remplaçable suit les mêmes trois règles :

• Omettre le champ : la session hérite de la valeur de la version de l'agent qu'elle référence.
• Définir le champ sur null, ou sur un tableau vide pour les champs de type liste : la session s'exécute avec ce champ effacé. Cette règle s'applique pleinement à system et skills. Il existe trois exceptions :
  • model ne peut jamais être effacé. Une session a toujours besoin d'un modèle, donc model: null renvoie une erreur 400 agent_model_required.
  • Effacer tools renvoie une erreur 400 lorsque les skills effectifs de la session ne sont pas vides, car les skills nécessitent l'outil read. Sinon, tools: null et tools: [] effacent le champ.
  • Effacer mcp_servers renvoie une erreur 400 lorsque les tools effectifs de la session contiennent encore un mcp_toolset qui référence l'un des serveurs de l'agent. Remplacez tools dans la même requête pour supprimer ces entrées mcp_toolset, puis effacez mcp_servers.
• Définir le champ sur une valeur : la valeur remplace intégralement la valeur de l'agent. Les remplacements ne sont jamais fusionnés avec la configuration de l'agent, donc un remplacement de tools doit lister chaque outil dont la session doit disposer. De même, un remplacement de model remplace intégralement l'objet model de l'agent, donc l'effort propre à l'agent n'est pas reporté. Pour exécuter la session à un niveau d'effort spécifique, définissez effort dans l'objet model du remplacement. Un niveau que le modèle ne prend pas en charge renvoie une erreur 400, et un remplacement de model sans effort s'exécute au niveau d'effort par défaut de ce modèle.

Les remplacements s'appliquent uniquement à la session que vous créez. Ils ne modifient pas la ressource agent et ne créent pas de nouvelle version de l'agent, de sorte que les autres sessions qui référencent le même agent ne sont pas affectées.

Dans la réponse, l'objet agent reflète la configuration avec laquelle la session s'exécute une fois les remplacements appliqués. Ses champs id et version identifient toujours l'agent et la version auxquels les remplacements sont appliqués. Cela vous permet de remonter d'une session jusqu'à son agent de base.

L'exemple suivant démarre une session qui remplace le modèle et efface l'invite système :

override_session = client.beta.sessions.create(
    agent={
        "type": "agent_with_overrides",
        "id": agent.id,
        "model": {"id": "claude-sonnet-5"},
        "system": None,  # clear the agent's system prompt for this session
    },
    environment_id=environment.id,
)
# L'agent de la réponse est l'instantané résolu avec les remplacements appliqués.
print(f"Model: {override_session.agent.model.id}")
print(f"System: {override_session.agent.system}")

Épingler la zone géographique d'inférence pour une session

Comme un remplacement de model remplace intégralement l'objet model de l'agent, il définit ou efface également l'épinglage inference_geo du modèle pour la session : un remplacement qui inclut inference_geo épingle la zone géographique qui traite les requêtes de modèle de la session, et un remplacement qui l'omet efface l'épinglage de l'agent, de sorte que la session suit le default_inference_geo de l'espace de travail. La valeur remplacée est validée par rapport aux allowed_inference_geos de l'espace de travail lors de la création de la session.

L'exemple suivant démarre une session à partir d'un agent dont le modèle n'a pas d'épinglage géographique, épingle les requêtes de modèle de la session à l'inférence aux États-Unis en incluant inference_geo dans le remplacement de model, et affiche la valeur renvoyée dans le champ agent.model de la réponse :

session = client.beta.sessions.create(
    agent={
        "type": "agent_with_overrides",
        "id": agent.id,
        # Replaces the agent's `model` in full: restate `id`, add `inference_geo` to pin.
        "model": {"id": "claude-opus-5-5", "inference_geo": "us"},
    },
    environment_id=environment.id,
)
print(f"Inference geo: {session.agent.model.inference_geo}")

Définir un budget de session

Pour plafonner ce qu'une session peut dépenser, transmettez l'objet facultatif budget lors de sa création. Un budget est un plafond strict sur le coût au tarif public (list cost) de la session : la plateforme tarifie tout ce que la session consomme aux tarifs publics, et la session cesse d'émettre de nouvelles requêtes de modèle dès que ce total cumulé atteint max_list_cost. Définissez type sur limit et donnez à max_list_cost un amount et une currency. amount est un nombre entier de cents américains écrit sous forme de chaîne, par exemple "2500" pour 25,00 $ ; l'API accepte une chaîne plutôt qu'un nombre afin qu'aucun arrondi en virgule flottante ne soit jamais appliqué. USD est la seule devise actuellement prise en charge. Lorsque la session atteint le plafond, elle se met en pause et devient inactive avec le motif d'arrêt budget_reached. Le plafond est appliqué entre les requêtes de modèle, de sorte que la requête qui le franchit se termine d'abord et que le coût final de la session peut se situer légèrement au-delà du plafond. Un budget ne peut être attaché qu'à la création : vous pouvez le modifier ou le supprimer ultérieurement, mais vous ne pouvez pas en ajouter un à une session créée sans budget.

L'exemple suivant crée une session avec un budget de 25,00 $ ; la réponse renvoie le budget sur la ressource de session :

curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2500", "currency": "USD"}
  }
}
EOF

Consultez Budgets de session pour savoir comment fonctionne l'application du plafond, ce qui est comptabilisé dans le coût au tarif public et comment les budgets se comportent dans les sessions multi-agents.

Authentification MCP via les coffres-forts

Si votre agent utilise des outils MCP qui nécessitent une authentification, transmettez vault_ids lors de la création de la session pour référencer un coffre-fort (vault) contenant des identifiants OAuth stockés. Anthropic gère le renouvellement des jetons en votre nom. Consultez S'authentifier avec les coffres-forts pour savoir comment créer des coffres-forts et enregistrer des identifiants.

vault_session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

Démarrer la session

Créer une session sans initial_events enregistre la session mais ne démarre aucun travail ; le sandbox de l'environnement commence à être provisionné dès que la session est créée, de sorte que le premier appel d'outil n'a pas à l'attendre. Pour déléguer une tâche, envoyez des événements à la session à l'aide d'un événement utilisateur. Pour fournir le premier événement dans la requête de création à la place, consultez Amorcer la session avec des événements initiaux. La session agit comme une machine à états qui suit la progression tandis que les événements pilotent l'exécution réelle.

client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)

Consultez Flux d'événements de session pour savoir comment diffuser en streaming les réponses de l'agent et gérer les confirmations d'outils.

Consultez Statuts de session pour connaître les statuts par lesquels passe une session.

Étapes suivantes