代理程式的受管理記憶體

Important

這項功能位於測試版 (Beta) 中。工作區管理員可以從 「預覽 」頁面控制對此功能的存取。請參閱管理 Azure Databricks 預覽。

管理代理記憶體讓你的代理在對話中擁有長期記憶。 Azure Databricks 負責管理基礎架構並隔離每個範圍的記憶體，讓你不必自己管理儲存或分割。

透過管理記憶體，您的代理人員可以：

記住使用者偏好、過去決策，以及對話中累積的背景資訊。
請用 Unity 目錄治理來保護這些知識。
跨代理與專案共享記憶體。
隨著時間提升他們的準確度與效率。

Requirements

已啟用 Unity Catalog 的 Databricks 工作區。
父 CREATE MEMORY STORE 結構有權建立記憶體儲存。

管理記憶體的運作方式

管理式記憶有兩個層級：

記憶體存放區是 Unity Catalog 的一種可保護物件，可作為記憶體項目的容器。記憶體儲存繼承與其他 Unity 目錄資產相同的治理、存取控制與血統。
記憶體條目是儲存在記憶體儲存中的單一內容。每個條目都由範圍和路徑識別。作用域決定該條目屬於誰的記憶，路徑則組織作用域內的條目，類似檔案路徑（例如， /memories/preferences.md）。

Scope

範圍是你如何將記憶體設為私人給某個使用者，或是跨群組共享。你的應用程式在每次讀寫時都設定一個範圍，搜尋只會回傳具有相同範圍的條目。選擇符合經紀人需要記住的策略：

每個使用者的私有記憶體： 將範圍設定為已驗證的最終使用者身份。每個使用者都有自己的分割區，只能看到自己的項目。這個數值 user_client 會幫你解析最終使用者的 ID。
- 範例： 客服人員會記住一位使用者的溝通偏好和過去的工單。
團體共享記憶： 將範圍設定為你選擇的固定鍵，例如組織、團隊或專案ID。每個使用者閱讀和書寫的記憶都一樣。
- 範例： 團隊代理人記得公司用語和內部政策的共同詞彙表。
記憶被其他東西分割： 從你自己的值（例如租戶 ID 或 user_id:project 合成值）來建立範圍。
- 範例： 多租戶應用程式會將每位客戶的記憶體分開，或是每個專案中將單一使用者的記憶體隔離。

單一代理人可以在一次對話中結合多種策略。例如，它可以在同一請求中讀取使用者的私人記憶體與共享團隊記憶體。

在你的應用程式碼中設定範圍，依據請求無法竄改的受信任呼叫端內容：每位使用者的記憶體使用來自 OBO 權杖的已驗證終端使用者身分，而共用記憶體則使用受信任的租戶、團隊或專案金鑰。絕對不要讓模特兒自己決定。如果你的範圍策略取決於終端使用者身分，請拒絕沒有終端使用者身分的請求，而不要改用共享範圍。這個 managed-memory 技能會引導你完成這個設定。

Scope 會將記憶分開，但不會讓你進入商店。呼叫端仍需要具備 READ MEMORY STORE 或 WRITE MEMORY STORE 權限，才能開啟它。請參見記憶體存取控制。

Warning

範圍是使用者之間的隔離邊界，但並非存取控制。應用程式服務主體可以讀取所有範圍，因此請相應地保護其憑證。

代理人保存與回憶的內容

管理記憶體提供記憶體儲存及讀寫條目的 API。你的應用程式控制代理程式儲存什麼、何時擷取記憶體，以及如何使用這些結果。

在代理的系統提示中定義此行為：指示代理要儲存哪些持久資訊，以及何時取回。 managed-memory技能與範本使此系統提示保持為常數，名為 MEMORY_INSTRUCTIONS。權限範圍是在受信任的應用程式程式碼中另外設定的，絕不會由模型選擇。

讓措辭符合你的範圍策略。以下是每個使用者策略的範例：

You have durable, cross-session memory about whoever (or whatever) this conversation is scoped to. Use it deliberately, not by reflex.

