Mendaftarkan dan mengelola agen ADK yang dihosting di Vertex AI Agent Engine

Halaman ini menjelaskan cara admin Gemini Enterprise dapat mendaftarkan agen Agent Development Kit (ADK) yang dihosting di Vertex AI Agent Engine agar dapat tersedia bagi pengguna di aplikasi web Gemini Enterprise.

Sebelum memulai

Pastikan Anda memiliki:

  • Peran Admin Discovery Engine.

  • Aktifkan Discovery Engine API. Untuk mengaktifkan Discovery Engine API untuk project Google Cloud, di konsol Google Cloud , buka halaman Discovery Engine API.

    Buka Discovery Engine API

  • Aplikasi Gemini Enterprise yang sudah ada. Untuk membuat aplikasi, lihat Membuat aplikasi.

  • Agen ADK yang dihosting di Vertex AI Agent Engine. Untuk mengetahui informasi selengkapnya, lihat Ringkasan Agent Development Kit.

Mengonfigurasi detail otorisasi

Buat kredensial OAuth 2.0 untuk agen agar dapat mengakses Google Cloud resource, seperti tabel BigQuery, atas nama pengguna.

Mendapatkan detail otorisasi

Ikuti langkah-langkah berikut untuk mendapatkan detail otorisasi.

  1. Di konsol Google Cloud , pada halaman APIs & Services, buka halaman Credentials.

    Buka Kredensial

  2. Pilih project Google Cloud , yang memiliki sumber data yang ingin diakses oleh agen. Misalnya, pilih project yang berisi set data BigQuery yang ingin Anda kueri oleh agen.

  3. Klik Buat kredensial, lalu pilih ID klien OAuth.

  4. Di Application type, pilih Web application.

  5. Di bagian URI pengalihan yang diberi otorisasi, tambahkan URI berikut:

    • https://vertexaisearch.cloud.google.com/oauth-redirect
    • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html

  6. Klik Create.

  7. Di panel OAuth client created, klik Download JSON. JSON yang didownload mencakup Client ID, Authorization URI, Token URI, dan Client secret untuk projectGoogle Cloud yang dipilih. Anda memerlukan detail berikut untuk membuat resource otorisasi:

Menambahkan resource otorisasi ke Gemini Enterprise

Jalankan perintah berikut untuk mendaftarkan resource otorisasi dengan 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"
      }
   }'

