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 les statuts suivants. 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 une 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 être modifiés 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. 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 remplacer l'invite système effective entre les tours 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 conserver 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



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 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, passez 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 selon la 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 ; les autres paramètres de requête, y compris les filtres 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"

# Repasser le curseur next_page comme --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}'
# Passer le prev_page de cette réponse comme --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 fichiers, 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.

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