sessions

Creates, updates, deletes, gets or lists a sessions resource.

Overview

Name	sessions
Type	Resource
Id	databricks_workspace.agentkit.sessions

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
name	string	Resource name in the form ``session-stores/{session_store_id}/sessions/{session_id}``.
actor_id	string	Opaque caller-provided identifier for the application actor associated with the session. This is application data and has no Databricks authentication or authorization semantics. Use the same value as the Managed Memory Entry ``actor_id`` when storing memories associated with this actor. Every session must set it. A child session must use the same value as its parent.
parent_session_id	string	Immediate parent session ID. Set only at creation for child sessions, immutable thereafter, and restricted to the same store.
root_session_id	string	Top-level session ID in the spawn tree. This equals ``session_id`` for a root or fork and is inherited transitively by child sessions.
session_id	string	Unique session ID. The service generates a UUID unless the caller supplies ``CreateSessionRequest.session_id``.
create_time	string (date-time)	Time when the session was created.
last_activity_time	string (date-time)	Time when the session's item history was last mutated.
metadata	object	Mutable caller-defined string labels.
update_time	string (date-time)	Time when session resource fields last changed.

list

Name	Datatype	Description
name	string	Resource name in the form ``session-stores/{session_store_id}/sessions/{session_id}``.
actor_id	string	Opaque caller-provided identifier for the application actor associated with the session. This is application data and has no Databricks authentication or authorization semantics. Use the same value as the Managed Memory Entry ``actor_id`` when storing memories associated with this actor. Every session must set it. A child session must use the same value as its parent.
parent_session_id	string	Immediate parent session ID. Set only at creation for child sessions, immutable thereafter, and restricted to the same store.
root_session_id	string	Top-level session ID in the spawn tree. This equals ``session_id`` for a root or fork and is inherited transitively by child sessions.
session_id	string	Unique session ID. The service generates a UUID unless the caller supplies ``CreateSessionRequest.session_id``.
create_time	string (date-time)	Time when the session was created.
last_activity_time	string (date-time)	Time when the session's item history was last mutated.
metadata	object	Mutable caller-defined string labels.
update_time	string (date-time)	Time when session resource fields last changed.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	session_store_id, session_id, deployment_name, workspace_domain		Gets a session by resource name.
list	select	session_store_id, deployment_name, workspace_domain	filter, order_by, page_size, page_token	Lists sessions within a session store.
create	insert	session_store_id, deployment_name, workspace_domain, actor_id	session_id	Creates a session within a session store.
update	update	session_store_id, session_id, update_mask, deployment_name, workspace_domain, actor_id		Updates a session's mutable fields.
delete	delete	session_store_id, session_id, deployment_name, workspace_domain		Deletes a session, its items, and any descendant sessions recursively. Independently retained memory
extract_memories	exec	session_store_id, session_id, deployment_name, workspace_domain, memory_store		Synchronously extracts memories from a single session into the given memory store, returning the
fork	exec	session_store_id, deployment_name, workspace_domain, source_session_id, actor_id		Forks a session into an independent top-level copy.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
deployment_name	string	The Databricks workspace deployment name: the host prefix of the workspace URL (dbc-abcd0123-a1bc on AWS, adb-1234567890123456.7 on Azure, 1234567890123456.7 on GCP). Set DATABRICKS_DEPLOYMENT_NAME to default it for the session. (default: dbc-abcd0123-a1bc, x-stackQL-envVar: DATABRICKS_DEPLOYMENT_NAME)
session_id	string	Identifier of the session whose transcript is distilled into memories.
session_store_id	string	The session_store_id segment of the parent resource name (session-stores/{session_store_id}). Resource name of the containing session store, in the form session-stores/{session_store_id}.
update_mask	object	Fields to update. Only metadata is mutable; any other path returns INVALID_PARAMETER_VALUE.
workspace_domain	string	The Databricks workspace domain suffix for the cloud. Selected by DATABRICKS_CLOUD (aws, azure or gcp; default aws). (default: cloud.databricks.com, x-stackQL-envVarSelector: {"envVar":"DATABRICKS_CLOUD","default":"aws","values":{"aws":"cloud.databricks.com","azure":"azuredatabricks.net","gcp":"gcp.databricks.com"}})
filter	string	Filter expression. Supported fields include actor_id and metadata; for example, actor_id = "support-customer-123".
order_by	string	Sort order. Defaults to last_activity_time desc. Page-token continuation is exactly-once when ordering by create_time (immutable); ordering by last_activity_time is best-effort, because that value changes as a session gains activity, so a session updated between page requests may be repeated or skipped. To enumerate every session exactly once, order by create_time.
page_size	integer	Maximum number of sessions to return. Defaults to 10; must be between 1 and 100.
page_token	string	Token returned by a previous list request.
session_id	string	Optional caller-selected session ID. The service generates a UUID when this field is omitted. The ID must be unique; a collision returns ALREADY_EXISTS.

