Informations de référence sur l’API mémoire

Cette page est la référence de l’API REST pour la mémoire de l’agent managé. Il couvre les points de terminaison, les champs de requête et les champs de réponse pour la mémoire managée :

• Un magasin de mémoire est un catalogue Unity sécurisable qui agit comme un conteneur pour les entrées de mémoire. Utilisez les API du magasin de mémoire pour créer et gérer des magasins.
• Une entrée de mémoire est un élément de contenu individuel stocké dans un magasin de mémoire. Utilisez les API d’entrée de mémoire pour lire et écrire des entrées.
• Une conversation est compatible avec OpenAI ( messages et appels d’outils) soutenus par un magasin de mémoire et épinglé à une étendue. Utilisez les API conversation pour créer et gérer des conversations et leurs éléments.

Prerequisites

Générez un jeton OAuth à l’aide de l’interface CLI Databricks pour appeler les API :

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

API du magasin de mémoire

Un magasin de mémoire est un catalogue Unity sécurisable qui agit comme un conteneur pour les entrées de mémoire. Les magasins de mémoire utilisent un nommage à trois niveaux : catalog.schema.memory_store_name.

Créer un magasin de mémoire

Crée un magasin de mémoire sous un schéma parent.

• Point de terminaison :POST /api/2.1/unity-catalog/memory-stores
• Privilège requis : CREATE MEMORY STORE sur le schéma parent

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"
  }'

Champs de demande :

Obtenir un magasin de mémoire

Récupère un magasin de mémoire par son nom complet en trois parties.

• Point de terminaison :GET /api/2.1/unity-catalog/memory-stores/{full_name}
• Privilège requis : READ MEMORY STORE sur le magasin

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

Répertorier les stockages de mémoire

Répertorie les magasins de mémoire dans un schéma. Les résultats sont filtrés pour stocker l’appelant peut lire.

• Point de terminaison :GET /api/2.1/unity-catalog/memory-stores
• Privilège requis : USE SCHEMA sur le schéma parent

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

Paramètres de requête :

Mettre à jour un magasin de mémoire

Met à jour les champs mutables sur un magasin de mémoire. Actuellement, seul description le mutable est mutable.

• Point de terminaison :PATCH /api/2.1/unity-catalog/memory-stores/{full_name}
• Privilège requis : MANAGE sur le magasin

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"
  }'

Supprimer un magasin de mémoire

Supprime un magasin de mémoire et toutes ses entrées de mémoire.

• Point de terminaison :DELETE /api/2.1/unity-catalog/memory-stores/{full_name}
• Privilège requis : MANAGE sur le magasin

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

Champs de réponse du magasin de mémoire

API d’entrée de mémoire

Les entrées de mémoire sont les éléments de contenu individuels stockés dans un magasin de mémoire. Chaque entrée est identifiée par une étendue et un chemin d’accès : scope est une clé de partition que l’appelant affecte (par exemple, un ID d’utilisateur final) et path est un chemin d’accès souple dans cette étendue qui doit commencer /memories/ par (par exemple). /memories/preferences.md scope est nécessaire pour chaque demande d’entrée de mémoire.

Créer une entrée de mémoire

Crée une entrée de mémoire dans un magasin de mémoire.

• Point de terminaison :POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries?scope=<scope>
• Privilège requis : WRITE MEMORY STORE sur le magasin

scope est un paramètre de requête ; le corps de la demande est l’entrée elle-même.

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"
  }'

Champs de demande :

Obtenir une entrée de mémoire

Récupère une entrée de mémoire unique par scope et path.

• Point de terminaison :GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries:get
• Privilège requis : READ MEMORY STORE sur le magasin

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}"

Répertorier les entrées de mémoire

Répertorie les entrées de mémoire dans une étendue.

• Point de terminaison :GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• Privilège requis : READ MEMORY STORE sur le magasin

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}"

Paramètres de requête :

Les réponses de liste omettent contents (métadonnées uniquement) et incluent un next_page_token moment où d’autres pages restent.

Mettre à jour une entrée de mémoire

Applique une opération de modification unique à l’entrée contentsexistante, identifiée par scope et path. Fournissez exactement l’un des str_replace, insertou replace_all. description est modifiable : définissez-la pour remplacer la description de l’entrée ou omettez-la pour laisser la description inchangée.

• Point de terminaison :PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• Privilège requis : WRITE MEMORY STORE sur le magasin

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." }
  }'

Modifier les opérations (définir exactement une seule) :

Supprimer une entrée de mémoire

Supprime une entrée de mémoire, identifiée par scope et path.

• Point de terminaison :DELETE /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• Privilège requis : WRITE MEMORY STORE sur le magasin

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}"

Entrées de mémoire de recherche

Recherche les entrées de mémoire par mot clé sur le chemin, le contenu et les champs de description.

• Point de terminaison :POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries:search
• Privilège requis : READ MEMORY STORE sur le magasin

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"
  }'

Champs de demande : scope (obligatoire), query (obligatoire), path_prefix (facultatif), top_k (facultatif ; par défaut à 10, max. 50).

Champs de réponse d’entrée de mémoire

API de conversation

Une conversation stocke l’état de conversation compatible OpenAI ( messages, appels d’outils et autres éléments) dans un magasin de mémoire sous une seule étendue. Avec une conversation, un agent conserve et recharge le côté serveur de l’état de session. Vous créez chaque conversation sur un magasin de mémoire (nom en trois parties) et des scopeopérations de conversation nécessitent les mêmes privilèges que le magasin de mémoire sous-jacent.

Créer une conversation

Crée une conversation liée à un magasin de mémoire et à une étendue.

• Point de terminaison :POST /api/2.1/unity-catalog/conversations
• Privilège requis : WRITE MEMORY STORE sur le magasin

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" }
  }'

Champs de demande :

Obtenir une conversation

Récupère une conversation par son ID.

• Point de terminaison :GET /api/2.1/unity-catalog/conversations/{conversation_id}
• Privilège requis : READ MEMORY STORE sur le magasin

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

Mettre à jour une conversation

Met à jour la conversation metadata.

• Point de terminaison :POST /api/2.1/unity-catalog/conversations/{conversation_id}
• Privilège requis : WRITE MEMORY STORE sur le magasin

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" } }'

Supprimer une conversation

Supprime une conversation et ses éléments.

• Point de terminaison :DELETE /api/2.1/unity-catalog/conversations/{conversation_id}
• Privilège requis : WRITE MEMORY STORE sur le magasin

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

Champs de réponse aux conversations

API d’élément de conversation

Les éléments sont les messages individuels et les appels d’outil au sein d’une conversation. Ils suivent la forme des éléments de conversation OpenAI et utilisent la pagination compatible OpenAI (after, limit, has_more).