代理程式的受管理記憶體

管理代理記憶體賦予代理人員持久且長期的記憶，能在對話中持續存在。 Azure Databricks 將記憶體儲存在 Lakebase 中，並幫你管理儲存、索引和語意搜尋，讓你的代理程式能記住使用者偏好、過去決策和累積的上下文，而不必你操作資料庫。

當你希望代理程式能夠做到以下事項時，請使用受管理記憶體：

• 記住使用者偏好、事實與決策，跨越不同對話。
• 根據客服在先前會議中學到的內容，個人化回應。
• 在經紀人與專案間分享累積的知識。
• 隨著時間提升準確度與效率。

管理記憶體可搭配任何框架架構的代理程式運作。 若要在單一互動中建立短期對話歷史，請使用 管理代理會話。

管理記憶體的運作方式

管理式記憶有兩個層級：

• 記憶儲存區是代理記憶的工作區範圍容器。 建立存放區時，會自動佈建作為後端的 Lakebase 儲存體。 你用它的 display_name名稱來稱呼商店。
• 記憶體條目是商店中單一的內容。 每個條目都有自由格式文字 content、用於檢索的短訊 description ，以及一組用以組織和分割的欄位：
  • actor_id （必需）：記憶的主人，例如終端使用者或其他代理。
  • session_id （可選）：記錄記憶體擷取的會話，用於追蹤與來源確認。 若記憶體未繫結至特定工作階段，請將其留空。
  • path（必填）：類似檔案系統的路徑，用於整理 actor 內的項目，例如 /preferences/response-style.md。

一個項目可由 session_id、path 和 actor_id 的組合唯一識別。

檢索

記憶體擷取方式有兩種：

• 列出演員的條目，可選擇依據 session_id 或 path 前綴進行篩選。 使用此功能瀏覽或呈現代理程式所知內容的索引。
• 使用自然語言查詢搜尋某位演員的條目。 搜尋會回傳以全文相關性分數（BM25）排名的最具相關性條目。

Requirements

• 安裝 Python 3.10 或更高版本，使用 AgentKit SDK。 AgentKit SDK 是 Databricks Python 用戶端，用於代理 API，以下範例即使用此服務。 你也可以直接從任何語言呼叫 REST API，不需要 Python 要求。

開始

這些範例為支援代理設定管理記憶體：建立記憶體儲存，儲存使用者偏好，並在後續對話中調回。 選擇最適合你專案的客戶。 記憶體儲存 display_name 必須是3到56個字元，開頭是小寫字母，結尾是字母或數字，且僅包含小寫字母、數字和連字號。

AgentKit SDK

AgentKit SDK 是 Databricks 的 Python 用戶端，用於代理 API，並隨 databricks-agentbricks 套件發佈。 它會用 Databricks SDK WorkspaceClient進行驗證。

1. 安裝 AgentKit SDK：

   pip install databricks-agentbricks
   

2. 為你的經紀人建立一個記憶儲存庫。 AgentKitClient 使用您的 WorkspaceClient 憑證進行驗證：

   from databricks.sdk import WorkspaceClient
   from databricks_agentkit import AgentKitClient
   
   client = AgentKitClient(WorkspaceClient())
   memory_store = client.memory_stores.create("support-agent-memory")
   

3. 在代理得知關於使用者的持久性資訊後，儲存記憶。 actor_id 表示這是誰的記憶，path 將其組織在該行為者內，而 description 則提升擷取效率：

   memory_store.add(
       actor_id="user-123",
       path="/preferences/communication.md",
       content="Prefers email over phone. Timezone: PST. Enterprise subscription.",
       description="User 123 communication preferences",
   )
   

4. 用自然語言搜尋回想使用者在後續對話中的記憶：

   results = memory_store.search(actor_id="user-123", query="communication preferences", limit=10)
   

REST API

用戶端在 /api/2.0/agents/memory-stores 之下呼叫 REST API。 對於 Python 以外的語言，可直接呼叫。

1. 使用 Databricks CLI 產生 OAuth 代幣：

   databricks auth login --host ${DATABRICKS_HOST}
   export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)
   

