Informazioni di riferimento sulle API di memoria

Questa pagina è il riferimento all'API REST per la memoria dell'agente gestito. Vengono illustrati gli endpoint, i campi della richiesta e i campi di risposta per la memoria gestita:

Un archivio di memoria è un'entità a protezione diretta di Unity Catalog che funge da contenitore per le voci di memoria. Usare le API dell'archivio memoria per creare e gestire archivi.
Una voce di memoria è una singola parte di contenuto archiviata all'interno di un archivio di memoria. Usare le API di immissione memoria per leggere e scrivere voci.
Una conversazione è uno stato di conversazione compatibile con OpenAI, ovvero messaggi e chiamate di strumenti, supportato da un archivio di memoria e aggiunto a un ambito. Usare le API di conversazione per creare e gestire conversazioni e i relativi elementi.

Prerequisiti

Generare un token OAuth usando l'interfaccia della riga di comando di Databricks per chiamare le API:

databricks auth login --host ${DATABRICKS_HOST}
databricks auth token

API dell'archivio memoria

Un archivio di memoria è un'entità a protezione diretta di Unity Catalog che funge da contenitore per le voci di memoria. Gli archivi di memoria usano la denominazione a tre livelli: catalog.schema.memory_store_name.

Operazione	Punto finale	Privilegio obbligatorio
Creare	`POST /api/2.1/unity-catalog/memory-stores`	`CREATE MEMORY STORE` nel modello genitore
GET	`GET /api/2.1/unity-catalog/memory-stores/{full_name}`	`READ MEMORY STORE` nel negozio
Elenco	`GET /api/2.1/unity-catalog/memory-stores`	`USE SCHEMA` nel modello genitore
Update	`PATCH /api/2.1/unity-catalog/memory-stores/{full_name}`	`MANAGE` nel negozio
Elimina	`DELETE /api/2.1/unity-catalog/memory-stores/{full_name}`	`MANAGE` nel negozio

Creare un archivio di memoria

Crea un nuovo archivio di memoria in uno schema padre.

Endpoint:POST /api/2.1/unity-catalog/memory-stores
Privilegio obbligatorio: CREATE MEMORY STORE nello schema padre

curl -X POST "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agent_memory",
    "catalog_name": "main",
    "schema_name": "default",
    "description": "Memory store for customer support agents"
  }'

Campi della richiesta:

Campo	Tipo	Obbligatorio	Description
`name`	`string`	Yes	Nome breve per l'archivio di memoria. Deve corrispondere a `[A-Za-z0-9_-]+`, da 1 a 255 caratteri. Univoco all'interno dello schema padre.
`catalog_name`	`string`	Yes	Nome del catalogo padre.
`schema_name`	`string`	Yes	Nome dello schema padre, relativo al catalogo.
`description`	`string`	No	Descrizione leggibile dell'archivio di memoria.

Ottenere un archivio di memoria

Recupera un archivio di memoria in base al nome completo in tre parti.

Endpoint:GET /api/2.1/unity-catalog/memory-stores/{full_name}
Privilegio obbligatorio: READ MEMORY STORE nell'archivio

curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Elencare gli archivi di memoria

Elenca gli archivi di memoria in uno schema. I risultati vengono filtrati per archiviare il chiamante in grado di leggere.

Endpoint:GET /api/2.1/unity-catalog/memory-stores
Privilegio obbligatorio: USE SCHEMA nello schema padre

curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores?catalog_name=main&schema_name=default" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Parametri di query:

Parametro	Tipo	Obbligatorio	Description
`catalog_name`	`string`	Yes	Nome catalogo padre.
`schema_name`	`string`	Yes	Nome schema padre.
`page_token`	`string`	No	Token di paginazione da una risposta precedente.
`max_results`	`integer`	No	Numero massimo di archivi per pagina. Il valore predefinito è 100, massimo 1000.

Aggiornare un archivio di memoria

Aggiorna i campi modificabili in un archivio di memoria. Attualmente è modificabile solo description .

Endpoint:PATCH /api/2.1/unity-catalog/memory-stores/{full_name}
Privilegio obbligatorio: MANAGE nell'archivio