Recall whenever the answer is about the user or calls for personalized information — anything that might draw on preferences, decisions, or workflows they've shared before — and you don't already have it from this conversation; also list once before saving, to find the right existing topic. Don't tell the user you don't know their preferences without checking — list_memories first. Skip memory only when the answer truly doesn't depend on who's asking (general knowledge, math, coding) or you already have what you need. A `[has_contents]` entry has a body to get_memory; one without is fully captured by its description. Open a memory with get_memory before you state its specifics, and never assert a fact that isn't stored — if nothing relevant is stored, just answer without it. Don't re-list what you've already seen this turn.

Save only what will still matter in a future, unrelated conversation — a stable preference, fact, decision, or ongoing project the user actually stated or decided. Don't save your own suggestions or guesses, passing chatter, secrets, or anything scoped to this chat ("for now", a one-off label).
- Write each memory so it stands on its own out of context, under one broad, stable /memories/... topic per subject with the specifics inside it.
- Check the list first and update_memory an existing topic instead of minting a near-duplicate.
- For a very broad question that touches many memories, summarize from the list's descriptions; reserve get_memory for the specific entry you actually need.
- If the user's info changes or contradicts what's stored, update or replace it rather than keeping both — but don't rewrite a memory that already says the same thing.
- delete_memory what's stale.
- Briefly tell the user whenever you save, update, or delete.

開始學習管理記憶技能

為代理程式新增管理記憶體最簡單的方法是使用 managed-memory Claude Code 技能。這個技能會幫你處理所有設定，並且能同時支援 OpenAI Agents SDK 和 LangGraph。

將這項技能融入你的專案，有兩種方式之一：

從範本開始

這項技能內含於 Databricks 應用程式範本中。使用其中一個代理人範本建立新的代理人，並在 .claude/skills/managed-memory/ 下方找到該技能。

複製範本庫：

git clone https://github.com/databricks/app-templates.git

瀏覽 app-templates，選取一個代理程式範本作為起點。例如，使用 OpenAI Agents SDK 範本：
```
cd app-templates/agent-openai-agents-sdk
```
Note

對於「進階」應用程式範本，部署後，您必須將 Lakebase Postgres 權限授予該應用程式服務主體，否則工作階段設定將會傳回 502 錯誤。
一旦技能融入你的專案，描述你想要什麼，然後你的程式助理會處理剩下的：
Tip
```
Add Databricks managed long-term memory to my agent.
```

將這項技能加入現有專案

如果你已經有經紀人專案，就把這項技能加入去。

如果技能目錄不存在，請建立：
```
mkdir -p .claude/skills/managed-memory
```
從技能目錄下載SKILL.md檔案managed-memory並存到 .claude/skills/managed-memory/。
一旦技能融入你的專案，描述你想要什麼，然後你的程式助理會處理剩下的：
Tip
```
Add Databricks managed long-term memory to my agent.
```

手動建立並使用記憶儲存

本節將展示如何在沒有 managed-memory Claude Code 技能的情況下建立並使用記憶體儲存。

以下範例為客戶支援代理設置管理記憶體，儲存使用者偏好並在後續對話中取用。

使用 Databricks CLI 產生 OAuth 令牌以呼叫 API：

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

建立記憶儲存庫來儲存你的代理人記憶：

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": "support_agent_memory",
    "catalog_name": "main",
    "schema_name": "default",
    "description": "Long-term memory for the customer support agent"
  }'

在代理程式得知某位使用者的某些資訊後，寫入一筆記憶項目。 scope 會將該項目劃分給單一使用者。使用 contents 欄位顯示完整記憶體文字，作為 description 簡短摘要，提升檢索效率：

curl -X POST \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.support_agent_memory/entries?scope=user-123" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/memories/preferences.md",
    "contents": "Prefers email communication. Timezone: PST. Has an Enterprise subscription.",
    "description": "User 123 communication preferences and account details"
  }'

在後續對話中搜尋該使用者的記憶條目，以取得代理所學到的內容：

curl -X POST \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.support_agent_memory/entries:search" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user-123",
    "query": "communication preferences"
  }'

關於完整的 REST API，包括端點、請求欄位與回應欄位，請參見記憶體 API 參考。

透過對話為客服成員增添記憶

