Skip to main content
Last updated on

Managed agent sessions

Beta

This feature is in Beta.

Managed agent sessions give your agents a durable, framework-agnostic store for session state: the state an agent or framework keeps for one interaction. Most commonly this is the conversation history, the ordered transcript of messages, tool calls, and results that an agent reads at the start of a turn and appends to as it runs. It can also be any other state a framework persists for the interaction, such as a LangGraph graph. Databricks stores it in Lakebase and manages the storage for you, so you don't build or operate the database.

note

During the preview, you are billed for the underlying Lakebase instance that stores your sessions. No additional charges apply for managed agent sessions itself. Pricing is subject to change as the preview progresses.

Use managed sessions when you want to:

  • Persist an agent's conversation history so it survives restarts and can be resumed later.
  • Reconstruct full context (including tool calls and reasoning) on a follow-up message.
  • List, resume, and branch past conversations from your own UI.

Managed sessions hold the state of a single interaction (short-term, in-session state). For durable, long-term memory that persists across conversations, use managed agent memory.

How managed sessions work​

Managed agent sessions resource hierarchy: a session store contains many sessions, and each session contains many ordered session items.

Managed sessions have three levels:

  • A session store is the workspace-scoped container for an agent's sessions. Creating a store provisions the backing Lakebase storage automatically. You choose a workspace-unique session_store_name.
  • A session is one durable interaction (typically a conversation thread) within a store. A session is identified by:
    • actor_id (required): who the session belongs to, such as an end user or another agent. It groups all of one subject's sessions so you can list and filter them together. When you build a per-user app, set actor_id to the user's ID (for example, the verified end-user identity from your app's authentication) so each user's sessions stay grouped. Set it from trusted application context, never a model- or user-supplied value.
    • session_id (optional): a caller-chosen ID for the interaction. The service generates one when you omit it.
    • parent_session_id (optional): links a session to the one it was forked from, to represent branched conversations.
  • A session item is one entry in a session's ordered history. Each item holds an opaque, JSON-compatible data value, such as a message, tool call, tool result, or reasoning block. Databricks assigns each item an item_id and a create_time and does not inspect or validate its contents. Items are immutable after they are appended.

The service maintains a deterministic order for a session's items and authorizes every operation against the session store.

Requirements​

  • Python 3.10 or above, to use Mason (Databricks' Python client and CLI for agent APIs), which the examples below use. You can also call the REST API directly from any language, with no Python requirement.

Get started​

These examples set up managed sessions for a support agent: they create a session store, start a session for one conversation, append the conversation's turns, and read the history back on a later request. Choose the client that fits your project.

Mason is Databricks' Python client and CLI for agent APIs. It authenticates with the Databricks SDK's WorkspaceClient.

  1. Install Mason:

    Bash
    pip install databricks-mason

  2. Create a session store, then start a session for one conversation. actor_id is who the conversation belongs to; the optional session_id uniquely identifies this 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. Append the conversation's turns as the agent runs. Each item is any JSON-compatible value:

    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. On a follow-up request, reload the session and read its full history in order to rebuild context:

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

The clients also support removing the most recent item, clearing a session's items, and forking a conversation into an independent copy (optionally up to a specific item). Deleting a session that has child sessions requires a force option to cascade the deletion to them (for example, session.delete(force=True)).

Back an agent framework's session with managed sessions​

Agent frameworks such as the OpenAI Agents SDK and the Claude Agent SDK read conversation history at the start of a run and append new items at the end. The session store maps directly onto that pattern:

Framework operation

Session store call

Read history

list_items in chronological order (order_by="create_time asc")

Add turn items

append the new items

Undo last item

pop the most recent item

Clear the thread

clear the session's items

Framework operation

Session store call

Read history

list_items in chronological order (order_by="create_time asc")

Add turn items

append the new items

Undo last item

pop the most recent item

Clear the thread

clear the session's items

Scope and access​

Managed sessions store a session's items as opaque, JSON-compatible values: the service persists and returns whatever your agent or framework appends, without interpreting it. It doesn't add execution-control resources such as runs, checkpoints, or approvals as first-class concepts, though a framework that serializes such state can persist it as items.

Session stores are workspace-scoped, and access is authorized at the store level. The actor_id and metadata fields support grouping and filtering only; they do not grant or restrict access. Set the actor_id from trusted application context rather than a model- or user-supplied value.

To let another principal, such as your agent's service principal, use a store, grant it access with the store's grant-permission operation (session_store.grant_permission(principal_id) in Mason).

Managed sessions and managed memory are independent. Deleting a session or session store does not delete memory retained in a memory store.

Next steps​

On this page