w.agent_kit: AgentKit.v1

class databricks.sdk.service.agentkit.AgentKitAPI

APIs for managing agent memory and durable session state. This interface is under active development and may change.

append_session_items(parent: str, items: List[SessionItem]) → AppendSessionItemsResponse

Appends items to a session.

Parameters:

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

  • items – List[SessionItem] 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.

Returns:

AppendSessionItemsResponse

clear_session_items(parent: str) → ClearSessionItemsResponse

Clears all items from a session.

Parameters:

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

Returns:

ClearSessionItemsResponse

create_memory(parent: str, managed_memory_entry: ManagedMemoryEntry [, managed_memory_entry_id: Optional[str]]) → ManagedMemoryEntry

Creates a memory entry using exclusive-create semantics. Callers may choose the entry ID; the service generates one when it is omitted. Returns ALREADY_EXISTS when an entry with the same actor, session, and path already exists. Omitted session_id is its own uniqueness key: two omitted-session entries with the same actor and path conflict, but an omitted-session entry does not conflict with a session-scoped entry at the same actor and path.

Parameters:

  • parent – str Memory store that will contain the entry, in the form memory-stores/{managed_memory_store_id}.

  • managed_memory_entry – ManagedMemoryEntry The memory entry to create.

  • managed_memory_entry_id – str (optional) Optional caller-selected memory entry ID. The service generates an ID when omitted.

Returns:

ManagedMemoryEntry

create_memory_store(managed_memory_store: ManagedMemoryStore, managed_memory_store_id: str) → ManagedMemoryStore

Creates a memory store in the caller’s workspace.

Parameters:

  • managed_memory_store – ManagedMemoryStore The memory store to create.

  • managed_memory_store_id – str Caller-provided, workspace-unique memory store ID. It must be 3-56 characters, begin with a lowercase letter, contain only lowercase letters, digits, and hyphens, and end with a letter or digit.

Returns:

ManagedMemoryStore

create_session(parent: str, session: Session [, session_id: Optional[str]]) → Session

Creates a session within a session store.

Parameters:

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

  • session – Session 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.

  • session_id – str (optional) 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.

Returns:

Session

create_session_store(session_store: SessionStore, session_store_id: str) → SessionStore

Creates a session store.

Parameters:

  • session_store – SessionStore The session store to create.

  • session_store_id – str Caller-provided, workspace-unique session store ID. It must be 3-55 characters, begin with a lowercase letter, and contain only lowercase letters, digits, and hyphens.

Returns:

SessionStore

delete_memory(name: str)

Deletes a memory entry by resource name. Returns NOT_FOUND when the entry does not exist in the caller’s workspace.

Parameters:

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

delete_memory_store(name: str)

Deletes a memory store by resource name. Returns NOT_FOUND when the store does not exist in the caller’s workspace.

Parameters:

name – str Resource name in the form memory-stores/{managed_memory_store_id}.

delete_session(name: str)

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

Parameters:

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

delete_session_store(name: str)

Deletes a session store, its sessions and items, and its service-managed storage. Memory entries retained by a separate Memory Store are not deleted.

Parameters:

name – str Resource name in the form session-stores/{session_store_id}.

extract_memories(session_store: str, session_id: str, memory_store: str [, dry_run: Optional[bool], instructions: Optional[str]]) → ExtractMemoriesResponse

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

Parameters:

  • session_store – str Session store containing the session, in the form session-stores/{session_store_id}.

  • session_id – str Identifier of the session whose transcript is distilled into memories.

  • memory_store – str Memory store the extracted entries are written to, in the form memory-stores/{managed_memory_store_id}.

  • dry_run – bool (optional) 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.

  • instructions – str (optional) Instructions steering what is extracted from the session.

Returns:

ExtractMemoriesResponse

fork_session(parent: str, source_session_id: str, actor_id: str [, metadata: Optional[Dict[str, str]], session_id: Optional[str], up_to_item_id: Optional[str]]) → ForkSessionResponse