Ganti kode berikut:

  • PROJECT_ID: ID project Anda.
  • ENDPOINT_LOCATION: multi-region untuk permintaan API Anda. Tentukan salah satu nilai berikut:
    • us untuk multi-region AS
    • eu untuk multi-region Uni Eropa
    • global untuk lokasi Global
    Untuk mengetahui informasi selengkapnya, lihat Menentukan multi-region untuk penyimpanan data Anda.
  • LOCATION: multi-region penyimpanan data Anda: global, us, atau eu
  • AUTH_ID: ID resource otorisasi. Ini adalah ID alfanumerik arbitrer yang Anda tentukan. Anda perlu merujuk ID ini nanti saat mendaftarkan Agen yang memerlukan dukungan OAuth.
  • OAUTH_CLIENT_ID: ID klien OAuth 2.0 yang Anda dapatkan saat membuat kredensial OAuth.
  • OAUTH_CLIENT_SECRET: rahasia klien OAuth 2.0 yang Anda dapatkan saat membuat kredensial OAuth.

  • OAUTH_AUTH_URI: URI Otorisasi. Untuk memberi otorisasi aplikasi Anda, buat URI Otorisasi tertentu menggunakan detail dari file JSON kredensial OAuth Anda. Salin template berikut, lalu ganti placeholder dengan nilai spesifik Anda.

    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

    Pengelompokan Parameter

    Untuk membantu memastikan URI berfungsi dengan benar, verifikasi kolom berikut:

    Parameter Nilai atau tindakan
    client_id Ganti dengan client_id yang ada di JSON yang Anda download.
    redirect_uri Jangan ubah. Harus berupa https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
    scope Tindakan diperlukan: Cantumkan cakupan Google API yang dibutuhkan aplikasi Anda (seperti, https://www.googleapis.com/auth/bigquery). Jika Anda menggunakan beberapa cakupan, pisahkan dengan spasi, yang akan menjadi %20 di URL.
    include_granted_scopes Harus berupa true.
    response_type Harus code untuk menerima kode otorisasi.
    access_type Setel ke offline untuk membantu memastikan bahwa Anda menerima token refresh.
    prompt Setel ke consent untuk membantu memastikan bahwa pengguna selalu melihat layar izin.

  • OAUTH_TOKEN_URI: URI token yang Anda peroleh saat Anda membuat kredensial OAuth.

Mendaftarkan agen ADK dengan Gemini Enterprise

Anda dapat mendaftarkan agen ADK dengan Gemini Enterprise menggunakan konsolGoogle Cloud atau REST API. Hal ini membuat agen tersedia bagi pengguna dalam aplikasi Gemini Enterprise.

Konsol

Untuk mendaftarkan agen ADK menggunakan Google Cloud konsol, ikuti langkah-langkah berikut:

  1. Di konsol Google Cloud , buka halaman Gemini Enterprise.

    Gemini Enterprise

  2. Klik nama aplikasi yang ingin Anda daftarkan agennya.

  3. Klik Agen. Halaman Agen akan ditampilkan.

  4. Klik Tambahkan agen. Panel Tambahkan agen akan ditampilkan.

  5. Klik Tambahkan untuk Agen kustom melalui Agent Engine. Halaman Authorizations akan ditampilkan.

  6. Jika Anda ingin agen mengakses resource Google Cloud atas nama Anda, maka setiap resource memerlukan otorisasi. Untuk menyiapkan otorisasi bagi satu resource, ikuti langkah-langkah berikut:

    1. Klik Add authorization.

    2. Masukkan nilai unik untuk Nama otorisasi. ID dibuat berdasarkan nama, dan tidak dapat diubah nanti.

    3. Masukkan nilai yang Anda buat di bagian Obtain authorization details di kolom berikut:

      1. Masukkan nilai di kolom Client ID.

      2. Masukkan nilai di kolom Client secret.

      3. Masukkan nilai di kolom Token URI.

      4. Klik Done.

  7. Klik Berikutnya.

  8. Untuk mengonfigurasi agen, ikuti langkah-langkah berikut:

    1. Masukkan nama di kolom Nama agen. Nilai ini muncul di aplikasi web Gemini Enterprise sebagai nama tampilan agen Anda.

    2. Masukkan deskripsi di kolom Deskripsikan agen Anda. Nilai ini digunakan oleh LLM untuk menentukan apakah akan memanggil agen Anda sebagai respons terhadap kueri pengguna.

    3. Masukkan jalur resource Agent Engine reasoning engine. Jalur resource memiliki format berikut:

          https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/ADK_RESOURCE_ID

      Untuk mengetahui informasi selengkapnya tentang cara mencantumkan agen yang dihosting di Vertex AI Agent Engine dan mendapatkan jalur resource, lihat Mencantumkan agen yang di-deploy.

    4. Klik Create.

REST

Contoh kode ini menunjukkan cara mendaftarkan agen ADK Anda.

   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_NUMBER/locations/global/authorizations/AUTH_ID"
   ]
   }
   }'

