Referenční informace k rozhraní API pro paměť

Tato stránka je referenční informace k rozhraní REST API pro paměť spravovaného agenta. Zahrnuje koncové body, pole požadavků a pole odpovědí pro spravovanou paměť:

Úložiště paměti je zabezpečitelný katalog Unity, který funguje jako kontejner pro položky paměti. Rozhraní API úložiště paměti slouží k vytváření a správě úložišť.
Položka paměti je jednotlivá část obsahu uložená v úložišti paměti. Pomocí rozhraní API pro zadávání paměti můžete číst a zapisovat položky.
Konverzace je stav konverzace kompatibilní s OpenAI – zprávy a volání nástroje – založené na úložišti paměti a připnuté k oboru. Pomocí rozhraní API pro konverzaci můžete vytvářet a spravovat konverzace a jejich položky.

Předpoklady

Vygenerujte token OAuth pomocí rozhraní příkazového řádku Databricks k volání rozhraní API:

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

Rozhraní API úložiště paměti

Úložiště paměti je zabezpečitelný katalog Unity, který funguje jako kontejner pro položky paměti. Úložiště paměti používají tříúrovňové pojmenování: catalog.schema.memory_store_name.

Operation	Koncový bod	Požadovaná oprávnění
Vytvářet	`POST /api/2.1/unity-catalog/memory-stores`	`CREATE MEMORY STORE` v nadřazeném schématu
Získejte	`GET /api/2.1/unity-catalog/memory-stores/{full_name}`	`READ MEMORY STORE` v obchodě
Seznam	`GET /api/2.1/unity-catalog/memory-stores`	`USE SCHEMA` v nadřazeném schématu
Aktualizace	`PATCH /api/2.1/unity-catalog/memory-stores/{full_name}`	`MANAGE` v obchodě
Vymazat	`DELETE /api/2.1/unity-catalog/memory-stores/{full_name}`	`MANAGE` v obchodě

Vytvoření úložiště paměti

Vytvoří nové úložiště paměti pod nadřazeným schématem.

Koncový bod:POST /api/2.1/unity-catalog/memory-stores
Požadovaná oprávnění: CREATE MEMORY STORE u nadřazeného schématu

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

Pole žádosti:

Pole	Typ	Povinné	Description
`name`	`string`	Yes	Krátký název úložiště paměti. Musí odpovídat `[A-Za-z0-9_-]+`1–255 znakům. Jedinečné v rámci nadřazeného schématu.
`catalog_name`	`string`	Yes	Název nadřazeného katalogu.
`schema_name`	`string`	Yes	Název nadřazeného schématu vzhledem k katalogu
`description`	`string`	No	Popis úložiště paměti čitelný pro člověka.

Získání úložiště paměti

Načte úložiště paměti podle plně kvalifikovaného názvu ze tří částí.

Koncový bod:GET /api/2.1/unity-catalog/memory-stores/{full_name}
Požadovaná oprávnění: READ MEMORY STORE v úložišti

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

Výpis úložišť paměti

Zobrazí seznam úložišť paměti ve schématu. Výsledky jsou filtrovány tak, aby volající mohl číst.

Koncový bod:GET /api/2.1/unity-catalog/memory-stores
Požadovaná oprávnění: USE SCHEMA u nadřazeného schématu

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

Parametry dotazu:

Parameter	Typ	Povinné	Description
`catalog_name`	`string`	Yes	Název nadřazeného katalogu
`schema_name`	`string`	Yes	Název nadřazeného schématu
`page_token`	`string`	No	Token stránkování z předchozí odpovědi
`max_results`	`integer`	No	Maximální počet obchodů na stránku Výchozí hodnota je 100, max. 1000.

Aktualizace úložiště paměti

Aktualizuje proměnlivá pole v úložišti paměti. description V současné době je pouze proměnlivá.

Koncový bod:PATCH /api/2.1/unity-catalog/memory-stores/{full_name}
Požadovaná oprávnění: MANAGE v úložišti

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

Odstranění úložiště paměti

Odstraní úložiště paměti a všechny jeho položky paměti.

Koncový bod:DELETE /api/2.1/unity-catalog/memory-stores/{full_name}
Požadovaná oprávnění: MANAGE v úložišti

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

Pole odpovědi úložiště paměti

Pole	Typ	Description
`name`	`string`	Krátký název úložiště paměti.
`catalog_name`	`string`	Název nadřazeného katalogu
`schema_name`	`string`	Název nadřazeného schématu
`description`	`string`	Popis čitelný pro člověka.
`owner`	`string`	Uc principal, který vlastní obchod. Nastaví se při vytvoření.
`full_name`	`string`	Třídílný plně kvalifikovaný název: `catalog.schema.name`.
`memory_store_id`	`string`	UUID přiřazené serverem.
`securable_type`	`string`	Vždy `MEMORY_STORE`.
`created_at`	`integer`	Doba vytváření v milisekundách unixové epochy
`updated_at`	`integer`	Čas poslední aktualizace v unixových milisekundách.
`created_by`	`string`	Objekt zabezpečení, který vytvořil úložiště.