SELECT examples

get

Gets a session by resource name.

SELECT
name,
actor_id,
parent_session_id,
root_session_id,
session_id,
create_time,
last_activity_time,
metadata,
update_time
FROM databricks_workspace.agentkit.sessions
WHERE session_store_id = '{{ session_store_id }}' -- required
AND session_id = '{{ session_id }}' -- required
AND deployment_name = '{{ deployment_name }}' -- required
AND workspace_domain = '{{ workspace_domain }}' -- required
;

list

Lists sessions within a session store.

SELECT
name,
actor_id,
parent_session_id,
root_session_id,
session_id,
create_time,
last_activity_time,
metadata,
update_time
FROM databricks_workspace.agentkit.sessions
WHERE session_store_id = '{{ session_store_id }}' -- required
AND deployment_name = '{{ deployment_name }}' -- required
AND workspace_domain = '{{ workspace_domain }}' -- required
AND filter = '{{ filter }}'
AND order_by = '{{ order_by }}'
AND page_size = '{{ page_size }}'
AND page_token = '{{ page_token }}'
;

INSERT examples

create

Creates a session within a session store.

INSERT INTO databricks_workspace.agentkit.sessions (
actor_id,
create_time,
last_activity_time,
metadata,
name,
parent_session_id,
root_session_id,
session_id,
update_time,
session_store_id,
deployment_name,
workspace_domain,
session_id
)
SELECT 
'{{ actor_id }}' /* required */,
'{{ create_time }}',
'{{ last_activity_time }}',
'{{ metadata }}',
'{{ name }}',
'{{ parent_session_id }}',
'{{ root_session_id }}',
'{{ session_id }}',
'{{ update_time }}',
'{{ session_store_id }}',
'{{ deployment_name }}',
'{{ workspace_domain }}',
'{{ session_id }}'
RETURNING
name,
actor_id,
parent_session_id,
root_session_id,
session_id,
create_time,
last_activity_time,
metadata,
update_time
;

Manifest

