Important
代理人服務目前仍處於 測試階段。 Unity Gateway 已普遍可用,但其測試版功能需另行啟用。 帳號管理員必須從帳號主控台的預覽頁面開啟 Unity Gateway 測試版功能。 請參閱 管理 Azure Databricks 預覽。
在 Unity 目錄中註冊代理人,讓每個團隊的代理人都集中在一個地方。 當你將代理註冊為代理服務時,你可以將它與資料表、模型和函式一同瀏覽及探索,並使用保護其他 Unity Catalog 資產的相同授權來設定權限。
在目錄探索器中發現代理
代理服務註冊後,它會出現在目錄檔案總管中,根據建立時的結構。 要查看代理服務,使用者需要對其擁有明確的權限,例如 EXECUTE。 選擇一個代理服務以查看其名稱、描述、連線及目前權限。
Note
授權 EXECUTE 同時也讓使用者能夠呼叫代理服務,而不只是發現它。 只將該權限授予應可使用代理程式的使用者。
在建立或更新客服服務時,請使用該 comment 欄位新增描述。 此說明會顯示在 Catalog Explorer 中,幫助隊友在瀏覽時了解該代理程式的用途。
這讓組織能有一個單一地方,查看哪些代理存在、誰擁有、誰有存取權限,而無需在不同系統或文件間追蹤他們。
Requirements
- Unity Gateway 測試版功能已啟用於您的帳號。 請參閱 管理 Azure Databricks 預覽。
- 若要建立代理服務,您必須在父目錄和結構描述上具備
USE CATALOG和USE SCHEMA、在結構描述上具備CREATE SERVICE,以及在代理服務所參考的連線上具備USE CONNECTION。 - 要管理代理服務的 權限 ,您必須是代理服務的擁有者或擁有
MANAGE該權限。
建立代理服務
代理服務會參考一個現有的 Unity 目錄連線,該連線中保存代理的主機與憑證。 在建立客服服務之前,先建立連線。
以下範例會在 support_agent 結構描述中建立名為 main.default 的代理程式服務:
databricks api post \
"/api/2.1/unity-catalog/agent-services?parent=schemas/main.default&agent_service_id=support_agent" \
--json '{
"agent_service_type": "AGENT_SERVICE_TYPE_EXTERNAL",
"comment": "Support agent for the customer team",
"config": {
"source_connection": {
"name": "connections/main.default.my_agent_connection"
},
"base_path": "/v1/chat",
"system_prompt": "You are a helpful support assistant."
}
}'
回應包含代理服務的資源名稱:
{
"name": "agent-services/main.default.support_agent",
"agent_service_type": "AGENT_SERVICE_TYPE_EXTERNAL",
"created_by": "you@company.com",
"config": {
"source_connection": { "name": "connections/main.default.my_agent_connection" },
"base_path": "/v1/chat",
"system_prompt": "You are a helpful support assistant."
}
}
取得並刊登經紀人服務
依全名檢索單一代理服務:
databricks api get "/api/2.1/unity-catalog/agent-services/main.default.support_agent"
以結構形式列出所有代理服務:
databricks api get "/api/2.1/unity-catalog/agent-services?parent=schemas/main.default"
若要列出整個元儲存庫的代理服務,請省略結構過濾器:
databricks api get "/api/2.1/unity-catalog/agent-services"
更新代理服務
若要更新特定欄位而不覆蓋其他欄位,請使用 PATCH 請求並指定要更改的欄位。 以下範例更新系統提示字元,但其他欄位保持不變:
databricks api patch \
"/api/2.1/unity-catalog/agent-services/main.default.support_agent?update_mask=config.system_prompt" \
--json '{ "config": { "system_prompt": "You are a concise support assistant." } }'
你可以更新的欄位有: comment, config.system_prompt, config.base_path,
授予存取權
為代理服務設定權限,並採用與保護其他 Unity Catalog 可保護物件相同的授權模型。 將 EXECUTE 授與使用者和服務主體:
databricks api patch \
"/api/2.1/unity-catalog/permissions/AGENT_SERVICE/main.default.support_agent" \
--json '{
"changes": [
{ "principal": "teammate@company.com", "add": ["EXECUTE"] }
]
}'
檢視現有補助:
databricks api get "/api/2.1/unity-catalog/permissions/AGENT_SERVICE/main.default.support_agent"
撤銷存取權限:
databricks api patch \
"/api/2.1/unity-catalog/permissions/AGENT_SERVICE/main.default.support_agent" \
--json '{
"changes": [
{ "principal": "teammate@company.com", "remove": ["EXECUTE"] }
]
}'
可分配權限: EXECUTE, READ METADATA, MANAGE, ALL PRIVILEGES,
刪除代理服務
databricks api delete "/api/2.1/unity-catalog/agent-services/main.default.support_agent"
Limitations
測試期間,以下限制適用:
- 執行時調用功能不可用。 代理人無法透過註冊代理人服務被呼叫。 註冊與權限管理現已開放。
- API 不支援服務政策與速率限制。 嘗試設定這些欄位會回傳錯誤。
- 代理服務的 SQL DDL 無法使用。 使用 REST API 建立並管理代理服務。
-
full_name和owner欄位在此版本的null回應中會傳回 GET。 - Unity Catalog 全域搜尋不會顯示代理服務。
- 這種
BROWSE特權並不被支持。 要查看代理服務,使用者需要對其擁有明確的權限,例如EXECUTE。
下一步
- 透過 Unity Gateway 進行 AI 治理 ,從集中位置管理 AI 流量。