注: このドキュメントセットは、Gemini Enterprise の Standard、Plus、従量課金、Frontline エディションを対象としています。Business エディションのドキュメントについては、Gemini Enterprise - Business エディションのヘルプセンターをご覧ください。

Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Agent Runtime でホストされている ADK エージェントの登録と管理

このページでは、管理者が Gemini Enterprise ウェブアプリで使用するために、Agent Runtime から ADK エージェントを登録する方法について説明します。

Agent Runtime にデプロイされた ADK エージェントの場合は、 Agent Platform の単一の Agents CLI コマンドを使用して、エージェントを Gemini Enterprise に登録できます。

Agent Runtime でホストされている ADK エージェントを Gemini Enterprise app に登録し、Gemini Enterprise ウェブアプリでエンドユーザーがこれらのエージェントを利用できるようにすると、次のようになります。

Agent Runtime サービスがエージェントのクエリを処理します。
Agent Runtime ML 処理の利用規約が適用されます。詳細については、 Agent Runtime の制限事項をご覧ください。

次の表に、安全で制御されたデプロイと使用を確保するために ADK エージェントがどのように管理されるかを示します。

エージェントのガバナンス	説明
安全な通信	Agent Runtime と Gemini Enterprise の接続は VPC Service Controls（VPC-SC）に準拠しており、安全なデータ交換を保証します。
プロジェクトをまたぐエージェントのサポート	別の Google Cloudでホストされている ADK エージェントに接続できます。 Gemini Enterprise は、 Google Cloudの安全なプライベートネットワークをこれらのプロジェクト間接続に使用します。詳細については、プロジェクトをまたぐ ADK エージェントアクセスを構成するをご覧ください。
パーソナライズされたインタラクション	ADK エージェントは、Gemini Enterprise からユーザーのメールアドレスを受け取ります。これにより、エージェントは個々のユーザーを認識し、ユーザーの ID と権限に基づいてパーソナライズされたレスポンスを提供できます。

始める前に

以下のものが揃っていることを確認してください。

Gemini Enterprise 管理者ロール。
Discovery Engine API を有効にします。 Google Cloudプロジェクトで Discovery Engine API を有効にするには、 Google Cloud コンソールで [Discovery Engine API] ページに移動します。

Discovery Engine API に移動
既存の Gemini Enterprise app。アプリを作成するには、アプリを作成するをご覧ください。
Agent Runtime でホストされている ADK エージェント。詳しくは、Agent Development Kit の概要をご覧ください。
- エージェントがない場合は、adk-samples GitHub リポジトリの手順に沿って、fun_facts エージェントを Agent Runtime にデプロイします。その後、エージェントを Gemini Enterprise に登録できます。
ヒント: Gemini Enterprise 内で ADK エージェントを機能させるには、Agent Runtime でホストして維持する必要があります。
ADK エージェントが Gemini Enterprise app とは異なる Google Cloud プロジェクトでホストされている場合は、必要な権限を付与する必要があります。詳細については、プロジェクトをまたぐ ADK エージェントアクセスの権限を付与するをご覧ください。

認可の詳細情報を構成する（省略可）

認可の詳細情報を取得する手順は次のとおりです。

Google Cloud コンソールの [API とサービス] ページで、[認証情報] ページに移動します。

[認証情報] に移動
エージェントにアクセスさせるデータソースがあるプロジェクト Google Cloud を選択します。たとえば、エージェントにクエリを実行させる BigQuery データセットを含むプロジェクトを選択します。
[認証情報を作成] をクリックし、[OAuth クライアント ID] を選択します。
[アプリケーションの種類] で [ウェブアプリケーション] を選択します。
[承認済みのリダイレクト URI] セクションに、次の URI を追加します。
- https://vertexaisearch.cloud.google.com/oauth-redirect
- https://vertexaisearch.cloud.google.com/static/oauth/oauth.html
[作成] をクリックします。
[OAuth クライアントを作成しました] パネルで、[JSON をダウンロード] をクリックします。ダウンロードした JSON には、Client ID、Authorization URI Token URI、Client secret が選択した Google Cloud プロジェクトに含まれています。認可リソースを作成するには、次の情報が必要です。

ADK エージェントを Gemini Enterprise に登録する

Google Cloud コンソールまたは REST API を使用して、ADK エージェントを Gemini Enterprise に登録できます。これにより、Gemini Enterprise app 内のユーザーがエージェントを利用できるようになります。

コンソール

Google Cloud コンソールを使用して ADK エージェントを登録する手順は次のとおりです。

Google Cloud コンソールで、[Gemini Enterprise] ページに移動します。

