メモリ API リファレンス

このページは、 マネージド エージェント メモリの REST API リファレンスです。 マネージド メモリのエンドポイント、要求フィールド、応答フィールドについて説明します。

• メモリ ストアは、メモリ エントリのコンテナーとして機能するセキュリティ保護可能な Unity カタログです。 メモリ ストア API を使用して、ストアを作成および管理します。
• メモリ エントリは、メモリ ストア内に格納されている個々のコンテンツです。 メモリ エントリ API を使用して、エントリの読み取りと書き込みを行います。
• 会話は、メモリ ストアによってサポートされ、スコープにピン留めされた OpenAI 互換の会話状態 (メッセージとツール呼び出し) です。 Conversation API を使用して、会話とそのアイテムを作成および管理します。

前提条件

Databricks CLI を使用して OAuth トークンを生成し、API を呼び出します。

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

メモリ ストア API

メモリ ストアは、メモリ エントリのコンテナーとして機能するセキュリティ保護可能な Unity カタログです。 メモリ ストアでは、 catalog.schema.memory_store_nameという 3 レベルの名前付けが使用されます。

メモリ ストアを作成する

親スキーマの下に新しいメモリ ストアを作成します。

• エンドポイント:POST /api/2.1/unity-catalog/memory-stores
• 必要な特権: 親スキーマに対するCREATE MEMORY STORE

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

要求フィールド:

メモリ ストアを取得する

3 部構成の完全修飾名でメモリ ストアを取得します。

• エンドポイント:GET /api/2.1/unity-catalog/memory-stores/{full_name}
• 必要な特権: ストアでのREAD MEMORY STORE

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

メモリ ストアを一覧表示する

スキーマ内のメモリ ストアを一覧表示します。 結果は、呼び出し元が読み取ることができる格納にフィルター処理されます。

• エンドポイント:GET /api/2.1/unity-catalog/memory-stores
• 必要な特権: 親スキーマに対するUSE 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}"

クエリ パラメーター:

メモリ ストアを更新する

メモリ ストアの変更可能なフィールドを更新します。 現在、変更可能なのは description だけです。

• エンドポイント:PATCH /api/2.1/unity-catalog/memory-stores/{full_name}
• 必要な特権: ストアでのMANAGE

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

メモリ ストアを削除する

メモリ ストアとそのすべてのメモリ エントリを削除します。

• エンドポイント:DELETE /api/2.1/unity-catalog/memory-stores/{full_name}
• 必要な特権: ストアでのMANAGE

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

メモリ ストアの応答フィールド

メモリ エントリ API

メモリ エントリは、メモリ ストア内に格納されている個々のコンテンツです。 各エントリは 、スコープ と パスによって識別されます。 scope は呼び出し元が割り当てるパーティション キー (エンド ユーザー ID など) であり、 path はそのスコープ内のソフト パスであり、 /memories/ で始まる必要があります (たとえば、 /memories/preferences.md)。 scope は、すべてのメモリ エントリ要求で必要です。

メモリ エントリを作成する

メモリ ストアに新しいメモリ エントリを作成します。

• エンドポイント:POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries?scope=<scope>
• 必要な特権: ストアでのWRITE MEMORY STORE

scope はクエリ パラメーターです。要求本文はエントリ自体です。

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

要求フィールド:

メモリ エントリを取得する

scopeとpathで 1 つのメモリ エントリを取得します。

• エンドポイント:GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries:get
• 必要な特権: ストアでのREAD MEMORY STORE

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

メモリ エントリを一覧表示する

スコープ内のメモリ エントリを一覧表示します。

• エンドポイント:GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• 必要な特権: ストアでのREAD MEMORY STORE

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

クエリ パラメーター:

一覧の応答では、 contents が省略され (メタデータのみ)、さらにページが残っている場合は next_page_token が含まれます。

メモリ エントリを更新する

既存のエントリの contentsに 1 つの編集操作を適用します。これは、 scope と pathによって識別されます。 str_replace、insert、またはreplace_allのいずれかを指定します。 description は編集可能です。エントリの説明を置き換えるか、説明を変更せずに省略するように設定します。

• エンドポイント:PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• 必要な特権: ストアでのWRITE MEMORY STORE

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

編集操作 (厳密に 1 つ設定):

メモリ エントリを削除する

scopeとpathで識別されるメモリ エントリを削除します。

• エンドポイント:DELETE /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• 必要な特権: ストアでのWRITE MEMORY STORE

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

メモリ エントリを検索する

パス、コンテンツ、および説明フィールド間でキーワードでメモリ エントリを検索します。

• エンドポイント:POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries:search
• 必要な特権: ストアでのREAD MEMORY STORE

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

要求フィールド: scope (必須)、 query (必須)、 path_prefix (省略可能)、 top_k (省略可能、既定値は 10、最大 50)。

メモリ エントリの応答フィールド

Conversation API

会話では、OpenAI と互換性のある会話状態 (メッセージ、ツール呼び出し、その他の項目) が 1 つのスコープのメモリ ストアに格納されます。 会話を使用すると、エージェントはセッション状態サーバー側を保持して再読み込みします。 メモリ ストア (3 部構成の名前) と scopeに対して各会話を作成します。会話操作には、基になるメモリ ストアと同じ特権が必要です。

会話を作成する

メモリ ストアとスコープにバインドされた会話を作成します。

• エンドポイント:POST /api/2.1/unity-catalog/conversations
• 必要な特権: ストアでのWRITE MEMORY STORE

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

要求フィールド:

会話を取得する

ID で会話を取得します。

• エンドポイント:GET /api/2.1/unity-catalog/conversations/{conversation_id}
• 必要な特権: ストアでのREAD MEMORY STORE

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

会話を更新する

会話の metadataを更新します。

• エンドポイント:POST /api/2.1/unity-catalog/conversations/{conversation_id}
• 必要な特権: ストアでのWRITE MEMORY STORE

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

会話を削除する

会話とそのアイテムを削除します。

• エンドポイント:DELETE /api/2.1/unity-catalog/conversations/{conversation_id}
• 必要な特権: ストアでのWRITE MEMORY STORE

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

会話の応答フィールド

会話アイテム API

アイテムは、会話内の個々のメッセージとツール呼び出しです。 OpenAI 会話項目の図形に従い、OpenAI 互換の改ページ位置 (after、 limit、 has_more) を使用します。