エージェントメモリおよびセッションストアの権限を管理します
ベータ版
この機能はベータ版です。使用するには、ワークスペース管理者は プレビュー ページから Agentメモリセッション を有効にする必要があります。Databricksプレビューの管理を参照してください。
エージェントのメモリストアとセッションストアは、同じストアレベルの権限モデルを使用します。権限はストアのコンテンツに適用されます。メモリ内のすべてのメモリエントリ、またはセッションストア内のすべてのセッションおよびセッションアイテムに適用されます。
DatabricksユーザーまたはService Principalにアクセス権を付与できます。ユーザーをEメールで識別し、Service Principalをアプリケーション(クライアント) IDで識別します。ストア権限はグループをサポートしていません。
要件
- 既存のメモリ ストアまたはセッション ストア。
- Agent Bricks CLIまたはAgentKit SDKの例では、Python 3.10以上と
databricks-agentbricks0.8.0以上が必要です。
ストアレベルのアクセスモデル
ストアがセキュリティ境界になります。actor_id、session_id、path、metadataなどのフィールドはデータを整理・フィルタリングしますが、アクセスを制限するものではありません。ストアにアクセスできるプリンシパルは、そのストア内のすべてのアクセクタのデータにアクセスできます。テナントまたはユーザー間でデータを分離するには、セキュリティ境界ごとに個別のストアを作成します。
ストアの権限には次のレベルがあります：
権限 | ストアデータの読み取り | ストアデータの書き込み |
|---|---|---|
| はい | No |
| はい | はい。 |
アクセス権がありません | No | No.この状態は付与できません。プリンシパルの明示的なアクセス権を削除するには、取り消し操作を使用します。Get操作は、この状態を |
権限を管理できるのは、ストアの作成者とワークスペース管理者のみです：
- ストアの作成者には暗黙的に
WRITEアクセス権が付与され、権限の付与、一覧表示、取り消しができます。ストア作成者の所有権は取り消すことができません。 - ワークスペース管理者は、ワークスペース内の任意のストアに対する権限の付与、一覧表示、取り消しを行うことができます。ワークスペース管理者であること自体によってデータアクセス権が付与されるわけではありません。既存のデータアクセス権を持たない管理者は、ストアを使用するために
READまたはWRITEを自身に付与する必要があります。 READまたはWRITEを持つユーザーまたはService Principalはストアを使用できますが、権限を管理することはできません。
継承されたアクセス権は、databricks_superuserなど、基盤となるLakebaseプロジェクトのPostgresロールのメンバーシップから取得されます。ストアのアクセス許可操作では、それらのロールメンバーシップは変更されません。「Postgres ロールのアクセス許可の管理」を参照してください。
権限操作
ストアの権限は次の4つの操作をサポートしています：
オペレーション | 挙動 |
|---|---|
付与 |
|
取得 | 認証された呼び出し元は、Getをランできます。呼び出し元の有効な権限のみを返します。これには、暗黙的な作成者のアクセス権と継承されたアクセス権が含まれます。呼び出し元にアクセス権がない場合、 |
リスト | ユーザーおよびService Principalに対する明示的な許可を返します。これには、作成者の暗黙的なアクセス権、ワークスペース管理者管理権限、および継承されたアクセス権は含まれません。結果が空であっても、プリンシパルがストアにアクセスできないことは証明されません。 |
取り消し | 1つのプリンシパルから明示的な |
List REST APIは、100件の付与のdefaultページサイズを使用し、ページあたり最大1,000件の付与をサポートしています。AgentKit SDKはすべてのページを自動的に追跡します。Agent Bricks CLIでは、--allを使用してすべてのページを返します。
プリンシパルを WRITE から READ にダウングレードするには、既存の許可を取り消してから READ を許可します。これらの操作はアトミックではありません。そのため、プリンシパルは2つの呼び出し間で明示的なアクセス権を持っていません。
ストア権限の管理
次の例では、メモリストアの権限を管理します。セッションストアの場合は、 Agent Bricks CLIの memory stores、 AgentKit SDKの client.session_stores.get("<store-name>")、または REST API パスの session-stores/<store-name>の代わりに sessions storesを使用します。
- Agent Bricks CLI
- AgentKit SDK
- REST API
アクセス許可コマンドは、他のストアコマンドと同じストア識別子を受け入れます。メモリストアは、ストアID、リソース名、または一意の表示名を受け入れます。セッションストアは、ストア名またはリソース名を受け入れます。
ユーザーに読み取りアクセス権を付与するには、次の操作をランします。
agentbricks memory stores permissions grant <store-id> \
--user teammate@example.com --permission READ
Service Principalに書き込みアクセス権を付与するには、以下を実行します。Service PrincipalのアプリケーションIDを渡します。
agentbricks memory stores permissions grant <store-id> \
--service-principal <application-id> --permission WRITE
有効なアクセス許可を取得するには、次のコマンドをランします。
agentbricks memory stores permissions get <store-id>
すべての明示的な付与をリストするには、ストア作成者またはワークスペース管理者として以下をランします。
agentbricks memory stores permissions list <store-id> --all
ユーザーの明示的なアクセス権を取り消すには、次のコマンドをランします。--yesオプションは確認プロンプトをスキップします。
agentbricks memory stores permissions revoke <store-id> \
--user teammate@example.com --yes
権限メソッドは、MemoryStoreとSessionStoreの両方のオブジェクトで使用できます。次の例では、権限レベルとプリンシパルタイプを明示的に渡します。
from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient
client = AgentKitClient(WorkspaceClient())
store = client.memory_stores.get("<store-id>")
# Grant a user read access.
store.grant_permission(
"teammate@example.com",
principal_type="USER",
permission="READ",
)
# Return the authenticated caller's effective permission.
permission = store.get_permission()
print(permission.principal.name, permission.permission)
# List every explicit grant.
for grant in store.list_permissions(page_size=100):
print(grant.principal.name, grant.principal.principal_type, grant.permission)
# Remove the user's explicit READ and WRITE grants.
store.revoke_permission("teammate@example.com", principal_type="USER")
grant_permission() および revoke_permission() は、SERVICE_PRINCIPAL をdefaultのプリンシパルタイプとして使用します。grant_permission() は WRITE をdefaultの権限として使用します。ユーザーアクセスまたは読み取り専用アクセスを付与する際は、両方の引数を明示的に渡してください。
権限Endpointは /api/2.0/agents/memory-stores/<store-id>/permissions の下にあります。リクエスト本文では、USER を持つユーザーと SERVICE_PRINCIPAL を持つService Principalを識別します。
DATABRICKS_HOST をワークスペース URL ( https:// を含む) に設定し、 DATABRICKS_TOKEN をアクセストークンに設定します。
ユーザーに読み取りアクセス権を付与するには、Grant操作を呼び出します。
curl -X POST "${DATABRICKS_HOST}/api/2.0/agents/memory-stores/<store-id>/permissions:grant" \
-H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"principal": {"principal_type": "USER", "name": "teammate@example.com"},
"permission": "READ"
}'
認証された呼び出し側の有効な権限を取得するには、Get操作を呼び出します。
curl "${DATABRICKS_HOST}/api/2.0/agents/memory-stores/<store-id>/permissions/self" \
-H "Authorization: Bearer ${DATABRICKS_TOKEN}"
明示的な付与をリストするには、ストア作成者またはワークスペース管理者として List 操作を呼び出します。
curl "${DATABRICKS_HOST}/api/2.0/agents/memory-stores/<store-id>/permissions?page_size=100" \
-H "Authorization: Bearer ${DATABRICKS_TOKEN}"
ユーザーの明示的なアクセス権を取り消すには、Revoke 操作を呼び出します。
curl -X POST "${DATABRICKS_HOST}/api/2.0/agents/memory-stores/<store-id>/permissions:revoke" \
-H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"principal": {"principal_type": "USER", "name": "teammate@example.com"}
}'
GrantおよびRevoke操作は、アクセス許可オブジェクトを返しません。変更を確認するには、ストア作成者またはワークスペース管理者としてListをランします。有効なアクセス権を確認するには、影響を受けるプリンシパルとして認証し、Getをランします。
エージェントデプロイメントによって管理される権限
エージェント プロジェクトでメモリまたはセッション ストアが宣言されると、agentbricks deploy はデプロイされたアプリのService Principalにそのストアへのアクセス権を付与します。後のデプロイで、手動で取り消したアクセス権が復元される場合があります。
ストアのバインディングを解除すると、エージェントプロジェクトからバインディングが削除されます。アプリのService Principalに既に付与されているアクセス権は取り消されません。そのアクセス権を削除するには、Revoke操作を使用します。
その他のリソース
-
- エージェントメモリ
- 異なる会話の間で持続する長期記憶をエージェントに与えます。
-
- エージェントセッション
- エージェントの会話履歴を保存することで、ターン間での対話を再開できるようにします。