Gemini Enterprise
エージェントを登録するアプリの名前をクリックします。
[エージェント] をクリックします。[エージェント] ページが表示されます。
[ Add agent] をクリックします。[エージェントを追加] パネルが表示されます。
[Agent Runtime によるカスタムエージェント] の [追加] をクリックします。[認可] ページが表示されます。
エージェントがユーザーに代わって Google Cloud リソースにアクセスする場合は、各リソースに認可が必要です。単一のリソースの認可を設定する手順は次のとおりです。
1. [承認を追加] をクリックします。
2. [認証名] に一意の値を入力します。名前に基づいて ID が生成され、後で変更することはできません。
3. 認可の詳細情報を構成する（省略可）で生成した値を次のフィールドに入力します。
  1. [Client ID] フィールドに値を入力します。
  2. [クライアントシークレット] フィールドに値を入力します。
  3. [トークン URI] フィールドに値を入力します。
  4. [Authorization URI] フィールドに値を入力します。OAuth 認証情報の JSON ファイルの詳細を使用して、Authorization URI を作成します。次のテンプレートをコピーし、プレースホルダを特定の値に置き換えます。
```
https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=YOUR_CUSTOM_SCOPES&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
```
  5. [完了] をクリックします。
[次へ] をクリックします。
エージェントを構成する手順は次のとおりです。
1. [エージェント名] フィールドに名前を入力します。この値は、エージェントの表示名として Gemini Enterprise ウェブアプリに表示されます。
2. [エージェントの説明] フィールドに説明を入力します。この値は、ユーザーのクエリに応じてエージェントを呼び出すかどうかを判断するために LLM によって使用されます。
3. Agent Runtime リソースパスを入力します。リソースパスの形式は次のとおりです。
```
 projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID
 
```
  Agent Runtime でホストされているエージェントを一覧表示してリソースパスを取得する方法の詳細については、デプロイされたエージェントを一覧表示するをご覧ください。
4. [作成] をクリックします。

REST

REST API を使用して ADK エージェントを登録する手順は次のとおりです。

Gemini Enterprise に認可リソースを追加する（省略可）
ADK エージェントを登録する

Gemini Enterprise に認可リソースを追加する（省略可）

エージェントがユーザーに代わって Google Cloud リソースにアクセスする必要がある場合は、次のコマンドを実行して、認可の詳細情報を構成する（省略可）セクションで作成した認可リソースを Gemini Enterprise に登録します。

curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/authorizations?authorizationId=AUTH_ID" \
   -d '{
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/authorizations/AUTH_ID",
      "serverSideOauth2": {
         "clientId": "OAUTH_CLIENT_ID",
         "clientSecret": "OAUTH_CLIENT_SECRET",
         "authorizationUri": "OAUTH_AUTH_URI",
         "tokenUri": "OAUTH_TOKEN_URI"
      }
   }'

次のように置き換えます。

PROJECT_ID: 実際のプロジェクトの ID。
PROJECT_NUMBER: Google Cloud プロジェクトの数。
ENDPOINT_LOCATION: API リクエストのマルチリージョン。次のいずれかの値を指定します。
- 米国のマルチリージョンの場合は us
- EU のマルチリージョンの場合は eu
- グローバルロケーションの場合は global
詳細については、データストアのマルチリージョンを指定するをご覧ください。
LOCATION: データストアのマルチリージョン（ global、us、eu）
AUTH_ID: 認可リソースの ID。任意に定義する英数字の ID です。この ID は、OAuth サポートが必要なエージェントを登録するときに参照する必要があります。
OAUTH_CLIENT_ID: OAuth 認証情報を作成したときに取得した OAuth 2.0 クライアント ID。
OAUTH_CLIENT_SECRET: OAuth 認証情報を作成したときに取得した OAuth 2.0 クライアントシークレット。
OAUTH_AUTH_URI: 認可 URI。アプリを認可するには、OAuth 認証情報の JSON ファイルの詳細を使用して、特定の認可 URI を作成します。次のテンプレートをコピーし、プレースホルダを特定の値に置き換えます。
```
https://accounts.google.com/o/oauth2/v2/auth?client_id=OAUTH_CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=YOUR_CUSTOM_SCOPES&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
```
- YOUR_CUSTOM_SCOPES: 必要なスコープを追加できます。たとえば、次の OAuth スコープ文字列は、Google ドライブと Google ドキュメントへの読み取り専用アクセスをリクエストします。
```
scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdocuments.readonly
```
OAUTH_TOKEN_URI: OAuth 認証情報の作成時に取得したトークン URI。

認可 URI パラメータの詳細。

URI が正しく機能するように、次のフィールドを確認してください。

