Aller au contenu principal
Dernière mise à jour le

Sessions d’agent gérées

info

Bêta

Cette fonctionnalité est en version bêta.

Les sessions d'agent gérées offrent à vos agents un magasin durable et indépendant du framework pour l'état de session : l'état qu'un agent ou un framework conserve pour une seule interaction. Il s'agit le plus souvent de l'historique de conversation, c'est-à-dire la transcription ordonnée des messages, des appels d'outils et des résultats qu'un agent lit au start d'un tour et auxquels il ajoute des éléments au fur et à mesure de son exécution. Il peut également s'agir de tout autre état persistant qu'un framework conserve pour l'interaction, tel qu'un graphe LangGraph. Databricks le stocke dans Lakebase et gère le stockage pour vous, de sorte que vous n'avez pas à créer ni à exploiter la base de données.

remarque

Durant la version préliminaire, vous êtes facturé pour l'instance Lakebase sous-jacente qui stocke vos sessions. Aucun frais supplémentaire ne s'applique pour les sessions d'agent gérées elles-mêmes. Les tarifs sont susceptibles d'être modifiés au fil de l'évolution de la version préliminaire.

Utilisez des sessions managées lorsque vous souhaitez :

  • Conservez l'historique des conversations d'un agent pour qu'il survive aux redémarrages et puisse être repris ultérieurement.
  • Reconstruct full context (including tool calls and reasoning) on a follow-up message.
  • Répertoriez, reprenez et créez des Branch à partir d’historiques de conversations directement depuis votre propre interface utilisateur.

Les sessions gérées contiennent l’état d’une seule interaction (état à court terme, au sein de la session). Pour une mémoire durable à long terme qui persiste au-delà des conversations, utilisez la mémoire d’agent gérée.

Fonctionnement des sessions gérées​

Hiérarchie des ressources des sessions d’agents gérés : un magasin de sessions contient de nombreuses sessions, et chaque session contient de nombreux éléments de session ordonnés.

Les sessions gérées comportent trois niveaux :

  • Un session store est le conteneur délimité par le workspace pour les sessions d’un agent. La création d’un store entraîne le provisionnement automatique du stockage Lakebase sous-jacent. Vous choisissez un élément session_store_name unique pour le workspace.

  • Une session correspond à une interaction durable (généralement un fil de discussion) au sein d’un magasin. Une session est identifiée par :

    • actor_id (requis) : propriétaire de la session, tel qu’un utilisateur final ou un autre agent. Elle groupe toutes les sessions d’un même sujet afin de vous permettre de les répertorier et de les filtrer ensemble. Lorsque vous créez une application par utilisateur, définissez actor_id sur l’ID de l’utilisateur (par exemple, l’identité vérifiée de l’utilisateur final provenant de l’authentification de votre application) afin que les sessions de chaque utilisateur restent regroupées. Définissez-le à partir d’un contexte d’application de confiance, et jamais à partir d’une valeur fournie par le modèle ou l’utilisateur.
    • session_id (optionnel) : un identifiant choisi par l’appelant pour l’interaction. Le service en génère un si vous l’omettez.
    • parent_session_id (facultatif) : lie une session à celle à partir de laquelle elle a été ramifiée, pour représenter des conversations ramifiées.

  • Un élément de session correspond à une entrée dans l'historique ordonné d'une session. Chaque élément contient une valeur data opaque et compatible JSON, telle qu'un message, un appel d'outil, un résultat d'outil ou un bloc de raisonnement. Databricks attribue à chaque élément un item_id et un create_time, et n'inspecte ni ne valide son contenu. Les éléments sont immuables après leur ajout.

Le service maintient un ordre déterministe pour les éléments d’une session et autorise chaque opération sur le magasin de sessions.

Conditions requises​

  • Python 3.10 ou version ultérieure , pour utiliser Mason (le client Python et le CLI de Databricks pour les APIs d’agents), qu’utilisent les exemples ci-dessous. Vous pouvez également appeler l’ API REST directement depuis n’importe quel langage, sans nécessiter Python.