Forks a session into an independent top-level copy.

Parameters:

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

  • source_session_id – str ID of the session to copy.

  • actor_id – str Opaque caller-provided identifier for the application actor associated with the forked session.

  • metadata – Dict[str,str] (optional) Optional metadata for the fork.

  • session_id – str (optional) Optional unique ID for the forked session. A collision returns ALREADY_EXISTS.

  • up_to_item_id – str (optional) Optional last item ID to copy through, inclusively. When omitted, the fork atomically copies all items committed before the fork operation begins.

Returns:

ForkSessionResponse

get_memory(name: str [, view: Optional[ManagedMemoryEntryView]]) → ManagedMemoryEntry

Retrieves a memory entry by resource name. view controls whether the response includes memory content. Returns NOT_FOUND when the entry does not exist in the caller’s workspace.

Parameters:

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

  • view – ManagedMemoryEntryView (optional) Controls whether the response includes memory content. Defaults to FULL.

Returns:

ManagedMemoryEntry

get_memory_store(name: str) → ManagedMemoryStore

Retrieves a memory store by resource name. Returns NOT_FOUND when the store does not exist in the caller’s workspace.

Parameters:

name – str Resource name in the form memory-stores/{managed_memory_store_id}.

Returns:

ManagedMemoryStore

get_memory_store_permission(name: str) → MemoryStorePermission

Retrieves the current caller’s effective memory store permission. Returns PERMISSION_LEVEL_UNSPECIFIED when the caller has no access.

Parameters:

name – str Resource name in the form memory-stores/{managed_memory_store_id}.

Returns:

MemoryStorePermission

get_session(name: str) → Session

Gets a session by resource name.

Parameters:

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

Returns:

Session

get_session_store(name: str) → SessionStore

Gets a session store by resource name.

Parameters:

name – str Resource name in the form session-stores/{session_store_id}.

Returns:

SessionStore

get_session_store_permission(name: str) → SessionStorePermission

Retrieves the current caller’s effective session store permission. Returns PERMISSION_LEVEL_UNSPECIFIED when the caller has no access.

Parameters:

name – str Resource name in the form session-stores/{session_store_id}.

Returns:

SessionStorePermission

grant_memory_store_permission(name: str, principal: StorePrincipal, permission: PermissionLevel) → GrantMemoryStorePermissionResponse

Grants a READ or WRITE permission on a memory store to a principal. Only the owner or a workspace admin may grant permissions.

Parameters:

  • name – str Resource name in the form memory-stores/{managed_memory_store_id}.

  • principal – StorePrincipal Principal to grant the permission to.

  • permission – PermissionLevel Permission level to grant.

Returns:

GrantMemoryStorePermissionResponse

grant_session_store_permission(name: str, principal: StorePrincipal, permission: PermissionLevel) → GrantSessionStorePermissionResponse

Grants a READ or WRITE permission on a session store to a principal. Only the owner or a workspace admin may grant permissions.

Parameters:

  • name – str Resource name in the form session-stores/{session_store_id}.

  • principal – StorePrincipal Principal to grant the permission to.

  • permission – PermissionLevel Permission level to grant.

Returns:

GrantSessionStorePermissionResponse

list_memories(parent: str, actor_id: str [, page_size: Optional[int], page_token: Optional[str], path_prefix: Optional[str], session_id: Optional[str], view: Optional[ManagedMemoryEntryView]]) → Iterator[ManagedMemoryEntry]

Lists memory entries for one actor. An exact path filters entries across sessions, ignoring session metadata. Otherwise, session_id and path_prefix restrict the actor partition. view controls whether each returned entry includes memory content.

