Aller au contenu principal
Dernière mise à jour le

Sessions d’agents

info

Bêta

Cette fonctionnalité est en version bêta.

Les sessions d’agent donnent à vos agents un stockage durable et indépendant du framework pour l’état de la session : l’état qu’un agent ou un framework conserve pour une interaction. Il s’agit le plus souvent de l’historique de la conversation, la transcription ordonnée des messages, les appels d’outils et les résultats qu’un agent lit au start d’un tour et ajoute lorsqu’il s’exécute. Il peut également s'agir de tout autre état persistant dans un framework pour l'interaction, comme un graphe LangGraph. Databricks le stocke dans Lakebase et gère le stockage pour vous. Vous n'avez donc pas à créer ni à gérer la base de données.

remarque

Pendant la période d’évaluation, vous êtes facturé pour l’instance Lakebase sous-jacente qui stocke vos sessions. Aucun frais supplémentaire ne s'applique aux sessions de l'agent. Les tarifs sont sujets à modification au fur et à mesure de l’évolution de la version d’évaluation.

Utilisez les sessions d’agent lorsque vous voulez :

  • 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 d’agent conservent l’état d’une interaction unique (état à court terme, dans la session). Pour une mémoire à long terme qui persiste entre les conversations, utilisez la mémoire de l’agent.

Conditions requises​

  • Installez Python 3.10 ou version supérieure pour utiliser le SDK AgentKit. Le SDK AgentKit est le client Python Databricks pour les APIs d’agent qu’utilisent les exemples ci-dessous. Vous pouvez également appeler l’ API REST directement depuis n’importe quel langage, sans nécessiter Python.

Fonctionnement des sessions d’agent​

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

Les sessions d'agent ont 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.

Commencer​

Ces exemples configurent des sessions d’agent pour un agent de support : ils créent un magasin de sessions, start une session pour une conversation, ajoutent les tours de parole de la conversation et lisent l’historique lors d’une demande ultérieure. Choisissez le client qui convient à votre projet.

Le SDK AgentKit est le client Python Databricks pour les API d’agent, distribué dans le package databricks-agentbricks. Il s’authentifie auprès de WorkspaceClient du SDK Databricks.

  1. Installez le SDK AgentKit :

    Bash
    pip install databricks-agentbricks

  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_agentkit import AgentKitClient

    client = AgentKitClient(WorkspaceClient())
    session_store = client.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 demande de suivi, rechargez la session et consultez 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)).

Prendre en charge une session de framework d'agent avec des sessions d'agent​

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 d’agent stockent les éléments d’une session sous forme de valeurs opaques compatibles avec JSON : le service conserve et renvoie tout ce que votre agent ou application framework ajoute, sans l’interpréter. Il n’ajoute pas de ressources de contrôle d’exécution telles que les exécutions, les points de contrôle ou les approbations en tant que concepts de premier plan, 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 d’attribution d’autorisations du magasin (session_store.grant_permission(principal_id) dans le SDK AgentKit).

Les sessions d’agent et la mémoire des agents sont indépendantes. La suppression d’une session ou d’un magasin de session ne supprime pas la mémoire conservée dans un magasin de mémoire. Pour construire une mémoire à long terme à partir des sessions dans un magasin, créez un pipeline de mémoire.

Étapes suivantes​

Sur cette page