2. 為你的代理人建立記憶儲存：

   curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
     -d '{"display_name": "support-agent-memory", "description": "Support agent memory"}'
   

3. 為使用者儲存一個記憶體條目。 actor_id 代表這是誰的記憶，path 進行組織，而 description 改善檢索：

   curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
     -d '{"actor_id": "user-123", "path": "/preferences/communication.md", "content": "Prefers email over phone.", "description": "Communication preferences"}'
   

4. 用自然語言搜尋回想使用者的記憶：

   curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries:search" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
     -d '{"actor_id": "user-123", "query": "communication preferences"}'
   

為你的代理加入記憶功能

讓代理決定何時儲存並召回記憶體，將客戶端操作包裝成工具，並在系統提示字元中指示代理何時使用。 在受信任的應用程式碼中，根據已驗證的終端使用者身分設定 actor_id。 絕不要讓模型決定要讀寫哪個記憶體。

以下範例將 Get started 的 AgentKit SDK memory_store 包裝成 OpenAI Agents SDK 的工具。

from agents import Agent, function_tool

def make_memory_tools(memory_store, actor_id: str):
    @function_tool
    def search_memory(query: str) -> str:
        """Search long-term memory for relevant facts about the user."""
        results = memory_store.search(actor_id=actor_id, query=query, limit=10)
        return "\n\n".join(f"{r.memory.path}: {r.memory.content}" for r in results) or "No memory found."

    @function_tool
    def save_memory(path: str, content: str, description: str = "") -> str:
        """Save a durable, long-term memory about the user."""
        memory_store.add(actor_id=actor_id, path=path, content=content, description=description)
        return f"Saved memory at {path}"

    return [search_memory, save_memory]

agent = Agent(
    name="Support agent",
    instructions="Save durable user preferences and recall them when relevant.",
    tools=make_memory_tools(memory_store, actor_id="user-123"),
)

同樣的模式也適用於 Claude Agent SDK 及其他框架：將儲存庫的搜尋與新增操作包裝成框架的工具類型。

分割區與安全記憶體

在商店裡， actor_id 就是你如何分辨誰的記憶屬於誰。 每個清單和搜尋都限定在單一 actor_id 內，因此請選擇符合你的代理需要記住內容的策略：

• 每個使用者的私有記憶體： 設定 actor_id 為已驗證的最終使用者身份。 每個使用者都有自己的分割區，代理程式只會呼叫該使用者的條目。
  • 範例： 客服人員會記住一位使用者的溝通偏好和過去的工單。
• 群組共享記憶體：設定actor_id為你選擇的固定鍵，例如團隊、專案或組織 ID。 每個人都閱讀和書寫相同的記憶。
  • 範例： 一位團隊代理記得一份公司術語和內部慣例的共享詞彙表。
• 記憶體被其他東西分割：從你自己的值開始建立actor_id，例如租戶 ID 或複合值user:project。
  • 範例： 一個多租戶應用程式設定 actor_id 為 ， {tenant}:{user} 讓每個客戶的使用者彼此保持隔離。

在你的應用程式碼中，根據受信任的呼叫端內容設定 actor_id：若為每位使用者專屬的記憶體，請使用經驗證的終端使用者身分；若為共享記憶體，則使用受信任的團隊或專案金鑰。 絕對不要讓模特兒自己決定。 如果你的策略取決於終端使用者身分，則應拒絕未附帶該身分的請求，而不是改為使用共用的 actor_id。

要讓另一個主體，例如你代理的服務主體，使用一個儲存裝置，就透過該儲存裝置的授權操作memory_store.grant_permission(principal_id) （在 AgentKit SDK 中）授權它存取。

Limitations

• 管理記憶體僅提供長期記憶。 關於短期對話歷史，請參見管理代理會話。
• 搜尋是一種按相關性排序的全文（BM25）作業，會回傳前 N 筆結果，最多可達 100 筆。 它不支援分頁或向量相似性搜尋。
• 存取控制是在商店層級強制執行的。 不支援每個項目及每個角色的存取控制。
• display_name商店創建後是不可更改的。 只有 description 可以更新。

下一步

• 管理代理會話
• 代理 API 參考