Opérations de session

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 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 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 lorsque vous créez 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 ajouter des directives au 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 est la nouvelle valeur. Pour préserver les entrées existantes, effectuez un GET de 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 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 la direction 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 ; 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 à tous 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 fichiers, les magasins de mémoire, les coffres, 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"