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 de permissions, 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.

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 remplacements de configuration d'agent lors de la création de 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 lors de l'enregistrement de l'agent, ou définissez-le ou supprimez-le pour une seule session avec un remplacement model lors de sa création. 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 instructions 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 devient la nouvelle valeur. Pour préserver les entrées existantes, effectuez un GET sur la session, modifiez le tableau, puis renvoyez-le avec un POST.

La session doit être idle pour mettre à jour l'agent. Interrompez la session si vous devez mettre à jour l'agent pendant qu'elle est en cours d'exécution.

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 session

Une session créée avec un budget accepte deux types de mise à jour de budget : remplacer le plafond par un nouveau max_list_cost, et le supprimer 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 tarifaire consommé par la session, et la suppression est à sens unique : un budget non nul n'est accepté que sur une session qui en possède actuellement un, vous ne pouvez donc pas rajouter 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 d'erreur et ce qui est comptabilisé dans le coût tarifaire.



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 ; passez-le comme paramètre page dans la requête suivante pour récupérer la page suivante. next_page est null lorsqu'il n'y a plus de résultats.

Pour revenir à la page précédente, passez prev_page comme paramètre page. prev_page est 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 (le plus récent 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 partagés entre les 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 running ne peut pas être archivée ; envoyez un événement d'interruption si vous devez l'archiver immédiatement.

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



Suppression d'une session

Supprimez une session pour effacer définitivement son enregistrement, ses événements et le bac à sable associé. Une session running ne peut pas être supprimée ; envoyez un événement d'interruption si vous devez la supprimer immédiatement.

Les magasins de mémoire, les coffres-forts, les compétences, 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 propres 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.

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