API-referens för minne

Den här sidan är REST API-referensen för hanterat agentminne. Den omfattar slutpunkter, fält för begäranden och svarsfält för hanterat minne:

• Ett minneslager är en Unity Catalog-skyddsbar som fungerar som en container för minnesposter. Använd API:erna för minnesarkiv för att skapa och hantera butiker.
• En minnespost är ett enskilt innehåll som lagras i ett minnesarkiv. Använd API:erna för minnespost för att läsa och skriva poster.
• En konversation är OpenAI-kompatibelt konversationstillstånd – meddelanden och verktygsanrop – som backas upp av ett minnesarkiv och fästs på ett omfång. Använd konversations-API:erna för att skapa och hantera konversationer och deras objekt.

Förutsättningar

Generera en OAuth-token med Databricks CLI för att anropa API:erna:

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

API:er för minneslager

Ett minneslager är en Unity Catalog-skyddsbar som fungerar som en container för minnesposter. Minneslager använder namngivning på tre nivåer: catalog.schema.memory_store_name.

Skapa ett minneslager

Skapar ett nytt minneslager under ett överordnat schema.

• Slutpunkt:POST /api/2.1/unity-catalog/memory-stores
• Nödvändig behörighet: CREATE MEMORY STORE i det överordnade schemat

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

Fält för begäran:

Hämta ett minneslager

Hämtar ett minneslager med sitt fullständiga namn i tre delar.

• Slutpunkt:GET /api/2.1/unity-catalog/memory-stores/{full_name}
• Nödvändig behörighet: READ MEMORY STORE i arkivet

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

Lista minnesenheter

Visar en lista över minneslager i ett schema. Resultaten filtreras så att de lagrar som anroparen kan läsa.

• Slutpunkt:GET /api/2.1/unity-catalog/memory-stores
• Nödvändig behörighet: USE SCHEMA i det överordnade schemat

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

Frågeparametrar:

Uppdatera ett minneslager

Uppdaterar föränderliga fält i ett minnesarkiv. För närvarande är endast description föränderligt.

• Slutpunkt:PATCH /api/2.1/unity-catalog/memory-stores/{full_name}
• Nödvändig behörighet: MANAGE i arkivet

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

Ta bort ett minnesarkiv

Tar bort ett minneslager och alla dess minnesposter.

• Slutpunkt:DELETE /api/2.1/unity-catalog/memory-stores/{full_name}
• Nödvändig behörighet: MANAGE i arkivet

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

Svarsfält för minneslager

API:er för minnespost

Minnesposter är de enskilda innehållsdelarna som lagras i ett minnesarkiv. Varje post identifieras av ett omfång och en sökväg: scope är en partitionsnyckel som anroparen tilldelar (till exempel ett slutanvändar-ID) och path är en mjuk sökväg inom det omfånget som måste börja med /memories/ (till exempel /memories/preferences.md). scope krävs för varje begäran om minnesinmatning.

Skapa en minnespost

Skapar en ny minnespost i ett minneslager.

• Slutpunkt:POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries?scope=<scope>
• Nödvändig behörighet: WRITE MEMORY STORE i arkivet

scope är en frågeparameter. begärandetexten är själva posten.

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

Fält för begäran:

Hämta en minnespost

Hämtar en enskild minnespost av scope och path.

• Slutpunkt:GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries:get
• Nödvändig behörighet: READ MEMORY STORE i arkivet

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

Lista minnesposter

Visar en lista över minnesposter i ett omfång.

• Slutpunkt:GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• Nödvändig behörighet: READ MEMORY STORE i arkivet

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

Frågeparametrar:

Listsvar utelämnar contents (endast metadata) och inkluderar en next_page_token när fler sidor finns kvar.

Uppdatera en minnespost

Tillämpar en enskild redigeringsåtgärd på en befintlig posts , som identifieras contentsav scope och path. Ange exakt en av str_replace, inserteller replace_all. description är redigerbar: ställ in den för att ersätta postens beskrivning eller utelämna den för att lämna beskrivningen oförändrad.

• Slutpunkt:PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• Nödvändig behörighet: WRITE MEMORY STORE i arkivet

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

Redigera åtgärder (ange exakt en):

Ta bort en minnespost

Tar bort en minnespost som identifieras av scope och path.

• Slutpunkt:DELETE /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• Nödvändig behörighet: WRITE MEMORY STORE i arkivet

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

Sök efter minnesposter

Söker igenom minnesposter efter nyckelord i sökvägs-, innehålls- och beskrivningsfält.

• Slutpunkt:POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries:search
• Nödvändig behörighet: READ MEMORY STORE i arkivet

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

Begärandefält: scope (krävs), query (obligatoriskt), path_prefix (valfritt), top_k (valfritt; standardvärdet är 10, max 50).

Svarsfält för minnespost

Konversations-API:er

En konversation lagrar OpenAI-kompatibelt konversationstillstånd – meddelanden, verktygsanrop och andra objekt – i ett minneslager under ett enda omfång. Med en konversation bevarar och läser en agent in sessionstillståndet på serversidan igen. Du skapar varje konversation mot ett minneslager (tredelade namn) och en scope, och konversationsåtgärder kräver samma behörigheter som det underliggande minnesarkivet.

Skapa en konversation

Skapar en konversation som är bunden till ett minneslager och omfång.

• Slutpunkt:POST /api/2.1/unity-catalog/conversations
• Nödvändig behörighet: WRITE MEMORY STORE i arkivet

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

Fält för begäran:

Hämta en konversation

Hämtar en konversation med dess ID.

• Slutpunkt:GET /api/2.1/unity-catalog/conversations/{conversation_id}
• Nödvändig behörighet: READ MEMORY STORE i arkivet

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

Uppdatera en konversation

Uppdaterar en konversations metadata.

• Slutpunkt:POST /api/2.1/unity-catalog/conversations/{conversation_id}
• Nödvändig behörighet: WRITE MEMORY STORE i arkivet

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

Ta bort en konversation

Tar bort en konversation och dess objekt.

• Slutpunkt:DELETE /api/2.1/unity-catalog/conversations/{conversation_id}
• Nödvändig behörighet: WRITE MEMORY STORE i arkivet

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

Fält för konversationssvar

API:er för konversationsobjekt

Objekt är enskilda meddelanden och verktygsanrop i en konversation. De följer formen OpenAI-konversationsobjekt och använder OpenAI-kompatibel sidnumrering (after, limit, has_more).