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

このページでは、Gemini Enterprise の管理者が、Vertex AI Agent Engine でホストされている Agent Development Kit（ADK）エージェントを登録して、Gemini Enterprise ウェブアプリでユーザーが利用できるようにする方法について説明します。

始める前に

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

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

Discovery Engine API に移動
既存の Gemini Enterprise アプリ。アプリを作成するには、アプリを作成するをご覧ください。
Vertex AI Agent Engine でホストされている ADK エージェント。詳しくは、Agent Development Kit の概要をご覧ください。

ヒント: Gemini Enterprise 内で ADK エージェントを機能させるには、Vertex AI Agent Engine でホストして維持する必要があります。

認可の詳細情報を構成する

エージェントがユーザーの代わりに Google Cloud リソース（BigQuery テーブルなど）にアクセスするための OAuth 2.0 認証情報を作成します。

認可の詳細情報を取得する

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

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 には、選択したGoogle Cloud プロジェクトの Client ID、Authorization URI、Token URI、Client secret が含まれています。認可リソースを作成するには、次の情報が必要です。

Gemini Enterprise に認可リソースを追加する

次のコマンドを実行して、Gemini Enterprise に認可リソースを登録します。

REST

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/LOCATION/authorizations?authorizationId=AUTH_ID" \
   -d '{
      "name": "projects/PROJECT_ID/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。
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: OAuth 認証情報の作成時に取得した認証 URI。次の形式となります。https://accounts.google.com/o/oauth2/v2/auth?client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fbigquery&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
OAUTH_TOKEN_URI: OAuth 認証情報の作成時に取得したトークン URI。

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

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

コンソール

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

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

Gemini Enterprise
エージェントを登録するアプリの名前をクリックします。
[エージェント] > [エージェントの追加] をクリックします。
[エージェントタイプの選択] セクションで、[Agent Engine によるカスタムエージェント] の [追加] をクリックします。
エージェントがユーザーに代わって Google Cloud リソースにアクセスできるようにするには、次の操作を行います。
1. [承認を追加] をクリックします。
2. [認証名] に一意の値を入力します。ID は名前に基づいて生成され、後で変更することはできません。
3. 認可の詳細を取得するで生成したクライアント ID、クライアントシークレット、認可 URI、トークン URI を入力します。
4. [承認を追加] をクリックします。
[次へ] をクリックします。
エージェントを構成する手順は次のとおりです。
1. [エージェント名] フィールドに名前を入力します。この値は、エージェントの表示名として Gemini Enterprise ウェブアプリに表示されます。
2. [エージェントの説明] フィールドに説明を入力します。この値は、ユーザーのクエリに応じてエージェントを呼び出すかどうかを判断するために LLM によって使用されます。
3. Agent Engine 推論エンジンのリソースパスを入力します。リソースパスの形式は次のとおりです。
```
    https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/ADK_RESOURCE_ID
 
```
  Vertex AI Agent Engine でホストされているエージェントを一覧表示してリソースパスを取得する方法の詳細については、デプロイされたエージェントを一覧表示するをご覧ください。
4. [作成] をクリックします。

REST

このコードサンプルは、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"
      },
      "adk_agent_definition": {
         "provisioned_reasoning_engine": {
            "reasoning_engine":
            "projects/PROJECT_ID/locations/REASONING_ENGINE_LOCATION/reasoningEngines/ADK_RESOURCE_ID"
         }
      },
   "authorization_config": {


   "tool_authorizations": [
   "projects/PROJECT_ID/locations/global/authorizations/AUTH_ID"
   ]
   }
   }'

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

ENDPOINT_LOCATION-: API リクエストのマルチリージョン。次のいずれかの値を割り当てます。
- 米国のマルチリージョンの場合は us-
- EU のマルチリージョンの場合は eu-
- グローバルロケーションの場合は global-
詳細については、データストアのマルチリージョンを指定するをご覧ください。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
APP_ID: Gemini Enterprise アプリの固有識別子。
DESCRIPTION: Gemini Enterprise に表示されるエージェントの説明。
ICON_URI: エージェントの名前の横に表示するアイコンの公開 URI。別の方法として、Base64 でエンコードされた画像ファイルの内容を渡すこともできます。その場合は、icon.content を使用します。
ADK_RESOURCE_ID: ADK エージェントがデプロイされている Reasoning Engine エンドポイントの ID。Vertex AI Agent Engine でホストされているエージェントを一覧表示してリソース ID を取得する方法については、デプロイされたエージェントを一覧表示するをご覧ください。
REASONING_ENGINE_LOCATION: 推論エンジンのクラウドロケーション。詳細については、推論エンジンのロケーションをご覧ください。
authorizationConfig: 認可の詳細情報を取得し、エージェントがユーザーに代わって Google Cloud リソースにアクセスできるようにする場合は、JSON リソースに authorization_config フィールドを追加します。
```
 * <code><var>AUTH_ID</var></code>: the value that you used for
    <var>AUTH_ID</var> in the [Configure authorization details](#authorize-your-adk-agent)
    section.
```

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

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

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 アプリの 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 アプリの ID。
AGENT_ID: エージェントの ID。エージェント ID は、アプリに接続されているエージェントを一覧表示することで確認できます。

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

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

コンソール

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

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

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

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

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/REASONING_ENGINE_LOCATION/reasoningEngine
            s/ADK_RESOURCE_ID"
         },
      }
}'

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

ENDPOINT_LOCATION-: API リクエストのマルチリージョン。次のいずれかの値を割り当てます。
- 米国のマルチリージョンの場合は us-
- EU のマルチリージョンの場合は eu-
- グローバルロケーションの場合は global-
詳細については、データストアのマルチリージョンを指定するをご覧ください。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
AGENT_RESOURCE_NAME: 更新するエージェント登録のリソース名。
DISPLAY_NAME: 必須。Gemini Enterprise に表示されるエージェントのわかりやすい名前。
DESCRIPTION: 必須。Gemini Enterprise でユーザーに表示される、エージェントの機能の簡単な説明。
REASONING_ENGINE_LOCATION: 必須。エージェントを作成する推論エンジンのクラウドロケーション。詳細については、推論エンジンのロケーションをご覧ください。
ADK_RESOURCE_ID: ADK エージェントがデプロイされている Reasoning Engine エンドポイントの ID。Vertex AI Agent Engine でホストされているエージェントを一覧表示してリソース 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 アプリの 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
}

推論エンジンのロケーション

API 呼び出しを推論エンジンの正しいロケーションに行うには、次の表を使用します。

呼び出し側のクラウドロケーション	推論エンジンのロケーション
`us`	`us-central1`
`eu`	`europe-west1`
その他（`global` を含む）	`us-central1`

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

始める前に

認可の詳細情報を構成する

認可の詳細情報を取得する

Gemini Enterprise に認可リソースを追加する

REST

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

コンソール

REST

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

REST

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

REST

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

コンソール

REST

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

REST

コマンドの例と結果

推論エンジンのロケーション

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