ADK エージェントの登録と管理

このページでは、Gemini Enterprise で Vertex AI Agent Engine によってホストされている ADK エージェントを登録して管理する方法について説明します。

概要

Agent Development Kit（ADK）を使用して、生成 AI エージェントを Gemini Enterprise に追加できます。ADK エージェントを登録すると、Gemini Enterprise アプリを使用して選択できるようになります。アプリにクエリを入力すると、エージェントから回答を得て、フォローアップの質問をすることができます。

エージェントの登録は、Gemini Enterprise 管理者のみが行うことができます。エージェントが登録されると、他のユーザーは登録されたエージェントを使用できます。

始める前に

Gemini Enterprise に ADK エージェントを登録する前に、次の操作を行います。

コンソール

Google Cloud コンソールで、[Discovery Engine API] ページに移動して、 Google Cloudプロジェクトで Discovery Engine API を有効にします。

Discovery Engine API に移動
Discovery Engine サービスアカウントで Vertex AI User ロールと Vertex AI Viewer ロールを有効にします。これは、Gemini Enterprise が ADK エージェントを呼び出すために必要です。
1. IAM ページに移動します。
2. Discovery Engine を検索します。
3. サービスアカウントに権限を追加します。
4. Discovery Engine サービスアカウントを表示するには、 Google Cloud コンソールの [Identity and Access Management] ページで [Google 提供のロール付与を含める] を選択します。

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

エージェントがユーザーの代わりに 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/loca
   tions/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 に登録する

ADK エージェントを Gemini Enterprise に登録するには、Google Cloud コンソールまたは API を使用します。

このコードサンプルは、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_DEPLOYMENT_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_DEPLOYMENT_ID: ADK エージェントがデプロイされている Reasoning Engine エンドポイントの ID。
REASONING_ENGINE_LOCATION: 推論エンジンのクラウドロケーション。詳細については、推論エンジンのロケーションをご覧ください。
AUTH_ID: 省略可能な認可リソースの ID。AUTH_ID には 1 つ以上の ID を指定できます。ADK エージェントを認可するをご覧ください。

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

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

curl

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 に登録されたエージェントの詳細を取得する方法を示しています。

curl

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 エージェントを更新する

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

displayName
description
reasoningEngine

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

curl

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_DEPLOYMENT_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_DEPLOYMENT_ID: ADK エージェントがデプロイされている Reasoning Engine エンドポイントの ID。詳細については、推論エンジンのロケーションをご覧ください。

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

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

curl

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 呼び出しを推論エンジンの正しいロケーションに行うには、次の表を使用します。

呼び出し側のクラウドロケーション	推論エンジンのロケーション
`au`	`australia-southeast2`
`asia-northeast1`	`asia-northeast1`
`ca`	`northamerica-northeast2`
`in`	`asia-south2`
`de`	`europe-west3`
`us`	`us-central1`
`eu`	`europe-west1`
`europe-west2`	`europe-west2`
その他（`global` を含む）	`us-central1`

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

概要

始める前に

コンソール

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

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

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

REST

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

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

curl

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

curl

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

curl

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

curl

コマンドの例と結果

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

ADK エージェントの登録と管理