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 mises à jour de allowed_domains et blocked_domains s'appliquent pour le 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 de model, system ou skills différentes de celles de l'agent, utilisez les remplacements de configuration de l'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 lorsque vous enregistrez l'agent, ou définissez-le ou supprimez-le pour une seule session avec un remplacement de model lors de sa création. Le champ system configuré de l'agent est fixe pendant toute la durée de vie de la session. Sur les modèles qui le prennent en charge, vous pouvez tout de même 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 de 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. 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 devienne idle. Si une exécution de workflow est ouverte, qu'elle soit en cours ou en pause, la mise à jour renvoie une erreur 400, même lorsque la session est idle. Une interruption ne met pas fin à une exécution ; la mise à jour échoue donc toujours après l'interruption de la session. Envoyez un user.message qui demande à l'agent d'arrêter ses exécutions, ou attendez que toutes les exécutions soient terminées.

client.beta.sessions.update(
    session.id,
    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"}
        ],
    },
)

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 passant budget=None. 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 déjà 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 pris en compte dans le coût catalogue.

Récupération d'une session

retrieved = client.beta.sessions.retrieve(session.id)
print(f"Status: {retrieved.status}")

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.

# Définissez `limit` à une valeur basse pour que les résultats s'étendent sur plusieurs pages.
first_page = client.beta.sessions.list(limit=1, agent_id=agent.id)
# `prev_page` vaut None sur la première page ; `next_page` vaut None sur la dernière.
print(f"prev_page: {first_page.prev_page}")
print(f"next_page: {first_page.next_page}")

# Repassez `next_page` comme `page` pour récupérer la page suivante.
second_page = client.beta.sessions.list(
    limit=1, agent_id=agent.id, page=first_page.next_page
)
for listed_session in second_page.data:
    print(f"{listed_session.id}: {listed_session.status}")

# Repassez `prev_page` comme `page` pour revenir à la page précédente.
previous_page = client.beta.sessions.list(
    limit=1, agent_id=agent.id, page=second_page.prev_page
)
for listed_session in previous_page.data:
    print(f"{listed_session.id}: {listed_session.status}")
# Pour une itération vers l'avant uniquement, l'objet page est aussi directement itérable.

Archivage d'une session

Archivez une session pour empêcher l'envoi de nouveaux événements tout en conservant son historique. Une session running ne peut pas être archivée ; pour l'archiver, envoyez un événement user.interrupt seul et attendez que la session devienne idle. Si une exécution de workflow est ouverte, l'archivage peut renvoyer une erreur 400, même lorsque la session est idle, ou il peut réussir et mettre fin à l'exécution. Avant d'archiver, envoyez un user.message qui demande à l'agent d'arrêter ses exécutions, ou attendez que chaque exécution soit terminée. Archivez ensuite la session une fois qu'elle est idle.

client.beta.sessions.archive(session.id)

Suppression d'une session

Supprimez une session pour effacer définitivement son enregistrement, ses événements et le sandbox associé. Une session running ne peut pas être supprimée ; pour la supprimer, envoyez un événement user.interrupt seul et attendez que la session devienne idle. Si une exécution de workflow est ouverte, la suppression peut renvoyer une erreur 400, même lorsque la session est idle, ou elle peut réussir. Après une suppression réussie, aucun événement workflow_run ne signale la fin des exécutions de la session. Avant de supprimer, envoyez un user.message qui demande à l'agent d'arrêter ses exécutions, ou attendez que chaque exécution soit terminée. Supprimez ensuite la session une fois qu'elle est 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.

client.beta.sessions.delete(session.id)