Commencer​

Ces exemples configurent des sessions gérées pour un agent de support : ils créent un magasin de sessions, start une session pour une conversation, ajoutent les tours de la conversation et relisent l'historique lors d'une requête ultérieure. Choisissez le client qui correspond à votre projet.

Mason est le client Python et la CLI de Databricks pour les APIs d’agent. Il s’authentifie avec le WorkspaceClient du SDK Databricks.

  1. Installer Mason :

    Bash
    pip install databricks-mason

  2. Créez un magasin de sessions, puis start une session pour une conversation. actor_id correspond au propriétaire de la conversation ; le paramètre facultatif session_id identifie de manière unique cette conversation :

    Python
    from databricks.sdk import WorkspaceClient
    from databricks_mason import MasonClient

    mason = MasonClient(WorkspaceClient())
    session_store = mason.session_stores.create("support-agent-sessions")
    session = session_store.add(actor_id="customer-123", session_id="case-456")

  3. Ajoutez les tours de conversation au fur et à mesure de l’exécution de l’agent. Chaque élément est une valeur compatible avec JSON :

    Python
    session.append_items(
        [
            {"type": "message", "role": "user", "content": "I need help with my cluster."},
            {"type": "message", "role": "assistant", "content": "Let's take a look."},
        ]
    )

  4. Lors d’une requête de suivi, rechargez la session et lisez son historique complet afin de reconstituer le contexte :

    Python
    session = session_store.get("case-456")
    # Request chronological order; list_items defaults to newest-first and auto-pages.
    history = [item.data for item in session.list_items(order_by="create_time asc")]

Les clients prennent également en charge la suppression de l'élément le plus récent, l'effacement des éléments d'une session et la bifurcation d'une conversation en une copie indépendante (éventuellement jusqu'à un élément spécifique). La suppression d'une session qui comporte des sessions enfants nécessite une option de forçage pour propager la suppression en cascade (par exemple, session.delete(force=True)).

Associer la session d'un framework d'agents à des sessions gérées​

Les frameworks d'agents tels que l'OpenAI Agents SDK et le Claude Agent SDK lisent l'historique des conversations au start d'une exécution et ajoutent de nouveaux éléments à la fin. Le magasin de sessions correspond directement à ce modèle :

Opération du framework

Appel du magasin de sessions

Lire l’historique

list_items par ordre chronologique (order_by="create_time asc")

Ajouter des éléments de tour

append les nouveaux éléments

Annuler le dernier élément

pop l’élément le plus récent

Effacer le fil de discussion

clear les éléments de la session

Opération du framework

Appel du magasin de sessions

Lire l’historique

list_items par ordre chronologique (order_by="create_time asc")

Ajouter des éléments de tour

append les nouveaux éléments

Annuler le dernier élément

pop l’élément le plus récent

Effacer le fil de discussion

clear les éléments de la session

Portée et accès​

Les sessions gérées stockent les éléments d’une session sous forme de valeurs opaques compatibles avec JSON : le service conserve et renvoie ce que votre agent ou application de framework y ajoute, sans l’interpréter. Il n'ajoute pas de ressources de contrôle d'exécution telles que des exécutions, des points de contrôle ou des approbations en tant que concepts de premier ordre, bien qu'un framework qui sérialise un tel état puisse le conserver sous forme d'éléments.

Session stores are workspace-scoped, and access is authorized at the store level. Les champs actor_id et metadata prennent uniquement en charge le regroupement et le filtrage ; ils n’accordent et ne restreignent pas l’accès. Set the actor_id from trusted application context rather than a model- or user-supplied value.

Pour permettre à un autre principal, tel que le Service Principal de votre agent, d’utiliser un magasin, accordez-lui l’accès à l’aide de l’opération grant-permission du magasin (session_store.grant_permission(principal_id) dans Mason).

Les sessions gérées et la mémoire gérée sont indépendantes. La suppression d’une session ou d’un magasin de sessions ne supprime pas la mémoire conservée dans un magasin de mémoire.

Étapes suivantes​

Sur cette page