このページでは、ユーザーまたはサービス アカウントに Identity and Access Management の権限を付与して、プロジェクト内の単一のエージェントを共有する方法について説明します。
エージェントを共有するには、特定のエージェント リソースに対する aiplatform.reasoningEngines.query 権限を付与します。
エージェントを共有する場合
エージェントを共有すると、複数のユーザーまたは自動化されたシステムがエージェントにクエリを実行できます。 エージェントを共有する一般的なシナリオは次のとおりです。
- コラボレーション: エージェントをチームや 組織の他のメンバーと共有して、タスクに使用します。
- アプリケーション統合: サービス アカウントにアクセス権を付与して、 内部チャットボットやカスタマー サポート ポータルなどのカスタム アプリケーションがエージェントを呼び出して特定のユーザー リクエストを処理できるようにします。
- エージェント間通信: マルチエージェント システムでは、1 つのエージェントが別のエージェントを呼び出して情報を取得したり、サブタスクを委任したりすることが 必要になる場合があります。
- 情報アクセス: 基盤となるデータソースに直接アクセス権を付与することなく、 会話型インターフェースを介してデータへの制御されたアクセスを ユーザーに提供します。たとえば、ナレッジベース（人事ポリシーや技術ドキュメントなど）に接続されたエージェントをすべての従業員と共有します。
始める前に
- 共有するエージェントを特定します。エージェントのプロジェクト ID と Reasoning Engine ID が必要です。
- アクセス権を付与するユーザーまたはサービス アカウントを特定します。
ステップ 1: カスタムロールを作成する
最小権限の原則に従って、aiplatform.reasoningEngines.query 権限のみを含むカスタムロールを作成します。
gcloud
プロジェクトにカスタムロールを作成するには、次のコマンドを実行します。
gcloud iam roles create ROLE_ID --project=PROJECT_ID \ --title="ROLE_TITLE" \ --description="ROLE_DESCRIPTION" \ --permissions=aiplatform.reasoningEngines.query
または、組織全体にロールを作成するには、次のようにします。
gcloud iam roles create ROLE_ID --organization=ORGANIZATION_ID \ --title="ROLE_TITLE" \ --description="ROLE_DESCRIPTION" \ --permissions=aiplatform.reasoningEngines.query
次のように置き換えます。
ROLE_ID: ロールの ID（agentUserなど）。ROLE_TITLE: ロールのタイトル（Agent runtime userなど）。ROLE_DESCRIPTION: ロールの簡単な説明（Allows querying agentsなど）。PROJECT_ID: プロジェクト ID。ORGANIZATION_ID: 組織 ID。
Terraform
Terraform を使用してカスタムロールを作成するには、google_project_iam_custom_role リソースを使用します。
resource "google_project_iam_custom_role" "reasoning_engine_query" {
role_id = "ROLE_ID"
title = "ROLE_TITLE"
project = "PROJECT_ID"
permissions = ["aiplatform.reasoningEngines.query"]
}
次のように置き換えます。
ROLE_ID: ロールの ID（agentUserなど）。ROLE_TITLE: ロールのタイトル（Agent runtime userなど）。PROJECT_ID: プロジェクト ID。
カスタムロール名は projects/PROJECT_ID/roles/ROLE_ID または organizations/ORGANIZATION_ID/roles/ROLE_ID になります。
ステップ 2: エージェントにロールを付与する
ロールが作成されたら、ロールをエージェントにバインドし、権限を付与するユーザーまたはサービス アカウントを指定します。
Python
Python を使用してロールを付与するには、google-cloud-aiplatform ライブラリを使用します。
from google.cloud.aiplatform_v1 import ReasoningEngineServiceClient from google.api_core.client_options import ClientOptions # Initialize the client client = ReasoningEngineServiceClient( client_options=ClientOptions(api_endpoint="LOCATION-aiplatform.googleapis.com") ) # Define the resource path resource = "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID" # Get the current IAM policy and add the new binding policy = client.get_iam_policy(request={"resource": resource}) binding = policy.bindings.add() binding.role = "projects/PROJECT_ID/roles/ROLE_ID" binding.members.append("USER_OR_SA") # Update the IAM policy on the resource client.set_iam_policy(request={"resource": resource, "policy": policy})
次のように置き換えます。
LOCATION: エージェントがデプロイされているリージョン（us-central1など）。PROJECT_ID: プロジェクト ID。REASONING_ENGINE_ID: エージェントの Reasoning Engine ID。ROLE_ID: ロールの ID（agentUserなど）。USER_OR_SA: ユーザーのメールアドレスまたはサービス アカウント（user:someone@example.comやserviceAccount:my-sa@my-project.iam.gserviceaccount.comなど）。
Terraform
Terraform を使用してロールを付与するには、google_vertex_ai_reasoning_engine_iam_member リソースを使用します。
resource "google_vertex_ai_reasoning_engine_iam_member" "example" {
project = "PROJECT_ID"
region = "REGION"
reasoning_engine = google_vertex_ai_reasoning_engine.my_engine.name
role = google_project_iam_custom_role.reasoning_engine_query.name
member = "USER_OR_SA"
}
次のように置き換えます。
PROJECT_ID: プロジェクト ID。REGION: リージョン。USER_OR_SA: ユーザーまたはサービス アカウント。
セキュリティ上の考慮事項
エージェントへのアクセス権を付与すると、エージェントの FastAPI エンドポイントにメッセージを直接送信できます。セキュリティ保証は、受信エージェントのコードによって決まります。
- 信頼できるフロントエンド: ほとんどのデフォルト ADK エージェントは、信頼できる フロントエンドから動作します。エージェントはフロントエンド コマンドを信頼するため、フロントエンドはセッションとユーザーを完全に制御できます。このような場合は、信頼できないエンティティにエージェントへの直接アクセス権を付与しないでください。
- A2A エージェント: Agent2Agent（A2A）エージェントなどの他のエージェントは、独自の認証と 認可を実装している場合、信頼できないエンティティに 公開される可能性があります。エージェント ランタイムは、エージェント インターフェースへの粗いアクセス制御のみを提供します。