Démarrer une session

Une session est une instance d'agent au sein d'un environnement. Chaque session fait 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 pour provisionner son bac à sable, puis envoyer un événement utilisateur pour démarrer le travail.



Création d'une session

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

ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID"

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

ant beta:sessions create <<YAML
agent:
  type: agent
  id: $AGENT_ID
  version: 1
environment_id: $ENVIRONMENT_ID
YAML



Remplacer la configuration de l'agent pour une session

Vous pouvez passer agent sous trois formes : une chaîne d'ID d'agent, un objet de version épinglée (type: "agent"), ou un objet de remplacements (overrides). La forme avec remplacements modifie certaines 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 créer de nouvelle version de l'agent. Pour la forme avec remplacements, définissez type sur agent_with_overrides et passez l'id de l'agent et éventuellement une version (omettez version pour utiliser la dernière version de l'agent). Incluez ensuite n'importe lequel des champs model, system, tools, mcp_servers ou skills avec les valeurs que la session doit utiliser.

Chaque champ remplaçable suit les trois mêmes 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 intégralement à system, mcp_servers et skills. Il existe deux 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 le champ skills effectif de la session n'est pas vide, car les compétences nécessitent l'outil read. Sinon, tools: null et tools: [] effacent le champ.
• Définir le champ sur une valeur : La valeur remplace intégralement celle de l'agent. Les remplacements ne fusionnent jamais avec la configuration de l'agent, donc un remplacement de tools doit lister tous les outils que la session doit avoir.

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 après l'application des remplacements. Ses champs id et version identifient toujours l'agent et la version auxquels les remplacements sont appliqués. Cela vous permet de retracer une session jusqu'à son agent de base.

# Le champ `agent` de la réponse est l'instantané résolu : chaque override remplace ce
# champ pour cette session uniquement, et la ressource agent conserve son id et sa version.
ant beta:sessions create \
  --transform 'agent.{id,version,model,system}' \
  --format json <<YAML
agent:
  type: agent_with_overrides
  id: $AGENT_ID
  model:
    id: claude-sonnet-5
  system: null
environment_id: $ENVIRONMENT_ID
YAML



Authentification MCP via les coffres-forts

Si votre agent utilise des outils MCP qui nécessitent une authentification, passez 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 rafraîchissement des jetons en votre nom. Consultez S'authentifier avec des coffres-forts pour savoir comment créer des coffres-forts et enregistrer des identifiants.

ant beta:sessions create <<YAML
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
vault_ids:
  - $VAULT_ID
YAML



Démarrage de la session

La création d'une session provisionne le bac à sable de l'environnement mais ne démarre aucun travail. Pour déléguer une tâche, envoyez des événements à la session en utilisant un événement utilisateur. La session agit comme une machine à états qui suit la progression tandis que les événements pilotent l'exécution réelle.

ant beta:sessions:events send \
  --session-id "$SESSION_ID" <<'YAML'
events:
  - type: user.message
    content:
      - type: text
        text: List the files in the working directory.
YAML

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 les statuts par lesquels passe une session, et Opérations de session pour récupérer, lister, mettre à jour, archiver et supprimer des sessions.

Pour créer automatiquement des sessions selon un calendrier récurrent, consultez Déploiements planifiés.