Rozhraní API pro zadávání paměti

Položky paměti jsou jednotlivé části obsahu uložené v úložišti paměti. Každá položka je identifikována oborem a cestou: scope je klíč oddílu, který volající přiřadí (například ID koncového uživatele) a path je měkká cesta v tomto oboru, která musí začínat /memories/ (například /memories/preferences.md). scope vyžaduje se při každém požadavku na zadání paměti.

Operation	Koncový bod	Požadovaná oprávnění
Vytvářet	`POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`WRITE MEMORY STORE` v obchodě
Získejte	`GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries:get`	`READ MEMORY STORE` v obchodě
Seznam	`GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`READ MEMORY STORE` v obchodě
Aktualizace	`PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`WRITE MEMORY STORE` v obchodě
Vymazat	`DELETE /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`WRITE MEMORY STORE` v obchodě
Hledání	`POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries:search`	`READ MEMORY STORE` v obchodě

Vytvoření položky paměti

Vytvoří novou položku paměti v úložišti paměti.

Koncový bod:POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries?scope=<scope>
Požadovaná oprávnění: WRITE MEMORY STORE v úložišti

scope je parametr dotazu; text požadavku je samotná položka.

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

Pole žádosti:

Pole	V	Typ	Povinné	Description
`scope`	dotaz	`string`	Yes	Rozdělte položku do oddílu přiřazené volajícím (například ID koncového uživatele).
`path`	body	`string`	Yes	Soft path identifying the entry within the scope. Musí začínat na `/memories/`. Neměnný
`contents`	body	`string`	No	Textový obsah volného formátu.
`description`	body	`string`	No	Jednořádkový souhrn položky paměti. Slouží jako háček indexu v odpovědích seznamu.

Získání položky paměti

Načte jednu položku paměti podle scope a path.

Koncový bod:GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries:get
Požadovaná oprávnění: READ MEMORY STORE v úložišti

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

Výpis položek paměti

Vypíše položky paměti v oboru.

Koncový bod:GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries
Požadovaná oprávnění: READ MEMORY STORE v úložišti

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

Parametry dotazu:

Parameter	Typ	Povinné	Description
`scope`	`string`	Yes	Rozsah (oddíl) pro položky seznamu z.
`path_prefix`	`string`	No	Vrátí pouze položky, jejichž cesta začíná touto předponou.
`page_size`	`integer`	No	Maximální počet položek na stránku Server zasádí velikost stránky.
`page_token`	`string`	No	Token stránkování z předchozí odpovědi

Vypsat odpovědi vynechat contents (pouze metadata) a zahrnout next_page_token , když zbývá více stránek.

Aktualizace položky paměti

Použije jednu operaci úprav na existující položku contentsidentifikovanou uživatelem scope a path. Zadejte přesně jednu z str_replacehodnot , insertnebo replace_all. description je upravitelný: nastavte ho tak, aby nahradil popis položky, nebo ho vynecháte, aby se popis nezměnil.

Koncový bod:PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries
Požadovaná oprávnění: WRITE MEMORY STORE v úložišti

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

Upravit operace (nastavit přesně jednu):

Operation	Fields	Behavior
`replace_all`	`contents`	Přepište celý obsah položky.
`str_replace`	`old_str`, `new_str`	Nahraďte jeden výskyt `old_strnew_str` (musí se shodovat přesně jednou).
`insert`	`insert_line`, `insert_text`	Vložit `insert_text`; `insert_line` 0 = nahoře, vynecháno = připojit na konec.

Odstranění položky paměti

Odstraní položku paměti identifikovanou uživatelem scope a path.

Koncový bod:DELETE /api/2.1/unity-catalog/memory-stores/{full_name}/entries
Požadovaná oprávnění: WRITE MEMORY STORE v úložišti

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

Prohledávání položek paměti

Prohledává položky paměti podle klíčových slov v polích cesty, obsahu a popisu.

Koncový bod:POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries:search
Požadovaná oprávnění: READ MEMORY STORE v úložišti

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

Pole požadavku: scope (povinné), (povinné), querypath_prefix (volitelné), top_k (volitelné; výchozí hodnota je 10, max. 50).

Pole odpovědi na položku paměti

Pole	Typ	Description
`path`	`string`	Soft path of the entry within its scope.
`contents`	`string`	Text paměti. Vynecháno v odpovědích seznamu.
`description`	`string`	Jednořádkový souhrn.
`scope`	`string`	Rozsah (oddíl) položka patří.
`memory_store_name`	`string`	Třídílný název nadřazeného úložiště paměti.
`has_contents`	`boolean`	Zda položka obsahuje neprázdné `contents` (užitečné v seznamu).
`create_time`	`string`	Časové razítko vytvoření (RFC 3339).
`update_time`	`string`	Časové razítko poslední aktualizace (RFC 3339).

