What you will be able to do
- Describe the store, session, and item levels of managed agent sessions and the fields that identify a session
- Use the AgentKit SDK calls that append a multi-step agent's turns and rebuild its history in the right order
- Recognize what a session store does not provide (execution-control primitives, access control through actor_id) and how its lifecycle relates to memory
1.What a persisted session looks like
Managed agent sessions are a durable, framework-agnostic store for the state one interaction produces. Databricks stores that state in Lakebase and manages the storage, so you do not build or operate the database. The feature is in Beta. During the preview you are billed for the underlying Lakebase instance, with no additional charge for managed sessions themselves.
The store has three levels. A session store is the workspace-scoped container for an agent's sessions. Creating one provisions the backing Lakebase storage automatically, and you give it a workspace-unique session_store_name. A session is one durable interaction, usually a conversation thread. A session item is one entry in a session's ordered history: a message, tool call, tool result, or reasoning block, stored as an opaque JSON-compatible value. Databricks assigns each item an item_id and a create_time. It does not inspect or validate the contents. Items are immutable after they are appended, and the service keeps a deterministic order.
| Field | Required? | Purpose |
|---|---|---|
| actor_id | Required | Who the session belongs to, such as an end user or another agent. Groups one subject's sessions for listing and filtering |
| session_id | Optional | Caller-chosen ID for the interaction. The service generates one if omitted |
| parent_session_id | Optional | Links a session to the one it was forked from, to represent branched conversations |
Checkpoint 1 of 5· Check yourself
In a per-user app, where should the agent's code get the value for actor_id?
actor_id is required and groups a subject's sessions. The documentation says to set it from trusted application context, never from a value the model or user supplies. The service auto-generates session_id, not actor_id.
“Set it from trusted application context, never a model- or user-supplied value.”Source: docs.databricks.com
2.Appending steps and rebuilding context
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 fits that cycle directly, so persisting a multi-step agent's state means calling the store at those same two points. The AgentKit SDK, the Databricks Python client for agent APIs, wraps the REST API under /api/2.0/agents/session-stores. Other languages can call that REST API directly.
session = session_store.add(actor_id="customer-123", session_id="case-456")session.append_items( [ {"type": "message", "role": "user", "content": "I need help with my cluster."}, {"type": "message", "role": "assistant", "content": "Let's take a look."}, ])Newest first. The SDK's list_items defaults to newest-first and auto-pages. To replay a transcript in the order it happened, request chronological order explicitly with order_by="create_time asc".
Checkpoint 2 of 5· Fill the gap
Which value rebuilds the history in the order the agent produced it?
history = [item.data for item in session.list_items(order_by=" ? ")]list_items defaults to newest-first, so rebuilding the transcript needs chronological order, requested with create_time asc.
Source: docs.databricks.com| 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 |
Checkpoint 3 of 5· Put it in order
Put the documented support-agent setup in order
- 1.Read the history back on a later request
- 2.Append the conversation's turns as the agent runs
- 3.Start a session for one conversation
- 4.Create a session store
The store has to exist before a session can be added to it, and items are appended during the run so a later request can read them back.
“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”Source: docs.databricks.com
3.What the store does not do, and how it relates to memory
Choosing a session store for multi-step state also means knowing where it stops. It persists and returns whatever your agent or framework appends, without interpreting it. It does not add execution-control resources such as runs, checkpoints, or approvals as first-class concepts. If you need those, your framework has to serialize them and store them as items. Branching is supported: the clients can fork a conversation into an independent copy, optionally up to a specific item, and parent_session_id records which session a fork came from. Deleting a session that has child sessions requires a force option to cascade the delete.
Access is authorized at the store level, and stores are workspace-scoped. The actor_id and metadata fields support grouping and filtering only, so they do not decide who can read a session. To let another principal, such as the agent's service principal, use a store, grant it access with the store's grant-permission operation.
The session store is also independent of memory. Deleting a session or an entire session store does not delete anything retained in a memory store. That independence is what allows sessions to age out while distilled facts stay.
Checkpoint 4 of 5· Check yourself
A developer wants the agent's human-approval gates to be tracked as native objects in the managed session store. What does the documentation say?
Managed sessions do not model runs, checkpoints, or approvals natively. A framework can still persist such state by serializing it into items.
“It doesn't add execution-control resources such as runs, checkpoints, or approvals as first-class concepts”Source: docs.databricks.com
Checkpoint 5 of 5· Exam question
Which statement accurately describes Lakebase as it relates to storing durable agent state on Databricks?
Correct answer: A — It is a fully managed Postgres database with instant branching and native Unity Catalog integration
- A. Correct: Lakebase is documented as a fully managed Postgres database offering automatic scaling, instant branching, and native Unity Catalog integration, making it suitable as a durable state store for agents.
- B. Incorrect: an in-memory cache that discards state at session end describes an ephemeral scratchpad, which is the opposite of what Lakebase provides.
- C. Incorrect: a vector index for semantic search describes AI Search, a retrieval component, not Lakebase's transactional Postgres role.
- D. Incorrect: a prompt template library relates to system prompt design, not to durable state storage.
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.list_items returns a session's items in chronological order, so you can pass its output straight back to the model.Why is that wrong?
By default it returns the newest items first. Rebuilding context needs order_by="create_time asc".
Covered in Appending steps and rebuilding context
2.Setting actor_id on a session restricts who can access it.Why is that wrong?
Access is authorized at the store level. actor_id and metadata are used only for grouping and filtering.
Covered in What the store does not do, and how it relates to memory
3.Deleting a session store also removes the facts the agent saved to memory from those sessions.Why is that wrong?
The two stores are independent. Memory survives the deletion of sessions or session stores.
Covered in What the store does not do, and how it relates to memory
Practise it for real
Persist a multi-step agent conversation in a managed session store and rebuild its context the way a follow-up request would
1.Install the AgentKit SDK with pip install databricks-agentbricks, then create a client with AgentKitClient(WorkspaceClient())
Why: The AgentKit SDK is the Databricks Python client for agent APIs and authenticates through the Databricks SDK's WorkspaceClient
You should see: A client object you can use to reach session stores
2.Call client.session_stores.create("support-agent-sessions")
Why: Creating a store provisions its backing Lakebase storage automatically
You should see: A session store named support-agent-sessions
3.Call session_store.add(actor_id="customer-123", session_id="case-456")
Why: A session is one durable interaction, grouped by actor_id and identified by session_id
You should see: A session object for case-456
4.Call session.append_items with the user and assistant messages from the documentation example
Why: Appending as the agent runs is what moves state out of the prompt and into durable storage
You should see: The items are stored, each assigned an item_id and create_time
5.Reload with session_store.get("case-456") and build history from session.list_items(order_by="create_time asc")
Why: This reproduces how a follow-up request rebuilds full context
You should see: The appended items' data returned in chronological order
Stuck? Get a nudge
If the messages come back in reverse order, check that you passed order_by="create_time asc". The default is newest-first.
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Databricks stores it in Lakebase and manages the storage for you, so you don't build or operate the database.”
↩︎ What a persisted session looks like“Creating a store provisions the backing Lakebase storage automatically.”
↩︎ What a persisted session looks like“Items are immutable after they are appended.”
↩︎ What a persisted session looks like“read conversation history at the start of a run and append new items at the end”
↩︎ Appending steps and rebuilding context“list_items defaults to newest-first and auto-pages.”
↩︎ Appending steps and rebuilding context“a framework that serializes such state can persist it as items.”
↩︎ What the store does not do, and how it relates to memory“forking a conversation into an independent copy (optionally up to a specific item)”
↩︎ What the store does not do, and how it relates to memory“The actor_id and metadata fields support grouping and filtering only; they do not grant or restrict access.”
↩︎ What the store does not do, and how it relates to memory“Deleting a session or session store does not delete memory retained in a memory store.”
↩︎ What the store does not do, and how it relates to memory“list_items defaults to newest-first and auto-pages.”
↩︎ Exam trap 1“The actor_id and metadata fields support grouping and filtering only; they do not grant or restrict access.”
↩︎ Exam trap 2“Deleting a session or session store does not delete memory retained in a memory store.”
↩︎ Exam trap 3“Set it from trusted application context, never a model- or user-supplied value.”
↩︎ Checkpoint“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”
↩︎ Checkpoint“It doesn't add execution-control resources such as runs, checkpoints, or approvals as first-class concepts”
↩︎ Checkpoint - 2.
“Managed agent sessions store an agent's session state: the state an agent or framework keeps for one interaction.”
↩︎ What a persisted session looks like“deleting a session, or an entire session store, does not delete memory retained in a memory store.”
↩︎ What the store does not do, and how it relates to memory - 3.
“Use managed agent sessions for the conversation history store.”
↩︎ Appending steps and rebuilding context