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 magasin de session est un conteneur au niveau du workspace pour les sessions d'un agent. La création d'un magasin provisionne automatiquement le stockage Lakebase sous-jacent. Vous choisissez un ID de magasin unique au 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) : fait de la session un enfant d’une autre session dans le magasin, comme la conversation d’un sous-agent. Définissez-le lorsque vous créez la session.

  • 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 création d’une copie indépendante d’une conversation (éventuellement jusqu’à un élément spécifique). Une session dérivée n’a pas de session parente, et la suppression de la session source ne la supprime pas. La suppression d’une session supprime toujours ses sessions enfants, et leurs éléments.

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.

Les stockages de session sont limités au workspace et l’accès est autorisé au niveau du stockage. Le contrôle d’accès au stockage couvre les sessions d’un stockage. N’importe quel utilisateur du workspace peut lister et obtenir les stockages de session, notamment leurs identifiants et leurs descriptions. Les champs actor_id et metadata prennent uniquement en charge le regroupement et le filtrage ; ils n’accordent pas ni ne restreignent l’accès. Définissez actor_id à partir du contexte de l'application approuvée au lieu d'une valeur fournie par l'utilisateur ou le modèle.

Pour permettre à un autre principal, comme le service principal de votre agent, d'utiliser un magasin, accordez-lui l'accès avec l'opération grant-permission du magasin (session_store.grant_permission(principal_id) dans le SDK AgentKit). Seul le créateur du magasin ou un administrateur du workspace peut accorder l'accès.

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