Parameters:

  • parent – str Memory store whose entries are listed, in the form memory-stores/{managed_memory_store_id}.

  • actor_id – str Customer-provided identifier for the actor whose entries are listed.

  • page_size – int (optional) Maximum number of entries to return. The service may return fewer entries than requested. Defaults to 10; must be between 1 and 100.

  • page_token – str (optional) Opaque pagination token from a previous ListManagedMemoryEntries response.

  • path_prefix – str (optional) Optional path prefix used to restrict entries within the actor partition.

  • session_id – str (optional) Optional session identifier. When set, only entries with this exact session_id are returned. Omitted-session (cross-session) entries are not included. Ignored when path is set.

  • view – ManagedMemoryEntryView (optional) Controls whether each returned entry includes memory content. Defaults to FULL.

Returns:

Iterator over ManagedMemoryEntry

list_memory_store_permissions(parent: str [, page_size: Optional[int], page_token: Optional[str]]) → Iterator[MemoryStorePermission]

Lists explicit memory store grants. Only the owner or a workspace admin may list permissions.

Parameters:

  • parent – str Resource name of the store, in the form memory-stores/{managed_memory_store_id}.

  • page_size – int (optional) Maximum number of permissions to return. Defaults to 100; maximum is 1000.

  • page_token – str (optional) Continuation token from a previous response.

Returns:

Iterator over MemoryStorePermission

list_memory_stores([, page_size: Optional[int], page_token: Optional[str]]) → Iterator[ManagedMemoryStore]

Lists memory stores in the caller’s workspace.

Parameters:

  • page_size – int (optional) Maximum number of stores to return. The service may return fewer stores than requested. Defaults to 10; must be between 1 and 100.

  • page_token – str (optional) Opaque pagination token from a previous ListManagedMemoryStores response.

Returns:

Iterator over ManagedMemoryStore

list_session_items(parent: str [, order_by: Optional[str], page_size: Optional[int], page_token: Optional[str]]) → Iterator[SessionItem]

Lists items in a session.

Parameters:

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

  • order_by – str (optional) 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.

  • page_size – int (optional) Maximum number of items to return. Defaults to 10; must be between 1 and 100.

  • page_token – str (optional) Token returned by a previous list request.

Returns:

Iterator over SessionItem

list_session_store_permissions(parent: str [, page_size: Optional[int], page_token: Optional[str]]) → Iterator[SessionStorePermission]

Lists explicit session store grants. Only the owner or a workspace admin may list permissions.

Parameters:

  • parent – str Resource name of the store, in the form session-stores/{session_store_id}.

  • page_size – int (optional) Maximum number of permissions to return. Defaults to 100; maximum is 1000.

  • page_token – str (optional) Continuation token from a previous response.

Returns:

Iterator over SessionStorePermission

list_session_stores([, page_size: Optional[int], page_token: Optional[str]]) → Iterator[SessionStore]

Lists session stores.

Parameters:

  • page_size – int (optional) Maximum number of session stores to return. Defaults to 10; must be between 1 and 100.

  • page_token – str (optional) Token returned by a previous list request.

Returns:

Iterator over SessionStore

list_sessions(parent: str [, filter: Optional[str], order_by: Optional[str], page_size: Optional[int], page_token: Optional[str]]) → Iterator[Session]

Lists sessions within a session store.

Parameters:

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

  • filter – str (optional) Filter expression. Supported fields include actor_id and metadata; for example, actor_id = "support-customer-123".

  • order_by – str (optional) 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 – int (optional) Maximum number of sessions to return. Defaults to 10; must be between 1 and 100.

  • page_token – str (optional) Token returned by a previous list request.

Returns:

Iterator over Session

pop_session_item(parent: str) → PopSessionItemResponse

Pops the newest item from a session.

Parameters:

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

Returns:

PopSessionItemResponse

revoke_memory_store_permission(name: str, principal: StorePrincipal) → RevokeMemoryStorePermissionResponse

Removes a principal’s explicit READ and WRITE grants on a memory store. Only the owner or a workspace admin may revoke permissions. Ownership and inherited access are unaffected.

Parameters:

  • name – str Resource name in the form memory-stores/{managed_memory_store_id}.

  • principal – StorePrincipal Principal whose READ and WRITE grants will be removed.

