Opérations sur les sessions

Une fois qu'une session existe, utilisez ces opérations pour la lire, la mettre à jour, l'archiver ou la supprimer. Consultez Démarrer une session pour créer une session et lui envoyer du travail.

Statuts de session

Les sessions progressent à travers ces statuts. Consultez Démarrer une session pour le cycle de vie d'une session.

Mise à jour de la configuration de l'agent

Vous pouvez mettre à jour les champs agent.tools et agent.mcp_servers d'une session, y compris les politiques d'autorisation et les paramètres web par outil tels que les filtres de domaine, en cours de session sans créer de nouvelle version de l'agent. Les mises à jour sont locales à la session et ne se propagent pas à l'agent sous-jacent. Les valeurs allowed_domains et blocked_domains mises à jour s'appliquent au reste de la session.

Seuls les champs tools et mcp_servers de l'agent peuvent changer après la création d'une session. Pour exécuter une session avec des valeurs model, system ou skills différentes de celles de l'agent, utilisez les surcharges de configuration de l'agent lorsque vous créez la session. La configuration du modèle de l'agent, y compris son épinglage inference_geo, ne peut pas non plus changer en cours de session : définissez l'épinglage lorsque vous enregistrez l'agent, ou définissez-le ou supprimez-le pour une seule session avec une surcharge model lorsque vous la créez. Le champ system configuré de l'agent est fixe pour toute la durée de vie de la session. Sur les modèles qui le prennent en charge, vous pouvez toujours ajouter des consignes de niveau système en cours de session en envoyant un événement system.message.

La sémantique d'une mise à jour de tools ou mcp_servers est un remplacement complet : le tableau fourni constitue la nouvelle valeur. Pour conserver les entrées existantes, effectuez un GET sur la session, modifiez le tableau, puis renvoyez-le avec un POST.

La session doit être à l'état idle pour mettre à jour l'agent. Pour mettre à jour l'agent pendant que la session est en cours d'exécution, envoyez un événement user.interrupt seul et attendez que la session passe à l'état idle.

ant beta:sessions update --session-id "$SESSION_ID" <<'YAML'
agent:
  tools:
    - type: agent_toolset_20260401
    - type: mcp_toolset
      mcp_server_name: linear
  mcp_servers:
    - type: url
      name: linear
      url: https://mcp.linear.app/sse
YAML

Mise à jour du budget de la session

Une session créée avec un budget accepte deux types de mise à jour du budget : le remplacement du plafond par un nouveau max_list_cost, et sa suppression en définissant budget sur null. Les deux reprennent automatiquement le travail mis en pause lorsque la session a atteint son plafond. Un plafond de remplacement peut être supérieur ou inférieur au plafond actuel, mais il doit être strictement supérieur au coût catalogue consommé par la session, et la suppression est irréversible : un budget non nul n'est accepté que sur une session qui en possède actuellement un, de sorte que vous ne pouvez pas rétablir un budget supprimé ni en ajouter un à une session créée sans budget. Consultez Budgets de session pour des exemples de requêtes, les comportements en cas d'erreur et ce qui est comptabilisé dans le coût catalogue.

Récupération d'une session

ant beta:sessions retrieve --session-id "$SESSION_ID"

Liste des sessions

Les résultats de GET /v1/sessions sont paginés. Utilisez le paramètre de requête limit pour contrôler la taille de la page. Chaque réponse inclut un curseur next_page ; transmettez-le comme paramètre page lors de la requête suivante pour récupérer la page suivante. next_page vaut null lorsqu'il n'y a plus de résultats.

Pour revenir à la page précédente, transmettez prev_page comme paramètre page. prev_page vaut null lorsque vous êtes sur la première page.

Un curseur page est opaque et encode l'order de la requête qui l'a produit. Le paramètre de requête order définit le sens de tri des résultats, asc ou desc par date de création ; la valeur par défaut est desc (les plus récents en premier). Réutiliser un curseur avec un order différent renvoie une erreur 400, tout comme modifier un filtre created_at de sorte qu'il exclue la position du curseur. Les autres paramètres de requête, y compris les filtres restants et limit, peuvent changer entre les requêtes paginées. Pour les champs de pagination communs aux points de terminaison de liste, consultez Pagination.

# --format raw renvoie une enveloppe de page avec ses curseurs prev_page et next_page ;
# la sortie par défaut pagine automatiquement et n'émet que les sessions.
cursors=$(ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --format raw \
  --transform '{prev_page,next_page}')
printf '%s\n' "$cursors"

# Repassez le curseur next_page via --page pour récupérer la page suivante.
NEXT_PAGE=$(jq -r '.next_page' <<< "$cursors")
ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --page "$NEXT_PAGE" \
  --format raw \
  --transform '{prev_page,next_page}'
# Passez le prev_page de cette réponse via --page pour revenir en arrière de la même façon.

Archivage d'une session

Archivez une session pour empêcher l'envoi de nouveaux événements tout en préservant son historique. Une session à l'état running ne peut pas être archivée ; pour en archiver une, envoyez un événement user.interrupt seul et attendez que la session passe à l'état idle.

ant beta:sessions archive \
  --session-id "$SESSION_ID"

Suppression d'une session

Supprimez une session pour retirer définitivement son enregistrement, ses événements et le sandbox associé. Une session à l'état running ne peut pas être supprimée ; pour en supprimer une, envoyez un événement user.interrupt seul et attendez que la session passe à l'état idle.

Les magasins de mémoire, les coffres-forts, les skills, les environnements et les agents sont des ressources indépendantes et ne sont pas affectés par la suppression d'une session. Les fichiers que vous avez téléversés via l'API Files ne sont pas non plus affectés, mais les fichiers produits par la session elle-même lui sont rattachés et sont définitivement supprimés avec son système de fichiers. Téléchargez tout ce que vous devez conserver avant de supprimer la session. Un fichier de sortie écrit à la fin du dernier tour peut mettre quelques secondes après le passage de la session à l'état idle pour apparaître dans la liste des fichiers de la session ; vérifiez donc d'abord que les fichiers attendus y figurent.

ant beta:sessions delete \
  --session-id "$SESSION_ID"