メインコンテンツまでスキップ
に最終更新

マネージドエージェントセッション

備考

ベータ版

この機能はベータ版です。

マネージドエージェントセッションにより、エージェントの状態（1回のやり取りに対してエージェントやフレームワークが保持する状態）を保存するための、耐久性がありフレームワークに依存しないストアがエージェントに提供されます。最も一般的な原因は、会話履歴、つまりメッセージ、ツール呼び出し、およびエージェントがターンのはじめに読み込み、ラン時に追加していく結果の順序付きトランスクリプトです。また、LangGraph グラフなど、フレームワークがやり取りのために保持するその他の状態であってもかまいません。Databricks が Lakebase に保存し、ストレージを管理するため、ユーザーがデータベースを構築または運用する必要はありません。

注記

プレビュー期間中は、セッションを保存する基盤となる Lakebase インスタンスに対して料金が請求されます。管理対象のエージェントセッション自体には、追加料金は発生しません。価格はプレビューの進行に伴い変更される可能性があります。

マネージドセッションを使用する場面：

  • エージェントの会話履歴を保持して、再起動後も残るようにし、後で再開できるようにします。
  • 後続のメッセージで完全なコンテキスト (ツール呼び出しと推論を含む) を再構築します。
  • 独自の UI から、過去の会話のリスト表示、再開、Branch を行います。

マネージドセッションは、1回のインタラクションの状態（短期的なセッション内の状態）を保持します。会話を 跨いで 永続化する耐久性のある長期的なメモリには、マネージドエージェントメモリを使用します。

管理されたセッションの仕組み​

管理対象エージェントセッションのリソース階層：セッションストアには多くのセッションが含まれ、各セッションには多くの順序付けられたセッションアイテムが含まれます。

管理されたセッションには3つのレベルがあります：

  • セッションストア は、エージェントのセッションを格納するワークスペーススコープのコンテナです。ストアを作成すると、基盤となるLakebaseストレージが自動的にプロビジョニングされます。ワークスペース固有のsession_store_nameを選択します。

  • セッション は、ストア内の1つの永続的なインタラクション（通常は会話のスレッド）です。セッションは次の要素によって識別されます:

    • actor_id （必須）：セッションの所有者（エンドユーザーや別のエージェントなど）。1つのサブジェクトのすべてのセッションをグループ化するため、まとめて一覧表示およびフィルター処理できます。ユーザーごとのアプリを構築する場合は、各ユーザーのセッションがグループ化されたままになるように、actor_idをユーザーのID（アプリの認証から検証されたエンドユーザーIDなど）に設定します。信頼できるアプリケーションコンテキストから設定し、モデルやユーザーが提供した値からは絶対に設定しないでください。
    • session_id （オプション）：インタラクションに対して呼び出し元が選択したID。省略した場合は、サービスが生成します。
    • parent_session_id （オプション）: 分岐した会話を表現するために、セッションをフォーク元のセッションにリンクします。

  • セッションアイテム は、セッションの順序付けられた履歴における1つのエントリーです。各アイテムには、メッセージ、ツール呼び出し、ツール結果、推論ブロックなどの、難読化された JSON 互換の data 値が保持されます。Databricks は各アイテムに item_id と create_time を割り当てますが、その内容の検査や検証は行いません。アイテムは追加された後は変更できません。

このサービスは、セッション内のアイテムに対して決定論的な順序を維持し、セッションストアに対するすべての操作を承認します。

要件​

  • 以下の例で使用するMason （エージェント API 用の Databricks の Python クライアントおよび CLI）を使用するには、 Python 3.10 以降 が必要です。 Python を必要とせず、任意の言語から直接 REST API を呼び出すこともできます。

使い始める​

これらの例では、サポートエージェント用にマネージドセッションを設定します。セッションストアを作成し、1つの会話のセッションを起動し、会話のターンを追加し、その後のリクエストで履歴を読み戻します。プロジェクトに適したクライアントを選択します。

Masonは、エージェントAPI用のDatabricksのPythonクライアントおよびCLIです。Databricks SDKのWorkspaceClientで認証を行います。

  1. Mason のインストール：

    Bash
    pip install databricks-mason

  2. セッションストアを作成し、1 つの会話のセッションを開始します。actor_id は会話の所有者であり、オプションの session_id はこの会話を一意に識別します。

    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. エージェントのランの実行に伴って、会話のターンを追加します。各アイテムは、任意の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. 後続のリクエストで、セッションを再読み込みし、その完全な履歴を読み取ってコンテキストを再構築します。

    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")]

クライアントは、最も最近のアイテムの削除、セッションのアイテムのクリア、および会話の独立したコピーへのフォーク（オプションで特定のアイテムまで）もサポートしています。子セッションを持つセッションを削除するには、削除をカスケードするための強制オプションが必要です（例：session.delete(force=True)）。

マネージドセッションによるエージェントフレームワークのセッションのバックアップ​

OpenAI Agents SDKやClaude Agent SDKなどのエージェントフレームワークは、ランの起動時に会話履歴を読み込み、末尾に新しい項目を追加します。セッションストアはそのパターンに直接マッピングされます：

フレームワークの動作

セッション ストアの呼び出し

履歴を読み取る

list_items 時系列順 (order_by="create_time asc")

ターン項目の追加

append 新しいアイテム

最後のアイテムを元に戻す

pop 最新のアイテム

スレッドをクリアする

clear セッションのアイテム

フレームワークの動作

セッション ストアの呼び出し

履歴を読み取る

list_items 時系列順 (order_by="create_time asc")

ターン項目の追加

append 新しいアイテム

最後のアイテムを元に戻す

pop 最新のアイテム

スレッドをクリアする

clear セッションのアイテム

スコープとアクセス​

マネージド セッションでは、セッションのアイテムが不透明な JSON 互換の値として保存されます。サービスは、エージェントやフレームワークが追加した内容を解釈せずにそのまま永続化し、返します。このような状態をシリアル化するフレームワークではアイテムとして永続化できますが、ラン、チェックポイント、承認などの実行制御リソースがファーストクラスの概念として追加されるわけではありません。

セッションストアはワークスペーススコープであり、アクセスはストアレベルで許可されます。actor_id フィールドと metadata フィールドはグループ化とフィルタリングのみをサポートしており、アクセスの付与や制限は行いません。モデルまたはユーザーが提供した値ではなく、信頼できるアプリケーションコンテキストから actor_id を設定します。

エージェントの Service Principal などの別のプリンシパルにストアを使用させるには、ストアの権限付与操作（Mason の session_store.grant_permission(principal_id)）でアクセス権を付与します。

マネージドセッションとマネージドメモリは独立しています。セッションまたはセッション ストアを削除しても、メモリストアに保持されているメモリは削除されません。

次のステップ​

このページの見出し