Returns:

RevokeMemoryStorePermissionResponse

revoke_session_store_permission(name: str, principal: StorePrincipal) → RevokeSessionStorePermissionResponse

Removes a principal’s explicit READ and WRITE grants on a session store. Only the owner or a workspace admin may revoke permissions. Ownership and inherited access are unaffected.

Parameters:

  • name – str Resource name in the form session-stores/{session_store_id}.

  • principal – StorePrincipal Principal whose READ and WRITE grants will be removed.

Returns:

RevokeSessionStorePermissionResponse

search_memories(parent: str, actor_id: str, query: str [, limit: Optional[int], page_size: Optional[int], page_token: Optional[str], path_prefix: Optional[str], session_id: Optional[str], view: Optional[ManagedMemoryEntryView]]) → Iterator[ManagedMemoryEntrySearchResult]

Searches memory entries by text query for one actor. Returns matching entries and scores ranked by relevance; view controls whether each returned entry includes content.

Parameters:

  • parent – str Memory store whose entries are searched, in the form memory-stores/{managed_memory_store_id}.

  • actor_id – str Customer-provided identifier for the actor whose entries are searched.

  • query – str Free-form search query.

  • limit – int (optional) Deprecated alias for page_size. When both fields are set, their values must match.

  • page_size – int (optional) Maximum number of relevance-ranked entries to return. Defaults to 10 and must be between 1 and 100.

  • page_token – str (optional) Reserved for pagination compatibility. The server currently ignores this field because Search returns a ranked top-N result set.

  • path_prefix – str (optional) Optional absolute, case-sensitive path prefix used to restrict searched entries within the actor partition. The prefix must begin with / and must not contain empty, . or .. segments.

  • session_id – str (optional) Optional session identifier. When set, only entries with this exact session_id are searched. Omitted-session (cross-session) entries are not included.

  • view – ManagedMemoryEntryView (optional) Controls whether each returned entry includes memory content. Search scores are always returned. Defaults to FULL.

Returns:

Iterator over ManagedMemoryEntrySearchResult

update_memory(name: str, managed_memory_entry: ManagedMemoryEntry, update_mask: FieldMask) → ManagedMemoryEntry

Updates selected mutable fields on a memory entry. Identity fields are immutable.

Parameters:

  • name – str Resource name in the form memory-stores/{managed_memory_store_id}/entries/{managed_memory_entry_id}. Required for updates; assigned by the service on creation.

  • managed_memory_entry – ManagedMemoryEntry The memory entry to update.

  • update_mask – FieldMask Fields to update. Only content and description may be updated.

Returns:

ManagedMemoryEntry

update_memory_store(name: str, managed_memory_store: ManagedMemoryStore, update_mask: FieldMask) → ManagedMemoryStore

Updates a memory store’s description and metadata.

Parameters:

  • name – str Resource name in the form memory-stores/{managed_memory_store_id}.

  • managed_memory_store – ManagedMemoryStore The memory store to update. name is taken from the URL.

  • update_mask – FieldMask Only description and metadata may be updated. Selecting metadata replaces the entire map.

Returns:

ManagedMemoryStore

update_session(name: str, session: Session, update_mask: FieldMask) → Session

Updates a session’s mutable fields.

Parameters:

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

  • session – Session Session to update.

  • update_mask – FieldMask Fields to update. Only metadata is mutable; any other path returns INVALID_PARAMETER_VALUE.

Returns:

Session

update_session_store(name: str, session_store: SessionStore, update_mask: FieldMask) → SessionStore

Updates a session store’s description and metadata.

Parameters:

  • name – str Resource name in the form session-stores/{session_store_id}.

  • session_store – SessionStore Session store to update.

  • update_mask – FieldMask Fields to update. Only description and metadata are mutable; any other path returns INVALID_PARAMETER_VALUE.

Returns:

SessionStore