Geheugen-API-referentie

Deze pagina is de REST API-verwijzing voor het geheugen van beheerde agents. Hierin worden de eindpunten, aanvraagvelden en antwoordvelden voor beheerd geheugen behandeld:

• Een geheugenopslag is een Unity Catalog die kan worden beveiligd als een container voor geheugenvermeldingen. Gebruik de MEMORY Store-API's om winkels te maken en te beheren.
• Een geheugenvermelding is een afzonderlijk stukje inhoud dat is opgeslagen in een geheugenopslag. Gebruik de GEHEUGEN-invoer-API's om vermeldingen te lezen en schrijven.
• Een gesprek is openAI-compatibele gespreksstatus ( berichten en hulpprogramma-aanroepen), ondersteund door een geheugenarchief en vastgemaakt aan een bereik. Gebruik de Gespreks-API's om gesprekken en hun items te maken en te beheren.

Prerequisites

Genereer een OAuth-token met behulp van de Databricks CLI om de API's aan te roepen:

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

API's voor geheugenopslag

Een geheugenopslag is een Unity Catalog die kan worden beveiligd als een container voor geheugenvermeldingen. Geheugenarchieven gebruiken naamgeving op drie niveaus: catalog.schema.memory_store_name.

Een geheugenopslag maken

Hiermee maakt u een nieuw geheugenarchief onder een bovenliggend schema.

• Eindpunt:POST /api/2.1/unity-catalog/memory-stores
• Vereiste bevoegdheid: CREATE MEMORY STORE in het bovenliggende schema

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

Aanvraagvelden:

Een geheugenopslag ophalen

Hiermee wordt een geheugenopslag opgehaald op basis van de volledig gekwalificeerde naam van drie delen.

• Eindpunt:GET /api/2.1/unity-catalog/memory-stores/{full_name}
• Vereiste bevoegdheid: READ MEMORY STORE in het archief

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

Geheugenarchieven weergeven

Bevat geheugenarchieven in een schema. Resultaten worden gefilterd om op te slaan dat de beller kan lezen.

• Eindpunt:GET /api/2.1/unity-catalog/memory-stores
• Vereiste bevoegdheid: USE SCHEMA in het bovenliggende schema

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

Zoekparameters

Een geheugenopslag bijwerken

Hiermee worden onveranderbare velden in een geheugenarchief bijgewerkt. Momenteel is alleen description veranderlijk.

• Eindpunt:PATCH /api/2.1/unity-catalog/memory-stores/{full_name}
• Vereiste bevoegdheid: MANAGE in het archief

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

Een geheugenarchief verwijderen

Hiermee verwijdert u een geheugenopslag en alle geheugenvermeldingen.

• Eindpunt:DELETE /api/2.1/unity-catalog/memory-stores/{full_name}
• Vereiste bevoegdheid: MANAGE in het archief

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

Antwoordvelden voor geheugenopslag

API's voor geheugeninvoer

Geheugenvermeldingen zijn de afzonderlijke stukjes inhoud die zijn opgeslagen in een geheugenopslag. Elke vermelding wordt geïdentificeerd door een bereik en een pad: scope is een partitiesleutel die de aanroeper toewijst (bijvoorbeeld een id van de eindgebruiker) en path is een zacht pad binnen dat bereik waarmee moet worden begonnen /memories/ (bijvoorbeeld /memories/preferences.md). scope is vereist voor elke aanvraag voor geheugeninvoer.

Een geheugenvermelding maken

Hiermee maakt u een nieuwe geheugenvermelding in een geheugenarchief.

• Eindpunt:POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries?scope=<scope>
• Vereiste bevoegdheid: WRITE MEMORY STORE in het archief

scope is een queryparameter; de hoofdtekst van de aanvraag is de vermelding zelf.

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

Aanvraagvelden:

Een geheugenvermelding ophalen

Hiermee wordt één geheugenvermelding opgehaald door scope en path.

• Eindpunt:GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries:get
• Vereiste bevoegdheid: READ MEMORY STORE in het archief

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

Geheugenvermeldingen vermelden

Bevat geheugenvermeldingen in een bereik.

• Eindpunt:GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• Vereiste bevoegdheid: READ MEMORY STORE in het archief

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

Zoekparameters

Lijstantwoorden laten contents weg (alleen metagegevens) en bevatten een next_page_token wanneer er meer pagina's blijven.

Een geheugenvermelding bijwerken

Hiermee past u één bewerking toe op een bestaande vermelding contents, geïdentificeerd door scope en path. Geef precies een van str_replace, insertof replace_all. description kan worden bewerkt: stel deze in om de beschrijving van de vermelding te vervangen of laat deze weg om de beschrijving ongewijzigd te laten.

• Eindpunt:PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• Vereiste bevoegdheid: WRITE MEMORY STORE in het archief

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

Bewerkingen bewerken (precies één instellen):

Een geheugenvermelding verwijderen

Hiermee verwijdert u een geheugenvermelding, geïdentificeerd door scope en path.

• Eindpunt:DELETE /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• Vereiste bevoegdheid: WRITE MEMORY STORE in het archief

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

Geheugenvermeldingen zoeken

Hiermee wordt gezocht naar geheugenvermeldingen op trefwoord op pad, inhoud en beschrijvingsvelden.

• Eindpunt:POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries:search
• Vereiste bevoegdheid: READ MEMORY STORE in het archief

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

Aanvraagvelden: scope (vereist), (vereist), querypath_prefix (optioneel), top_k (optioneel; standaard ingesteld op 10, max. 50).

Antwoordvelden voor geheugeninvoer

Gespreks-API's

In een gesprek wordt de openAI-compatibele gespreksstatus ( berichten, hulpprogramma-aanroepen en andere items) opgeslagen in een geheugenarchief onder één bereik. Met een gesprek blijft een agent de sessiestatusserver behouden en opnieuw laden. U maakt elk gesprek op basis van een geheugenarchief (driedelige naam) en een scope, en gespreksbewerkingen hebben dezelfde bevoegdheden nodig als het onderliggende geheugenarchief.

Een gesprek maken

Hiermee maakt u een gesprek dat is gebonden aan een geheugenopslag en -bereik.

• Eindpunt:POST /api/2.1/unity-catalog/conversations
• Vereiste bevoegdheid: WRITE MEMORY STORE in het archief

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

Aanvraagvelden:

Een gesprek ophalen

Hiermee wordt een gesprek opgehaald op basis van de id.

• Eindpunt:GET /api/2.1/unity-catalog/conversations/{conversation_id}
• Vereiste bevoegdheid: READ MEMORY STORE in het archief

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

Een gesprek bijwerken

Werkt het gesprek bij metadata.

• Eindpunt:POST /api/2.1/unity-catalog/conversations/{conversation_id}
• Vereiste bevoegdheid: WRITE MEMORY STORE in het archief

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

Een gesprek verwijderen

Hiermee verwijdert u een gesprek en de bijbehorende items.

• Eindpunt:DELETE /api/2.1/unity-catalog/conversations/{conversation_id}
• Vereiste bevoegdheid: WRITE MEMORY STORE in het archief

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

Antwoordvelden voor gesprekken

API's voor gespreksitems

Items zijn de afzonderlijke berichten en hulpprogrammagesprekken binnen een gesprek. Ze volgen de vorm van openAI-gespreksitems en gebruiken openAI-compatibele paginering (after, limit, has_more).