Ganti variabel dengan nilai:

  • ENDPOINT_LOCATION: multi-region untuk permintaan API Anda. Tentukan salah satu nilai berikut:

    • us untuk multi-region AS
    • eu untuk multi-region Uni Eropa
    • global untuk lokasi Global
    Untuk mengetahui informasi selengkapnya, lihat Menentukan multi-region untuk penyimpanan data Anda.

  • PROJECT_ID: ID Google Cloud project Anda.

  • PROJECT_NUMBER: jumlah Google Cloud project Anda.

  • APP_ID: ID unik untuk aplikasi Gemini Enterprise.

  • DESCRIPTION : deskripsi agen yang ditampilkan di Gemini Enterprise.

  • ICON_URI: URI publik ikon yang akan ditampilkan di dekat nama agen. Atau, Anda dapat meneruskan konten file gambar berenkode Base64, dan dalam hal ini, gunakan icon.content.

  • ADK_RESOURCE_ID: ID endpoint mesin penalaran tempat agen ADK di-deploy. Untuk mengetahui informasi selengkapnya tentang cara mencantumkan agen yang dihosting di Vertex AI Agent Engine dan mendapatkan ID resource, lihat Mencantumkan agen yang di-deploy.

  • REASONING_ENGINE_LOCATION: lokasi cloud mesin penalaran. Untuk mengetahui informasi selengkapnya, lihat Lokasi mesin penalaran.

  • authorizationConfig: Jika Anda mendapatkan detail otorisasi dan ingin agen mengakses resource Google Cloud atas nama pengguna, tambahkan kolom authorization_config ke resource JSON Anda.

     * <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.

Menambahkan pengguna yang diberi izin

Untuk menambahkan pengguna yang diberi izin ke agen ADK menggunakan konsol Google Cloud , lihat Menambahkan atau mengubah pengguna dan izin mereka.

Mencantumkan agen yang terhubung ke aplikasi

Contoh kode berikut menunjukkan cara mendapatkan detail semua agen yang terhubung ke aplikasi Anda:

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"

Ganti variabel dengan nilai:

  • ENDPOINT_LOCATION: multi-region untuk permintaan API Anda. Tentukan salah satu nilai berikut:
    • us untuk multi-region AS
    • eu untuk multi-region Uni Eropa
    • global untuk lokasi Global
    Untuk mengetahui informasi selengkapnya, lihat Menentukan multi-region untuk penyimpanan data Anda.
  • PROJECT_ID: ID Google Cloud project Anda.
  • LOCATION: multi-region aplikasi Anda: global, us, atau eu.
  • APP_ID: ID aplikasi Gemini Enterprise Anda.

Jika agen Anda tidak dibuat oleh Google, respons akan menyertakan kolom name di beberapa baris pertama. Nilai kolom ini berisi ID Agen di akhir jalur. Misalnya, dalam respons berikut, ID Agen adalah 12345678901234567890:

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

Melihat detail agen ADK

Contoh kode berikut menunjukkan cara mengambil detail agen yang terdaftar di 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"

Ganti variabel dengan nilai:

  • ENDPOINT_LOCATION: multi-region untuk permintaan API Anda. Tentukan salah satu nilai berikut:
    • us untuk multi-region AS
    • eu untuk multi-region Uni Eropa
    • global untuk lokasi Global
    Untuk mengetahui informasi selengkapnya, lihat Menentukan multi-region untuk penyimpanan data Anda.
  • PROJECT_ID: ID Google Cloud project Anda.
  • LOCATION: multi-region aplikasi Anda: global, us, atau eu.
  • APP_ID: ID aplikasi Gemini Enterprise Anda.
  • AGENT_ID: ID agen. Anda dapat menemukan ID agen dengan mencantumkan agen yang terhubung ke aplikasi Anda.

Memperbarui agen ADK

Anda dapat mengubah detail agen yang ada yang terdaftar di Gemini Enterprise menggunakan Google Cloud konsol atau REST API.

Konsol

Untuk mengupdate agen menggunakan konsol Google Cloud , ikuti langkah-langkah berikut:

  1. Di konsol Google Cloud , buka halaman Gemini Enterprise.

    Gemini Enterprise

  2. Klik nama aplikasi yang menyertakan agen yang ingin Anda perbarui.

  3. Klik Agen.

  4. Klik nama agen Agent engine yang ingin Anda perbarui, lalu klik Edit.

  5. Perbarui Nama tampilan, Deskripsi, atau mesin penalaran Agent Engine.

    Jalur resource memiliki format berikut:

      https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/ADK_RESOURCE_ID

    Untuk mengetahui informasi selengkapnya tentang cara mencantumkan agen yang dihosting di Vertex AI Agent Engine dan mendapatkan jalur resource, lihat Mencantumkan agen yang di-deploy.

  6. Klik Simpan.