パラメータ	値またはアクション
`client_id`	ダウンロードした JSON にある `client_id` に置き換えます。
`redirect_uri`	変更しないでください。 `https://vertexaisearch.cloud.google.com/static/oauth/oauth.html` を指定します。
`scope`	アプリがユーザーに代わってアクセスする必要がある Google API スコープを一覧表示します。たとえば、BigQuery へのアクセス権を付与するには、スコープ `https://www.googleapis.com/auth/bigquery` を使用します。Google ドキュメントへの読み取り専用アクセスには、`https://www.googleapis.com/auth/documents.readonly` を使用します。複数のスコープを使用する場合は、スペースで区切ります。スペースは URL で `%20` になります。
`include_granted_scopes`	`true` を指定します。
`response_type`	認証コードを受け取るには、`code` を指定します。
`access_type`	更新トークンを確実に受け取れるように、`offline` に設定します。
`prompt`	ユーザーに常に同意画面が表示されるように、`consent` に設定します。

ADK エージェントを登録する

このコードサンプルは、ADK エージェントを登録する方法を示しています。

   curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -H "X-Goog-User-Project: PROJECT_ID" \
      "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents" \
      -d '{
         "displayName": "DISPLAY_NAME",
         "description": "DESCRIPTION",
         "icon": {
            "uri": "ICON_URI"
         },
         "adkAgentDefinition": {
            "provisionedReasoningEngine": {
               "reasoningEngine": "projects/PROJECT_ID/locations/RESOURCE_LOCATION/reasoningEngines/RESOURCE_ID"
            }
         },
         "authorizationConfig": {
            "toolAuthorizations": [
               "projects/PROJECT_NUMBER/locations/global/authorizations/AUTH_ID"
            ]
         }
      }'

変数部分は、次のように実際の値に置き換えます。

ENDPOINT_LOCATION: API リクエストのマルチリージョン。次のいずれかの値を指定します。
- 米国のマルチリージョンの場合は us
- EU のマルチリージョンの場合は eu
- グローバルロケーションの場合は global
詳細については、データストアのマルチリージョンを指定するをご覧ください。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
PROJECT_NUMBER: 実際の Google Cloud プロジェクト ID。
APP_ID: Gemini Enterprise app の固有識別子。
DESCRIPTION：Gemini Enterprise に表示されるエージェントの説明。
ICON_URI: エージェントの名前の横に表示するアイコンの公開 URI。別の方法として、Base64 でエンコードされた画像ファイルの内容を渡すこともできます。その場合は、icon.content を使用します。
- RESOURCE_ID: ADK エージェントがデプロイされている Agent Runtime エンドポイントの ID 。Agent Runtime でホストされているエージェントを一覧表示してリソース ID を取得する方法については、デプロイされたエージェントを一覧表示するをご覧ください。
- RESOURCE_LOCATION: Agent Runtime エンドポイントのクラウドロケーション。詳細については、Agent Runtime のロケーションをご覧ください。
- authorization_config: 認可の詳細情報を取得し、エージェントがユーザーに代わって Google Cloud リソースにアクセスできるようにする場合は、JSON リソースに authorization_config フィールドを追加します。
  - AUTH_ID: 認可の詳細情報を構成するセクションで AUTH_ID に使用した値。

エージェントをユーザーと共有する

ユーザーが Gemini Enterprise ウェブアプリを使用してエージェントにアクセスできるようにするには、エージェントを共有するをご覧ください。

アプリに接続されているエージェントを一覧表示する

次のコードサンプルは、アプリに接続されているすべてのエージェントの詳細を取得する方法を示したものです。

REST

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents"

変数部分は、次のように実際の値に置き換えます。

ENDPOINT_LOCATION: API リクエストのマルチリージョン。次のいずれかの値を指定します。
- 米国のマルチリージョンの場合は us
- EU のマルチリージョンの場合は eu
- グローバルロケーションの場合は global
詳細については、データストアのマルチリージョンを指定するをご覧ください。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
LOCATION: アプリのマルチリージョン（global、us、eu）。
APP_ID: Gemini Enterprise app の ID。

エージェントが Google によって事前構築されていない場合、レスポンスの最初の数行に name フィールドが含まれます。このフィールドの値には、パスの末尾にエージェント ID が含まれます。たとえば、次のレスポンスでは、エージェント ID は 12345678901234567890 です。

{
"name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
...
}

ADK エージェントの詳細を表示する

次のコードサンプルが示すのは、Gemini Enterprise に登録されたエージェントの詳細を取得する方法です。

REST

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

変数部分は、次のように実際の値に置き換えます。

ENDPOINT_LOCATION: API リクエストのマルチリージョン。次のいずれかの値を指定します。
- 米国のマルチリージョンの場合は us
- EU のマルチリージョンの場合は eu
- グローバルロケーションの場合は global
詳細については、データストアのマルチリージョンを指定するをご覧ください。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
LOCATION: アプリのマルチリージョン（global、us、eu）。
APP_ID: Gemini Enterprise app の ID。
AGENT_ID: エージェントの ID。エージェント ID は、アプリに接続されているエージェントを一覧表示することで確認できます。

