Halaman ini diterjemahkan oleh Cloud Translation API.

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.

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

Buka Kredensial
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.
Klik Buat kredensial, lalu pilih ID klien OAuth.
Di Application type, pilih Web application.
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
Klik Buat.
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 ini 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. Tetapkan 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 yang Anda peroleh saat membuat kredensial OAuth. Formatnya adalah sebagai berikut: 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: URI token yang Anda peroleh saat 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:

Di konsol Google Cloud , buka halaman Gemini Enterprise.

Gemini Enterprise
Klik nama aplikasi yang ingin Anda daftarkan agennya.
Klik Agents > Add Agents.
Di bagian Choose an agent type, klik Add untuk Custom agent via Agent Engine.
Jika Anda ingin agen mengakses Google Cloud resource atas nama Anda, ikuti langkah-langkah berikut:
1. Klik Tambahkan otorisasi.
2. Masukkan nilai unik untuk Nama otorisasi. ID dibuat berdasarkan nama dan tidak dapat diubah nanti.
3. Masukkan Client ID, Client secret, Authorization URI, dan Token URI yang Anda buat di bagian Mendapatkan detail otorisasi.
4. Klik Tambahkan otorisasi.
Klik Berikutnya.
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. Konfigurasi Setelan alat:
  1. Masukkan deskripsi untuk kolom Deskripsi alat. Deskripsi ini digunakan oleh LLM untuk memahami tujuan alat dan memutuskan kapan harus menggunakannya.
  2. Masukkan nama di kolom Input parameter name. Ini adalah nama parameter untuk panggilan fungsi. Nama parameter ini memberi petunjuk kepada LLM tentang jenis input yang diharapkan, seperti question, command, atau search_query.
  3. Masukkan deskripsi untuk kolom Deskripsi parameter input. Deskripsi parameter ini memberikan informasi lebih lanjut kepada LLM tentang parameter, seperti konten yang diharapkan dan tindakan yang akan dilakukan.
5. Klik Buat.

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

Ganti variabel dengan nilai:

ENDPOINT_LOCATION-: multi-region untuk permintaan API Anda. Tetapkan 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.
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.
```

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. Tetapkan 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. Tetapkan 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 Google Cloud konsol, ikuti langkah-langkah berikut:

Di konsol Google Cloud , buka halaman Gemini Enterprise.

Gemini Enterprise
Klik nama aplikasi yang menyertakan agen yang ingin Anda perbarui.
Klik Agen.
Klik nama agen Agent engine yang ingin Anda perbarui, lalu klik Edit.
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.
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. Tetapkan 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. 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 inferensi.
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. Tetapkan 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.

Contoh perintah dan hasil

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
}

Lokasi mesin penalaran

Untuk melakukan panggilan API ke lokasi mesin penalaran yang benar, gunakan diagram berikut:

Lokasi cloud yang Anda panggil	Lokasi mesin penalaran
`us`	`us-central1`
`eu`	`europe-west1`
lainnya (termasuk `global`)	`us-central1`

Mendaftarkan dan mengelola agen ADK yang dihosting di Vertex AI Agent Engine Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sebelum memulai

Mengonfigurasi detail otorisasi

Mendapatkan detail otorisasi

Menambahkan resource otorisasi ke Gemini Enterprise

REST

Mendaftarkan agen ADK dengan Gemini Enterprise

Konsol

REST

Mencantumkan agen yang terhubung ke aplikasi

REST

Melihat detail agen ADK

REST

Memperbarui agen ADK

Konsol

REST

Menghapus agen ADK

REST

Contoh perintah dan hasil

Lokasi mesin penalaran

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