# Description fields are for documentation purposes
- name: sessions
props:
  - name: session_store_id
    value: "{{ session_store_id }}"
    description: Required parameter for the sessions resource.
  - name: deployment_name
    value: "{{ deployment_name }}"
    description: Required parameter for the sessions resource.
  - name: workspace_domain
    value: "{{ workspace_domain }}"
    description: Required parameter for the sessions resource.
  - name: actor_id
    value: "{{ actor_id }}"
    description: |
      Opaque caller-provided identifier for the application actor associated with the session. This is application data and has no Databricks authentication or authorization semantics. Use the same value as the Managed Memory Entry ``actor_id`` when storing memories associated with this actor. Every session must set it. A child session must use the same value as its parent.
  - name: create_time
    value: "{{ create_time }}"
    description: |
      Time when the session was created.
  - name: last_activity_time
    value: "{{ last_activity_time }}"
    description: |
      Time when the session's item history was last mutated.
  - name: metadata
    value: "{{ metadata }}"
    description: |
      Mutable caller-defined string labels.
  - name: name
    value: "{{ name }}"
    description: |
      Resource name in the form ``session-stores/{session_store_id}/sessions/{session_id}``.
  - name: parent_session_id
    value: "{{ parent_session_id }}"
    description: |
      Immediate parent session ID. Set only at creation for child sessions, immutable thereafter, and restricted to the same store.
  - name: root_session_id
    value: "{{ root_session_id }}"
    description: |
      Top-level session ID in the spawn tree. This equals ``session_id`` for a root or fork and is inherited transitively by child sessions.
  - name: session_id
    value: "{{ session_id }}"
    description: |
      Unique session ID. The service generates a UUID unless the caller supplies ``CreateSessionRequest.session_id``.
  - name: update_time
    value: "{{ update_time }}"
    description: |
      Time when session resource fields last changed.
  - name: session_id
    value: "{{ session_id }}"
    description: Optional caller-selected session ID. The service generates a UUID when this field is omitted. The ID must be unique; a collision returns ``ALREADY_EXISTS``.
    description: Optional caller-selected session ID. The service generates a UUID when this field is omitted. The ID must be unique; a collision returns ``ALREADY_EXISTS``.

UPDATE examples

update

Updates a session's mutable fields.

UPDATE databricks_workspace.agentkit.sessions
SET 
actor_id = '{{ actor_id }}',
create_time = '{{ create_time }}',
last_activity_time = '{{ last_activity_time }}',
metadata = '{{ metadata }}',
name = '{{ name }}',
parent_session_id = '{{ parent_session_id }}',
root_session_id = '{{ root_session_id }}',
session_id = '{{ session_id }}',
update_time = '{{ update_time }}'
WHERE 
session_store_id = '{{ session_store_id }}' --required
AND session_id = '{{ session_id }}' --required
AND update_mask = '{{ update_mask }}' --required
AND deployment_name = '{{ deployment_name }}' --required
AND workspace_domain = '{{ workspace_domain }}' --required
AND actor_id = '{{ actor_id }}' --required
RETURNING
name,
actor_id,
parent_session_id,
root_session_id,
session_id,
create_time,
last_activity_time,
metadata,
update_time;

DELETE examples

delete

Deletes a session, its items, and any descendant sessions recursively. Independently retained memory

DELETE FROM databricks_workspace.agentkit.sessions
WHERE session_store_id = '{{ session_store_id }}' --required
AND session_id = '{{ session_id }}' --required
AND deployment_name = '{{ deployment_name }}' --required
AND workspace_domain = '{{ workspace_domain }}' --required
;

Lifecycle Methods

extract_memories

Synchronously extracts memories from a single session into the given memory store, returning the

EXEC databricks_workspace.agentkit.sessions.extract_memories 
@session_store_id='{{ session_store_id }}' --required, 
@session_id='{{ session_id }}' --required, 
@deployment_name='{{ deployment_name }}' --required, 
@workspace_domain='{{ workspace_domain }}' --required 
@@json=
'{
"memory_store": "{{ memory_store }}", 
"dry_run": {{ dry_run }}, 
"instructions": "{{ instructions }}"
}'
;

fork

Forks a session into an independent top-level copy.

EXEC databricks_workspace.agentkit.sessions.fork 
@session_store_id='{{ session_store_id }}' --required, 
@deployment_name='{{ deployment_name }}' --required, 
@workspace_domain='{{ workspace_domain }}' --required 
@@json=
'{
"source_session_id": "{{ source_session_id }}", 
"actor_id": "{{ actor_id }}", 
"metadata": "{{ metadata }}", 
"session_id": "{{ session_id }}", 
"up_to_item_id": "{{ up_to_item_id }}"
}'
;