Rozhraní API pro konverzaci

Konverzace ukládá stav konverzace kompatibilní s OpenAI – zprávy, volání nástrojů a další položky – v úložišti paměti v rámci jednoho oboru. Při konverzaci se agent zachová a znovu načte stav relace na straně serveru. Každou konverzaci vytvoříte v úložišti paměti (název tří částí) a scopeoperace konverzace vyžadují stejná oprávnění jako podkladové úložiště paměti.

Operation	Koncový bod	Požadovaná oprávnění
Vytvářet	`POST /api/2.1/unity-catalog/conversations`	`WRITE MEMORY STORE` v obchodě
Získejte	`GET /api/2.1/unity-catalog/conversations/{conversation_id}`	`READ MEMORY STORE` v obchodě
Aktualizace	`POST /api/2.1/unity-catalog/conversations/{conversation_id}`	`WRITE MEMORY STORE` v obchodě
Vymazat	`DELETE /api/2.1/unity-catalog/conversations/{conversation_id}`	`WRITE MEMORY STORE` v obchodě

Vytvoření konverzace

Vytvoří konverzaci vázanou na úložiště paměti a rozsah.

Koncový bod:POST /api/2.1/unity-catalog/conversations
Požadovaná oprávnění: WRITE MEMORY STORE v úložišti

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

Pole žádosti:

Pole	Typ	Povinné	Description
`memory_store`	`object`	Yes	Paměť ukládá konverzaci.
`memory_store.name`	`string`	Yes	Třídílný plně kvalifikovaný název úložiště paměti: `catalog.schema.memory_store`.
`scope`	`object`	Yes	Rozsah konverzace je připnutý.
`scope.kind`	`string`	Yes	Druh oboru, například `user` .`user_defined`
`scope.value`	`string`	Yes	Hodnota oboru specifická pro konkrétní typ, například ID koncového uživatele.
`metadata`	`object`	No	Metadata klíč-hodnota řízená volajícím Až 16 klíčů; klíče až 64 znaků, hodnoty až 512 znaků.
`items`	`array`	No	Počáteční položky konverzace OpenAI pro zahájení konverzace (až 20). Položky bez položky `type` jsou uloženy jako položky zprávy.

Získání konverzace

Načte konverzaci podle ID.

Koncový bod:GET /api/2.1/unity-catalog/conversations/{conversation_id}
Požadovaná oprávnění: READ MEMORY STORE v úložišti

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

Aktualizace konverzace

Aktualizuje konverzaci metadata.

Koncový bod:POST /api/2.1/unity-catalog/conversations/{conversation_id}
Požadovaná oprávnění: WRITE MEMORY STORE v úložišti

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

Odstranění konverzace

Odstraní konverzaci a její položky.

Koncový bod:DELETE /api/2.1/unity-catalog/conversations/{conversation_id}
Požadovaná oprávnění: WRITE MEMORY STORE v úložišti

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

Pole odpovědi na konverzaci

Pole	Typ	Description
`id`	`string`	ID konverzace přiřazené serverem
`object`	`string`	Vždy `conversation`.
`created_at`	`integer`	Doba vytváření v unixových epoch sekundách.
`metadata`	`object`	Metadata klíč-hodnota zadané volajícím

Rozhraní API pro položky konverzace

Položky jsou jednotlivé zprávy a volání nástrojů v rámci konverzace. Sledují tvar položek konverzace OpenAI a používají stránkování kompatibilní s OpenAI (after, limit, has_more).

Operation	Koncový bod	Požadovaná oprávnění
Vytvoření položek	`POST /api/2.1/unity-catalog/conversations/{conversation_id}/items`	`WRITE MEMORY STORE` v obchodě
Získej položku	`GET /api/2.1/unity-catalog/conversations/{conversation_id}/items/{item_id}`	`READ MEMORY STORE` v obchodě
Položky seznamu	`GET /api/2.1/unity-catalog/conversations/{conversation_id}/items`	`READ MEMORY STORE` v obchodě
Odstranit položku	`DELETE /api/2.1/unity-catalog/conversations/{conversation_id}/items/{item_id}`	`WRITE MEMORY STORE` v obchodě

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-07-01

Referenční informace k rozhraní API pro paměť

Předpoklady

Rozhraní API úložiště paměti

Vytvoření úložiště paměti

Získání úložiště paměti

Výpis úložišť paměti

Aktualizace úložiště paměti

Odstranění úložiště paměti

Pole odpovědi úložiště paměti

Rozhraní API pro zadávání paměti

Vytvoření položky paměti

Získání položky paměti

Výpis položek paměti

Aktualizace položky paměti

Odstranění položky paměti

Prohledávání položek paměti

Pole odpovědi na položku paměti

Rozhraní API pro konverzaci

Vytvoření konverzace

Získání konverzace

Aktualizace konverzace

Odstranění konverzace

Pole odpovědi na konverzaci

Rozhraní API pro položky konverzace

Váš názor

Další materiály