Session

View as Markdown

A durable logical interaction stored within a Session Store.

Get a sessionGET /api/2.0/agents/{name=session-stores/*/sessions/*}List sessionsGET /api/2.0/agents/{parent=session-stores/*}/sessionsCreate a sessionPOST /api/2.0/agents/{parent=session-stores/*}/sessionsUpdate a sessionPATCH /api/2.0/agents/{name=session-stores/*/sessions/*}Delete a sessionDELETE /api/2.0/agents/{name=session-stores/*/sessions/*}Fork a sessionPOST /api/2.0/agents/{parent=session-stores/*}/sessions:forkList session itemsGET /api/2.0/agents/{parent=session-stores/*/sessions/*}/itemsAppend items to a sessionPOST /api/2.0/agents/{parent=session-stores/*/sessions/*}/items:appendPop an item from a sessionPOST /api/2.0/agents/{parent=session-stores/*/sessions/*}/items:popClear items from a sessionPOST /api/2.0/agents/{parent=session-stores/*/sessions/*}/items:clearExtract memories from a sessionPOST /api/2.0/agents/{session_store=session-stores/*}/sessions/{session_id}/extractions

Session object

A durable logical interaction stored within a Session Store.

session_idstringBetaOutput only

Unique session ID. The service generates a UUID unless the caller supplies CreateSessionRequest.session_id.

actor_idstringBetaImmutable

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_idstringBetaImmutable

Immediate parent session ID. Set only at creation for child sessions, immutable thereafter, and restricted to the same store.

root_session_idstringBetaOutput only

Top-level session ID in the spawn tree. This equals session_id for a root or fork and is inherited transitively by child sessions.

metadataobjectBeta

Mutable caller-defined string labels.

create_timestringBetaOutput only

Time when the session was created.

update_timestringBetaOutput only

Time when session resource fields last changed.

last_activity_timestringBetaOutput only

Time when the session's item history was last mutated.

namestringBetaOutput onlyIDImmutable

Resource name in the form session-stores/{session_store_id}/sessions/{session_id}.

View as Markdown

The Session object

{
  "session_id": "string",
  "actor_id": "string",
  "parent_session_id": "string",
  "root_session_id": "string",
  "metadata": {},
  "create_time": "string",
  "update_time": "string",
  "last_activity_time": "string",
  "name": "string"
}

Get a session Beta

GET /api/2.0/agents/{name=session-stores/*/sessions/*}

Gets a session by resource name.

API scopes: agent-kit

Parameters

namestringRequiredpath

Resource name in the form session-stores/{session_store_id}/sessions/{session_id}.

Response

Returns the Session object.

View as Markdown

Response

{
  "session_id": "string",
  "actor_id": "string",
  "parent_session_id": "string",
  "root_session_id": "string",
  "metadata": {},
  "create_time": "string",
  "update_time": "string",
  "last_activity_time": "string",
  "name": "string"
}

List sessions Beta

GET /api/2.0/agents/{parent=session-stores/*}/sessions

Lists sessions within a session store.

API scopes: agent-kit

Parameters

parentstringRequiredpath

Resource name of the containing session store, in the form session-stores/{session_store_id}.

page_sizeint32query

Maximum number of sessions to return. Defaults to 10; must be between 1 and 100.

page_tokenstringquery

Token returned by a previous list request.

filterstringquery

Filter expression. Supported fields include actor_id and metadata; for example, actor_id = "support-customer-123".

order_bystringquery

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.

Response

Returns a list of Session objects.

View as Markdown

Response

{
  "sessions": [
    {
      "session_id": "string",
      "actor_id": "string",
      "parent_session_id": "string",
      "root_session_id": "string",
      "metadata": {},
      "create_time": "string",
      "update_time": "string",
      "last_activity_time": "string",
      "name": "string"
    }
  ],
  "next_page_token": "string"
}

Create a session Beta

POST /api/2.0/agents/{parent=session-stores/*}/sessions

Creates a session within a session store.

API scopes: agent-kit

Parameters

parentstringRequiredpath

Resource name of the containing session store, in the form session-stores/{session_store_id}.

session_idstringquery

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.

Request body

The session to create. actor_id is required. A session with parent_session_id is a child and must use its parent's actor_id. Independent forks are created only through ForkSession.

actor_idstringRequiredImmutable

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_idstringImmutable

Immediate parent session ID. Set only at creation for child sessions, immutable thereafter, and restricted to the same store.

metadataobject

Mutable caller-defined string labels.

Response

Returns the Session object.

View as Markdown

Request

{
  "actor_id": "string",
  "parent_session_id": "string",
  "metadata": {}
}

Response

{
  "session_id": "string",
  "actor_id": "string",
  "parent_session_id": "string",
  "root_session_id": "string",
  "metadata": {},
  "create_time": "string",
  "update_time": "string",
  "last_activity_time": "string",
  "name": "string"
}

Update a session Beta

PATCH /api/2.0/agents/{name=session-stores/*/sessions/*}

Updates a session's mutable fields.

API scopes: agent-kit

Parameters

namestringRequiredIDImmutablepath

Resource name in the form session-stores/{session_store_id}/sessions/{session_id}.

update_maskstringRequiredquery

Fields to update. Only metadata is mutable; any other path returns INVALID_PARAMETER_VALUE.

Request body

Session to update.

actor_idstringRequiredImmutable

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_idstringImmutable

Immediate parent session ID. Set only at creation for child sessions, immutable thereafter, and restricted to the same store.

metadataobject

Mutable caller-defined string labels.

Response

Returns the Session object.

View as Markdown

Request

{
  "actor_id": "string",
  "parent_session_id": "string",
  "metadata": {}
}

Response

{
  "session_id": "string",
  "actor_id": "string",
  "parent_session_id": "string",
  "root_session_id": "string",
  "metadata": {},
  "create_time": "string",
  "update_time": "string",
  "last_activity_time": "string",
  "name": "string"
}

Delete a session Beta

DELETE /api/2.0/agents/{name=session-stores/*/sessions/*}

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

API scopes: agent-kit

Parameters

namestringRequiredpath

Resource name in the form session-stores/{session_store_id}/sessions/{session_id}.

View as Markdown

Response

{}

Fork a session Beta

POST /api/2.0/agents/{parent=session-stores/*}/sessions:fork

Forks a session into an independent top-level copy.

API scopes: agent-kit

Parameters

parentstringRequiredpath

Resource name of the containing session store, in the form session-stores/{session_store_id}.

Request body

source_session_idstringRequired

ID of the session to copy.

up_to_item_idstring

Optional last item ID to copy through, inclusively. When omitted, the fork atomically copies all items committed before the fork operation begins.

session_idstring

Optional unique ID for the forked session. A collision returns ALREADY_EXISTS.

actor_idstringRequired

Opaque caller-provided identifier for the application actor associated with the forked session.

metadataobject

Optional metadata for the fork.

Response

sessionobject

The newly-created independent top-level session.

Show child attributesHide child attributes

session_idstringOutput only

Unique session ID. The service generates a UUID unless the caller supplies CreateSessionRequest.session_id.

actor_idstringRequiredImmutable

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_idstringImmutable

Immediate parent session ID. Set only at creation for child sessions, immutable thereafter, and restricted to the same store.

root_session_idstringOutput only

Top-level session ID in the spawn tree. This equals session_id for a root or fork and is inherited transitively by child sessions.

metadataobject

Mutable caller-defined string labels.

create_timestringOutput only

Time when the session was created.

update_timestringOutput only

Time when session resource fields last changed.

last_activity_timestringOutput only

Time when the session's item history was last mutated.

namestringOutput onlyIDImmutable

Resource name in the form session-stores/{session_store_id}/sessions/{session_id}.

View as Markdown

Request

{
  "source_session_id": "string",
  "up_to_item_id": "string",
  "session_id": "string",
  "actor_id": "string",
  "metadata": {}
}

Response

{
  "session": {
    "session_id": "string",
    "actor_id": "string",
    "parent_session_id": "string",
    "root_session_id": "string",
    "metadata": {},
    "create_time": "string",
    "update_time": "string",
    "last_activity_time": "string",
    "name": "string"
  }
}

List session items Beta

GET /api/2.0/agents/{parent=session-stores/*/sessions/*}/items

Lists items in a session.

API scopes: agent-kit

Parameters

parentstringRequiredpath

Resource name of the containing session, in the form session-stores/{session_store_id}/sessions/{session_id}.

page_sizeint32query

Maximum number of items to return. Defaults to 10; must be between 1 and 100.

page_tokenstringquery

Token returned by a previous list request.

order_bystringquery

Sort order. Supported values are create_time asc and create_time desc. The default is create_time desc, which returns the most recently appended items first. Equal timestamps are resolved by committed append order in the requested direction.

Response

session_itemsarray of object

Session items in the requested page.

Show child attributesHide child attributes

item_idstringOutput only

Stable service-generated item ID.

dataobjectRequired

Complete SDK-native, JSON-compatible item. The service stores and returns this value without interpreting provider-specific fields such as type, role, or content.

create_timestringOutput only

Server-assigned time when the append commits. Values are nondecreasing within a session. Item listing orders by this timestamp; equal timestamps are resolved by committed append order.

next_page_tokenstring

Token to retrieve the next page.

View as Markdown

Response

{
  "session_items": [
    {
      "item_id": "string",
      "data": {},
      "create_time": "string"
    }
  ],
  "next_page_token": "string"
}

Append items to a session Beta

POST /api/2.0/agents/{parent=session-stores/*/sessions/*}/items:append

Appends items to a session.

API scopes: agent-kit

Parameters

parentstringRequiredpath

Resource name of the containing session, in the form session-stores/{session_store_id}/sessions/{session_id}.

Request body

itemsarray of objectRequired

Items to append atomically in request order. Concurrent append requests are serialized into one committed order without exposing a numeric sequence in the public contract.

Show child attributesHide child attributes

dataobjectRequired

Complete SDK-native, JSON-compatible item. The service stores and returns this value without interpreting provider-specific fields such as type, role, or content.

Response

session_itemsarray of object

Persisted session items with service-assigned fields.

Show child attributesHide child attributes

item_idstringOutput only

Stable service-generated item ID.

dataobjectRequired

Complete SDK-native, JSON-compatible item. The service stores and returns this value without interpreting provider-specific fields such as type, role, or content.

create_timestringOutput only

Server-assigned time when the append commits. Values are nondecreasing within a session. Item listing orders by this timestamp; equal timestamps are resolved by committed append order.

View as Markdown

Request

{
  "items": [
    {
      "data": {}
    }
  ]
}

Response

{
  "session_items": [
    {
      "item_id": "string",
      "data": {},
      "create_time": "string"
    }
  ]
}

Pop an item from a session Beta

POST /api/2.0/agents/{parent=session-stores/*/sessions/*}/items:pop

Pops the newest item from a session.

API scopes: agent-kit

Parameters

parentstringRequiredpath

Resource name of the containing session, in the form session-stores/{session_store_id}/sessions/{session_id}.

Response

itemobject

Removed item, if any.

Show child attributesHide child attributes

item_idstringOutput only

Stable service-generated item ID.

dataobjectRequired

Complete SDK-native, JSON-compatible item. The service stores and returns this value without interpreting provider-specific fields such as type, role, or content.

create_timestringOutput only

Server-assigned time when the append commits. Values are nondecreasing within a session. Item listing orders by this timestamp; equal timestamps are resolved by committed append order.

View as Markdown

Response

{
  "item": {
    "item_id": "string",
    "data": {},
    "create_time": "string"
  }
}

Clear items from a session Beta

POST /api/2.0/agents/{parent=session-stores/*/sessions/*}/items:clear

Clears all items from a session.

API scopes: agent-kit

Parameters

parentstringRequiredpath

Resource name of the containing session, in the form session-stores/{session_store_id}/sessions/{session_id}.

View as Markdown

Response

{}

Extract memories from a session Beta

POST /api/2.0/agents/{session_store=session-stores/*}/sessions/{session_id}/extractions

Synchronously extracts memories from a single session into the given memory store, returning the entries that were written.

API scopes: agent-kit

Parameters

session_storestringRequiredpath

Session store containing the session, in the form session-stores/{session_store_id}.

session_idstringRequiredpath

Identifier of the session whose transcript is distilled into memories.

Request body

memory_storestringRequired

Managed memory store the extracted entries are written to, in the form memory-stores/{managed_memory_store_id}.

instructionsstring

Instructions steering what is extracted from the session.

dry_runboolean

When true, extract and return the entries without writing them to the memory store. Defaults to false, which persists the extracted entries and returns them.

Response

namestringOutput only

Correlation identifier for this extraction, for logging and tracing. Not a fetchable resource.

entriesarray of objectOutput only

The memory entries written by this extraction.

Show child attributesHide child attributes

namestringOutput onlyIDImmutable

Resource name in the form memory-stores/{managed_memory_store_id}/entries/{managed_memory_entry_id}.

actor_idstringRequiredImmutable

Customer-provided identifier for the actor whose memory this entry represents.

session_idstringImmutable

Optional identifier for the session associated with this memory entry. When omitted, the entry applies across the actor's sessions.

pathstringRequiredImmutable

Absolute, case-sensitive path identifying the entry within its actor and optional session. Paths must begin with / and must not contain empty, . or .. segments.

contentstring

Optional free-form memory content.

descriptionstring

Human-readable description of the memory entry.

source_typestringImmutable

Which writer created this entry. Caller sets this on Create; immutable after creation.

Values:

• MANAGED_MEMORY_ENTRY_SOURCE_TYPE_AGENT
• MANAGED_MEMORY_ENTRY_SOURCE_TYPE_DREAMER

create_timestringOutput only

Time when the entry was created.

update_timestringOutput only

Time when the entry was last updated.

View as Markdown

Request

{
  "memory_store": "string",
  "instructions": "string",
  "dry_run": true
}

Response

{
  "name": "string",
  "entries": [
    {
      "name": "string",
      "actor_id": "string",
      "session_id": "string",
      "path": "string",
      "content": "string",
      "description": "string",
      "source_type": "MANAGED_MEMORY_ENTRY_SOURCE_TYPE_AGENT",
      "create_time": "string",
      "update_time": "string"
    }
  ]
}