curl -X PATCH \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_store": {
      "description": "Updated description for the memory store"
    },
    "update_mask": "description"
  }'

Eliminare un archivio di memoria

Elimina un archivio memoria e tutte le relative voci di memoria.

Endpoint:DELETE /api/2.1/unity-catalog/memory-stores/{full_name}
Privilegio obbligatorio: MANAGE nell'archivio

curl -X DELETE \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Campi di risposta dell'archivio memoria

Campo	Tipo	Description
`name`	`string`	Nome breve dell'archivio di memoria.
`catalog_name`	`string`	Nome catalogo padre.
`schema_name`	`string`	Nome schema padre.
`description`	`string`	Descrizione leggibile dagli umani
`owner`	`string`	Entità uc proprietaria dell'archivio. Impostato in caso di creazione.
`full_name`	`string`	Nome completo in tre parti: `catalog.schema.name`.
`memory_store_id`	`string`	UUID assegnato al server.
`securable_type`	`string`	Sempre `MEMORY_STORE`.
`created_at`	`integer`	Tempo di creazione in millisecondi dell'epoca Unix.
`updated_at`	`integer`	Ora dell'ultimo aggiornamento in millisecondi dell'epoca Unix.
`created_by`	`string`	Entità che ha creato l'archivio.

API di immissione della memoria

Le voci di memoria sono le singole parti di contenuto archiviate all'interno di un archivio di memoria. Ogni voce viene identificata da un ambito e da un percorso: scope è una chiave di partizione assegnata dal chiamante (ad esempio, un ID utente finale) ed path è un percorso flessibile all'interno di tale ambito che deve iniziare con /memories/ (ad esempio, /memories/preferences.md). scope è obbligatorio per ogni richiesta di voce di memoria.

Operazione	Punto finale	Privilegio obbligatorio
Creare	`POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`WRITE MEMORY STORE` nel negozio
GET	`GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries:get`	`READ MEMORY STORE` nel negozio
Elenco	`GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`READ MEMORY STORE` nel negozio
Update	`PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`WRITE MEMORY STORE` nel negozio
Elimina	`DELETE /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`WRITE MEMORY STORE` nel negozio
Ricerca	`POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries:search`	`READ MEMORY STORE` nel negozio

Creare una voce di memoria

Crea una nuova voce di memoria in un archivio memoria.

Endpoint:POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries?scope=<scope>
Privilegio obbligatorio: WRITE MEMORY STORE nell'archivio

scope è un parametro di query; il corpo della richiesta è la voce stessa.

curl -X POST \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries?scope=user-42" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/memories/preferences.md",
    "contents": "The user prefers responses in English and uses formal tone.",
    "description": "User language and tone preferences"
  }'

Campi della richiesta:

Campo	In	Tipo	Obbligatorio	Description
`scope`	query	`string`	Yes	La partizione a cui appartiene la voce, assegnata dal chiamante, ad esempio un ID utente finale.
`path`	body	`string`	Yes	Percorso flessibile che identifica la voce all'interno dell'ambito. Deve iniziare con `/memories/`. Non modificabile.
`contents`	body	`string`	No	Contenuto di testo di memoria in formato libero.
`description`	body	`string`	No	Riepilogo in una riga della voce di memoria. Funge da hook di indice nelle risposte di elenco.

Ottenere una voce di memoria

Recupera una singola voce di memoria per scope e path.

Endpoint:GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries:get
Privilegio obbligatorio: READ MEMORY STORE nell'archivio

curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries:get?scope=user-42&path=/memories/preferences.md" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Elencare le voci di memoria

Elenca le voci di memoria in un ambito.

Endpoint:GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries
Privilegio obbligatorio: READ MEMORY STORE nell'archivio

curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries?scope=user-42" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Parametri di query:

Parametro	Tipo	Obbligatorio	Description
`scope`	`string`	Yes	Ambito (partizione) da cui elencare le voci.
`path_prefix`	`string`	No	Restituisce solo voci il cui percorso inizia con questo prefisso.
`page_size`	`integer`	No	Numero massimo di voci per pagina. Il server delimita le dimensioni della pagina.
`page_token`	`string`	No	Token di paginazione da una risposta precedente.