REST

Anda dapat memperbarui semua kolom selama pendaftaran agen. Namun, kolom berikut harus diperbarui:

  • displayName
  • description

  • reasoningEngine

    Contoh kode ini menunjukkan cara memperbarui pendaftaran agen ADK yang ada:

    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"
         },
      }
}'

    Ganti variabel dengan nilai:

  • ENDPOINT_LOCATION: multi-region untuk permintaan API Anda. Tentukan salah satu nilai berikut:

    • us untuk multi-region AS
    • eu untuk multi-region Uni Eropa
    • global untuk lokasi Global
    Untuk mengetahui informasi selengkapnya, lihat Menentukan multi-region untuk penyimpanan data Anda.

  • PROJECT_ID: ID Google Cloud project Anda.

  • AGENT_RESOURCE_NAME: nama resource pendaftaran agen yang akan diperbarui.

  • DISPLAY_NAME: wajib diisi. Nama agen yang mudah digunakan untuk agen Anda yang ditampilkan di Gemini Enterprise.

  • DESCRIPTION: wajib diisi. Penjelasan singkat tentang fungsi agen Anda yang dapat dilihat oleh pengguna di Gemini Enterprise.

  • REASONING_ENGINE_LOCATION: wajib diisi. Lokasi cloud mesin penalaran tempat Anda membuat agen. Untuk mengetahui informasi selengkapnya, lihat Lokasi mesin penalaran.

  • ADK_RESOURCE_ID: ID endpoint mesin penalaran tempat agen ADK di-deploy. Untuk mengetahui informasi selengkapnya tentang cara mencantumkan agen yang dihosting di Vertex AI Agent Engine dan mendapatkan ID resource, lihat Mencantumkan agen yang di-deploy.

Menghapus agen ADK

Contoh kode berikut menunjukkan cara menghapus agen yang terhubung ke aplikasi Anda:

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"

Ganti variabel dengan nilai:

  • ENDPOINT_LOCATION: multi-region untuk permintaan API Anda. Tentukan salah satu nilai berikut:
    • us untuk multi-region AS
    • eu untuk multi-region Uni Eropa
    • global untuk lokasi Global
    Untuk mengetahui informasi selengkapnya, lihat Menentukan multi-region untuk penyimpanan data Anda.
  • PROJECT_ID: ID Google Cloud project Anda.
  • LOCATION: multi-region aplikasi Anda: global, us, atau eu
  • APP_ID: ID aplikasi Gemini Enterprise Anda.
  • AGENT_ID: ID agen. Anda dapat menemukan ID agen dengan mencantumkan agen yang terhubung ke aplikasi Anda.

Lokasi mesin penalaran

Saat mendaftarkan atau memperbarui agen ADK, lokasi resource mesin penalaran pokok harus kompatibel dengan lokasi agen Anda. Lokasi untuk mesin penalaran bergantung pada lokasi agen sebagai berikut:

  • Agen global: Jika agen Anda berada di lokasi global, Anda dapat menggunakan mesin penalaran yang di-deploy di region yang didukung.

  • Agen multi-region:

    • Jika agen Anda berada di multi-region us, mesin penalaran harus di-deploy di region berbasis Amerika Serikat, seperti us-central1, us-east1, atau us-west1.
    • Jika agen Anda berada di multi-region eu, mesin penalaran harus di-deploy di region Eropa, seperti europe-west1, europe-west2, atau europe-central2. Berikut tabel ringkasannya:
Lokasi Agen Lokasi mesin penalaran yang diizinkan
global Wilayah Google Cloud yang didukung
us Region apa pun yang diawali dengan us-, seperti us-central1 atau us-east4
eu Region apa pun yang diawali dengan europe-, seperti europe-west1 atau europe-west3

Lokasi yang tidak cocok akan menyebabkan error selama pendaftaran atau update agen.