上述 REST 工作流程直接呼叫記憶體儲存與入口 API。當你在 Azure Databricks 模型服務端點上建置代理程式時，請改用 SDK 中與 OpenAI 相容的用戶端，將記憶體存放區連線到 databricks-openai。

對話是與 OpenAI 相容的對話狀態——由訊息與工具呼叫構成的持續累積歷史記錄——以記憶體儲存體為後盾，並綁定至單一作用域。跨多個請求重複使用同一個對話，讓代理程式保有先前對話輪次的記憶。

將現有的記憶體儲存區和範圍綁定到新的對話。 memory_store.name 是儲存區的三級名稱，而 scope 會將對話的狀態分區，通常是依終端使用者劃分：

from databricks.sdk import WorkspaceClient
from databricks_openai import DatabricksOpenAI

workspace_client = WorkspaceClient()
user_id = str(workspace_client.current_user.me().id)

client = DatabricksOpenAI(workspace_client=workspace_client, use_ai_gateway=True)

conversation = client.conversations.create(
    extra_body={
        "memory_store": {"name": "main.default.support_agent_memory"},
        "scope": {"kind": "user", "value": user_id},
    },
)

將對話 ID 傳給 responses.create。代理在該範圍內讀寫綁定記憶體儲存中的對話狀態：

response = client.responses.create(
    model="databricks-gpt-5-2",
    conversation=conversation.id,
    input=[{"type": "message", "role": "user", "content": "What is the average NYC taxi price?"}],
    stream=True,
)

for event in response:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

在後續請求時重複使用 相同的 對話 ID，讓代理人記得之前的回合。不要每回合新增對話：

followup = client.responses.create(
    model="databricks-gpt-5-2",
    conversation=conversation.id,
    input=[{"type": "message", "role": "user", "content": "Restate the average taxi price you found, and how it was calculated."}],
    stream=True,
)

for event in followup:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

關於對話端點與請求欄位，請參見對話 API。

記憶體存取控制

記憶體存放區是 Unity Catalog 的可保護物件。以下權限控制存取權限：

特權	適用對象	Description
`CREATE MEMORY STORE`	父架構	在結構架構下建立新的記憶體儲存。
`READ MEMORY STORE`	記憶體存放區	讀取記憶體儲存的元資料及其條目。
`WRITE MEMORY STORE`	記憶體存放區	在儲存庫中建立、更新並刪除記憶體條目。
`MANAGE`	記憶體存放區	更新或刪除記憶體儲存本身。授權給其他使用者。
`USE SCHEMA`	父架構	列出結構描述中的記憶體存放區。

實作短期記憶

記憶體輸入 API 提供長期記憶作為工具，供代理使用。為了讓你的代理在會話中擁有管理式短期記憶，Databricks 建議將你的記憶儲存綁定到對話中。您也可以：

保留你的代理框架的會話記憶體，例如 OpenAI session= 參數或 LangGraph 檢查點。
使用自我管理的代理記憶體來儲存對話歷史。

安全性建議

Azure Databricks 提供受控的儲存、加密、隔離原語及稽核追蹤。作為應用程式開發者，Databricks 建議以下做法：

除非你有明確理由要採用不同的劃分方式（例如按專案或按帳戶劃分記憶體），否則請使用每個使用者的預設範圍（user_client）。
授予最低權限：只有您的代理人的服務負責人需要 WRITE MEMORY STORE。給予範圍有限的補助 READ MEMORY STORE ，避免給予人類使用者或大型群體的廣泛補助。
保護應用程式服務主體憑證：它是商店資料平面的鑰匙。把它當成任何高價值的服務憑證——使用短命的令牌，避免記錄，並在應用程式中加入 SSRF 防禦。

Limitations

記憶條目僅提供長期記憶。關於短期記憶與長期記憶的差異，請參見短期記憶與長期記憶。
記憶體儲存與條目僅透過 Unity Catalog REST API 建立和管理;這些 API 沒有 Python SDK。若要使用代理的記憶體儲存，請將其連接到與 OpenAI 相容用戶端的對話。請參閱透過對話為代理人新增記憶。

下一步

記憶體 API 參考

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-08-19