Elencare le risposte omettere contents (solo metadati) e includere un next_page_token quando rimangono più pagine.

Aggiornare una voce di memoria

Applica una singola operazione di modifica a una contentsvoce esistente, identificata da scope e path. Specificare esattamente uno di str_replace, inserto replace_all. description è modificabile: impostarla per sostituire la descrizione della voce o ometterla per lasciare invariata la descrizione.

Endpoint:PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries
Privilegio obbligatorio: WRITE MEMORY STORE nell'archivio

curl -X PATCH \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user-42",
    "path": "/memories/preferences.md",
    "replace_all": { "contents": "The user prefers responses in Spanish and uses casual tone." }
  }'

Operazioni di modifica (impostate esattamente una):

Operazione	Fields	Behavior
`replace_all`	`contents`	Sovrascrivere il contenuto completo della voce.
`str_replace`	`old_str`, `new_str`	Sostituire la singola occorrenza di `old_str` con `new_str` (deve corrispondere esattamente una volta).
`insert`	`insert_line`, `insert_text`	Inserisci `insert_text`; `insert_line` 0 = superiore, omesso = accodare alla fine.

Eliminare una voce di memoria

Elimina una voce di memoria, identificata da scope e path.

Endpoint:DELETE /api/2.1/unity-catalog/memory-stores/{full_name}/entries
Privilegio obbligatorio: WRITE MEMORY STORE nell'archivio

curl -X DELETE \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries?scope=user-42&path=/memories/preferences.md" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Cerca voci di memoria

Cerca le voci di memoria per parola chiave nei campi percorso, contenuto e descrizione.

Endpoint:POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries:search
Privilegio obbligatorio: READ MEMORY STORE nell'archivio

curl -X POST \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries:search" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user-42",
    "query": "language preferences"
  }'

Campi della richiesta: scope (obbligatorio), query (obbligatorio), (facoltativo), path_prefixtop_k (facoltativo; il valore predefinito è 10, massimo 50).

Campi di risposta della voce di memoria

Campo	Tipo	Description
`path`	`string`	Percorso flessibile della voce all'interno del relativo ambito.
`contents`	`string`	Testo della memoria. Omesso nelle risposte elenco.
`description`	`string`	Riepilogo su una riga.
`scope`	`string`	Ambito (partizione) a cui appartiene la voce.
`memory_store_name`	`string`	Nome in tre parti dell'archivio di memoria padre.
`has_contents`	`boolean`	Indica se la voce non è vuota `contents` (utile in Elenco).
`create_time`	`string`	Timestamp di creazione (RFC 3339).
`update_time`	`string`	Timestamp ultimo aggiornamento (RFC 3339).

API di conversazione

Una conversazione archivia lo stato della conversazione compatibile con OpenAI, ovvero messaggi, chiamate di strumenti e altri elementi, in un archivio memoria in un unico ambito. Con una conversazione, un agente mantiene e ricarica il lato server dello stato della sessione. Ogni conversazione viene creata su un archivio memoria (nome in tre parti) e le scopeoperazioni di conversazione e richiedono gli stessi privilegi dell'archivio di memoria sottostante.

Operazione	Punto finale	Privilegio obbligatorio
Creare	`POST /api/2.1/unity-catalog/conversations`	`WRITE MEMORY STORE` nel negozio
GET	`GET /api/2.1/unity-catalog/conversations/{conversation_id}`	`READ MEMORY STORE` nel negozio
Update	`POST /api/2.1/unity-catalog/conversations/{conversation_id}`	`WRITE MEMORY STORE` nel negozio
Elimina	`DELETE /api/2.1/unity-catalog/conversations/{conversation_id}`	`WRITE MEMORY STORE` nel negozio

Creare una conversazione

Crea una conversazione associata a un archivio di memoria e a un ambito.

Endpoint:POST /api/2.1/unity-catalog/conversations
Privilegio obbligatorio: WRITE MEMORY STORE nell'archivio

curl -X POST "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/conversations" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_store": { "name": "main.default.support_agent_memory" },
    "scope": { "kind": "user", "value": "user-123" },
    "metadata": { "source": "support-chat" }
  }'

