管理代理會話

管理代理會話為你的代理提供一個持久且不依賴框架的會話狀態儲存：代理或框架在一次互動中所保持的狀態。 最常見的是對話歷史，即代理在回合開始時讀取並附加的訊息、工具呼叫及結果的有序逐字稿。 它也可以是框架為互動而持久保存的任何其他狀態，例如 LangGraph 圖。 Azure Databricks 會把它儲存在 Lakebase 裡，並幫你管理儲存，所以你不需要自己建置或操作資料庫。

當你想要執行下列操作時，請使用受管理的工作階段：

• 持續保留客服人員的對話紀錄，讓它能在重啟時存活，之後也能繼續。
• 在後續訊息中重建完整脈絡（包括工具呼叫與推理）。
• 直接在你自己的介面中列出、繼續，以及從過去的對話另開分支。

受管理會話保持單一互動狀態（短期、會話中狀態）。 若要使用可在跨對話間持續保留的長期記憶，請使用受管理的代理記憶。

管理式會談的運作方式

管理式會議分為三個層級：

• 工作階段存放區是以工作區為範圍、用於存放代理工作階段的容器。 建立存放區時，系統會自動佈建作為後端支援的 Lakebase 儲存體。 你選擇一個獨特的 session_store_name工作空間。
• 會話是商店內一個持久互動（通常是對話線程）。 工作階段是根據下列項目識別的：
  • actor_id （必需）：會話所屬者，例如終端使用者或其他代理。 它會將同一主題的所有會議分組，讓你可以一起列出和篩選。 當您建置每位使用者專屬的應用程式時，請將 actor_id 設為該使用者的 ID（例如，來自您應用程式驗證流程且已驗證的終端使用者身分），讓每位使用者的工作階段維持歸在同一組。 從受信任的應用程式上下文設定，絕不要用模型或使用者提供的值。
  • session_id （可選）：為互動設置來電者選擇的 ID。 如果你省略它，服務會產生一個。
  • parent_session_id （可選）：將工作階段連結到它所分支自的工作階段，用來表示分支對話。
• 會話項目是會話排序歷史中的一個項目。 每個項目都包含一個不透明、與 JSON 相容 data 的值，例如訊息、工具呼叫、工具結果或推理區塊。 Azure Databricks 會將每個項目分配 an item_id 和 acreate_time，且不會檢查或驗證其內容。 項目一旦被附加後即為不可更改。

該服務會維持工作階段項目的確定性順序，並針對工作階段存放區授權每一項作業。

要求

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

開始

這些範例是為支援代理設置受管理的會話：他們建立會話庫，為某次對話啟動會話，新增對話回合，並在後續請求時回讀歷史。 選擇最適合你專案的客戶。

AgentKit SDK

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

1. 安裝 AgentKit SDK：

   pip install databricks-agentbricks
   

2. 建立一個工作階段儲存區，然後為單一對話啟動一個工作階段。 actor_id 是對話所屬的對象;可選 session_id 性則唯一識別此對話：

   from databricks.sdk import WorkspaceClient
   from databricks_agentkit import AgentKitClient
   
   client = AgentKitClient(WorkspaceClient())
   session_store = client.session_stores.create("support-agent-sessions")
   session = session_store.add(actor_id="customer-123", session_id="case-456")
   

3. 在代理程式執行時，追加對話回合。 每個項目皆為任何 JSON 相容值：

   session.append_items(
       [
           {"type": "message", "role": "user", "content": "I need help with my cluster."},
           {"type": "message", "role": "assistant", "content": "Let's take a look."},
       ]
   )
   

4. 在後續請求時，重新載入會話並閱讀其完整歷史以重建上下文：

   session = session_store.get("case-456")
   # Request chronological order; list_items defaults to newest-first and auto-pages.
   history = [item.data for item in session.list_items(order_by="create_time asc")]
   

REST API

用戶端在 /api/2.0/agents/session-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/session-stores?session_store_name=support-agent-sessions" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
     -d '{"description": "Support agent conversation history"}'
   

3. 開始一個用於單一對話的工作階段。 actor_id 表示其所屬對象；session_id 可唯一識別這段對話：

   curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions/sessions?session_id=case-456" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
     -d '{"actor_id": "customer-123"}'
   

4. 在代理程式執行時附加一個對話回合：

   curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions/sessions/case-456/items:append" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
     -d '{"items": [{"data": {"type": "message", "role": "user", "content": "I need help with my cluster."}}]}'
   

5. 按時間順序回顧歷史以重建背景：

   curl -G "https://${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions/sessions/case-456/items" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" --data-urlencode "order_by=create_time asc"
   

客戶端也支援移除最新項目、清除會話項目，以及將對話分支成獨立副本（可選擇性地切換到特定項目）。 刪除包含子工作階段的工作階段時，需要使用 force 選項，才能將刪除作業級聯至這些子工作階段（例如，session.delete(force=True)）。

用受管理的會話來支援代理框架的會話

像 OpenAI Agents SDK 和 Claude Agent SDK 這類代理框架，會在執行開始時讀取對話歷史，並在結束時附加新項目。 會話儲存會直接映射到該模式：

範圍與存取

受管理的工作階段會將工作階段項目儲存為不透明且與 JSON 相容的值：服務會將您的代理程式或框架附加到其中的任何內容持久化並原樣返回，而不會加以解讀。 它不會將執行控制資源如執行、檢查點或核准等作為一級概念加入，儘管序列化此類狀態的框架可以將其持久化為項目。

工作階段存放區以工作區為範圍，且存取權限是在存放區層級授與。 和actor_idmetadata欄位僅支援分組與過濾;它們不授予或限制存取權限。 應從受信任的應用程式內容設定 actor_id，而非使用模型或使用者提供的值。

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

受管理會話與 受管理記憶體 是獨立的。 刪除工作階段或工作階段存放區，並不會刪除保留在記憶體存放區中的記憶。

下一步

• 管理代理記憶體
• 代理 API 參考