ADK エージェントを更新する

Gemini Enterprise に登録されている既存のエージェントの詳細は、 Google Cloud コンソールまたは REST API を使用して変更できます。

コンソール

Google Cloud コンソールを使用してエージェントを更新する手順は次のとおりです。

Google Cloud コンソールで、[Gemini Enterprise] ページに移動します。

Gemini Enterprise
更新するエージェントを含むアプリの名前をクリックします。
[エージェント] をクリックします。
更新する Agent Runtime エージェントの名前をクリックし、[編集] をクリックします。
表示名 、説明、または Agent Runtime 推論エンジン を更新します。

リソースパスの形式は次のとおりです。
```
projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID
```
Agent Runtime でホストされているエージェントを一覧表示してリソースパスを取得する方法の詳細については、デプロイされたエージェントを一覧表示するをご覧ください。
[保存] をクリックします。

REST

エージェントの登録時にすべてのフィールドを更新できます。ただし、次のフィールドは更新する必要があります。

displayName
description

reasoningEngine

このコードサンプルは、既存の ADK エージェントの登録を更新する方法を示しています。

curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/AGENT_RESOURCE_NAME" \
   -d '{
         "displayName": "DISPLAY_NAME",
         "description": "DESCRIPTION",
         "adkAgentDefinition": {
         "provisionedReasoningEngine": {
            "reasoningEngine":
            "projects/PROJECT_ID/locations/RESOURCE_LOCATION/reasoningEngine
            s/RESOURCE_ID"
         },
      }
   }'

変数部分は、次のように実際の値に置き換えます。

ENDPOINT_LOCATION: API リクエストのマルチリージョン。次のいずれかの値を指定します。
- 米国のマルチリージョンの場合は us
- EU のマルチリージョンの場合は eu
- グローバルロケーションの場合は global
詳細については、データストアのマルチリージョンを指定するをご覧ください。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
AGENT_RESOURCE_NAME: 更新するエージェント登録のリソース名。
DISPLAY_NAME: 必須。Gemini Enterprise に表示されるエージェントのわかりやすい名前。
DESCRIPTION: 必須。Gemini Enterprise でユーザーに表示される、エージェントの機能の簡単な説明。
RESOURCE_LOCATION: Agent Runtime エンドポイントのクラウドロケーション。詳細については、Agent Runtime のロケーションをご覧ください。
RESOURCE_ID: ADK エージェントがデプロイされている Agent Runtime エンドポイントの ID。Agent Runtime でホストされているエージェントを一覧表示してリソース ID を取得する方法については、デプロイされたエージェントを一覧表示するをご覧ください。

ADK エージェントを削除する

次のコードサンプルが示すのは、アプリに接続されているエージェントを削除する方法です。

REST

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

変数部分は、次のように実際の値に置き換えます。

ENDPOINT_LOCATION: API リクエストのマルチリージョン。次のいずれかの値を指定します。
- 米国のマルチリージョンの場合は us
- EU のマルチリージョンの場合は eu
- グローバルロケーションの場合は global
詳細については、データストアのマルチリージョンを指定するをご覧ください。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
LOCATION: アプリのマルチリージョン（global、us、eu）
APP_ID: Gemini Enterprise app の ID。
AGENT_ID: エージェントの ID。エージェント ID は、アプリに接続されているエージェントを一覧表示することで確認できます。

コマンドの例と結果

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://global-discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890"

{
  "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890/operations/delete-agent-12345678901234567890",
  "done": true
}

Agent Runtime のロケーション

エージェントを登録または更新する場合、Agent Runtime のロケーションは Gemini Enterprise app のロケーションと互換性がある必要があります。ロケーションが一致しないとエラーが発生します。

互換性の要件については、次の表をご覧ください。

Gemini Enterprise app のロケーション	許可される Agent Runtime のロケーション
`global`	サポートされている Google Cloud 任意のリージョン
`us`	`us-` で始まる任意のリージョン（`us-central1`、`us-east4` など）
`eu`	`europe-` で始まる任意のリージョン（`europe-west1`、`europe-west3` など）

Agent Runtime でホストされている ADK エージェントの登録と管理 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

認可の詳細情報を構成する（省略可）

ADK エージェントを Gemini Enterprise に登録する

コンソール

REST

Gemini Enterprise に認可リソースを追加する（省略可）

認可 URI パラメータの詳細。

ADK エージェントを登録する

エージェントをユーザーと共有する

アプリに接続されているエージェントを一覧表示する

REST

ADK エージェントの詳細を表示する

REST

ADK エージェントを更新する

コンソール

REST

ADK エージェントを削除する

REST

コマンドの例と結果

Agent Runtime のロケーション

Agent Runtime でホストされている ADK エージェントの登録と管理