Campi della richiesta:

Campo	Tipo	Obbligatorio	Description
`memory_store`	`object`	Yes	Archivio memoria che esegue il backup della conversazione.
`memory_store.name`	`string`	Yes	Nome completo in tre parti dell'archivio di memoria: `catalog.schema.memory_store`.
`scope`	`object`	Yes	L'ambito della conversazione viene aggiunto a.
`scope.kind`	`string`	Yes	Tipo di ambito, ad esempio `user` o `user_defined`.
`scope.value`	`string`	Yes	Valore di ambito specifico del tipo, ad esempio un ID utente finale.
`metadata`	`object`	No	Metadati chiave-valore controllati dal chiamante. Fino a 16 chiavi; chiavi fino a 64 caratteri, valori fino a 512 caratteri.
`items`	`array`	No	Elementi iniziali della conversazione OpenAI per inizializzare la conversazione (fino a 20). Gli elementi senza un `type` oggetto vengono archiviati come elementi di messaggio.

Ottenere una conversazione

Recupera una conversazione in base al relativo ID.

Endpoint:GET /api/2.1/unity-catalog/conversations/{conversation_id}
Privilegio obbligatorio: READ MEMORY STORE nell'archivio

curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/conversations/${CONVERSATION_ID}" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Aggiornare una conversazione

Aggiorna l'oggetto di una conversazione.metadata

Endpoint:POST /api/2.1/unity-catalog/conversations/{conversation_id}
Privilegio obbligatorio: WRITE MEMORY STORE nell'archivio

curl -X POST \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/conversations/${CONVERSATION_ID}" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "source": "support-chat", "resolved": "true" } }'

Eliminare una conversazione

Elimina una conversazione e i relativi elementi.

Endpoint:DELETE /api/2.1/unity-catalog/conversations/{conversation_id}
Privilegio obbligatorio: WRITE MEMORY STORE nell'archivio

curl -X DELETE \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/conversations/${CONVERSATION_ID}" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Campi risposta conversazione

Campo	Tipo	Description
`id`	`string`	ID conversazione assegnato dal server.
`object`	`string`	Sempre `conversation`.
`created_at`	`integer`	Tempo di creazione in secondi dell'epoca Unix.
`metadata`	`object`	Metadati chiave-valore forniti dal chiamante.

API degli elementi di conversazione

Gli elementi sono i singoli messaggi e le chiamate degli strumenti all'interno di una conversazione. Seguono la forma Degli elementi della conversazione OpenAI e usano la paginazione compatibile con OpenAI (after, limit, has_more).

Operazione	Punto finale	Privilegio obbligatorio
Creare elementi	`POST /api/2.1/unity-catalog/conversations/{conversation_id}/items`	`WRITE MEMORY STORE` nel negozio
Ottieni elemento	`GET /api/2.1/unity-catalog/conversations/{conversation_id}/items/{item_id}`	`READ MEMORY STORE` nel negozio
Elementi elenco	`GET /api/2.1/unity-catalog/conversations/{conversation_id}/items`	`READ MEMORY STORE` nel negozio
Elimina elemento	`DELETE /api/2.1/unity-catalog/conversations/{conversation_id}/items/{item_id}`	`WRITE MEMORY STORE` nel negozio

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-07-01

Informazioni di riferimento sulle API di memoria

Prerequisiti

API dell'archivio memoria

Creare un archivio di memoria

Ottenere un archivio di memoria

Elencare gli archivi di memoria

Aggiornare un archivio di memoria

Eliminare un archivio di memoria

Campi di risposta dell'archivio memoria

API di immissione della memoria

Creare una voce di memoria

Ottenere una voce di memoria

Elencare le voci di memoria

Aggiornare una voce di memoria

Eliminare una voce di memoria

Cerca voci di memoria

Campi di risposta della voce di memoria

API di conversazione

Creare una conversazione

Ottenere una conversazione

Aggiornare una conversazione

Eliminare una conversazione

Campi risposta conversazione

API degli elementi di conversazione

Commenti e suggerimenti

Risorse aggiuntive