Menggunakan agen Agent Development Kit

Sebelum memulai

Tutorial ini mengasumsikan bahwa Anda telah membaca dan mengikuti petunjuk dalam:

• Membuat agen Agent Development Kit: untuk membuat agent sebagai instance AdkApp.
• Autentikasi pengguna untuk mengautentikasi sebagai pengguna guna membuat kueri agen.
• Impor dan inisialisasi SDK untuk menginisialisasi klien guna mendapatkan instance yang di-deploy (jika diperlukan).

Mendapatkan instance agen

Untuk membuat kueri AdkApp, Anda harus membuat instance baru atau mendapatkan instance yang ada terlebih dahulu.

Untuk mendapatkan AdkApp yang sesuai dengan ID resource tertentu:

Agent Platform SDK

Jalankan kode berikut:

import vertexai

client = vertexai.Client(  # For service interactions via client.agent_engines
    project="PROJECT_ID",
    location="LOCATION",
)

adk_app = client.agent_engines.get(name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID")

print(adk_app)

di mana

• PROJECT_ID adalah Google Cloud project ID yang digunakan untuk membuat dan men-deploy agen,
• LOCATION adalah salah satu wilayah yang didukung, dan
• RESOURCE_ID adalah ID agen yang di-deploy sebagai reasoningEngine resource.

Library permintaan Python

Jalankan kode berikut:

from google import auth as google_auth
from google.auth.transport import requests as google_requests
import requests

def get_identity_token():
    credentials, _ = google_auth.default()
    auth_request = google_requests.Request()
    credentials.refresh(auth_request)
    return credentials.token

response = requests.get(
f"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
    headers={
        "Content-Type": "application/json; charset=utf-8",
        "Authorization": f"Bearer {get_identity_token()}",
    },
)

REST API

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID

Saat menggunakan Agent Platform SDK, objek adk_app sesuai dengan class AgentEngine yang berisi hal berikut:

• adk_app.api_resource dengan informasi tentang agen yang di-deploy. Anda juga dapat memanggil adk_app.operation_schemas() untuk menampilkan daftar operasi yang didukung adk_app. Lihat Operasi yang didukung untuk mengetahui detailnya.
• adk_app.api_client yang memungkinkan interaksi layanan sinkron
• adk_app.async_api_client yang memungkinkan interaksi layanan asinkron

Bagian selanjutnya mengasumsikan bahwa Anda memiliki instance AgentEngine, yang diberi nama adk_app.

Operasi yang didukung

Operasi berikut didukung untuk AdkApp:

• async_stream_query: untuk melakukan streaming respons terhadap kueri.

• async_create_session: untuk membuat sesi baru.

• async_list_sessions: untuk mencantumkan sesi yang tersedia.

• async_get_session: untuk mengambil sesi tertentu.

• async_delete_session: untuk menghapus sesi tertentu.

• async_add_session_to_memory: untuk membuat memori sesi.

• async_search_memory: untuk mengambil kenangan.

Untuk mencantumkan semua operasi yang didukung:

Agent Platform SDK

Jalankan kode berikut:

adk_app.operation_schemas()

Library permintaan Python

Jalankan kode berikut:

import json

json.loads(response.content).get("spec").get("classMethods")

REST API

Ditampilkan di spec.class_methods dari respons terhadap permintaan curl.

Mengelola sesi

AdkApp menggunakan sesi terkelola berbasis cloud setelah Anda men-deploy agen ke Agent Platform. Bagian ini menjelaskan cara menggunakan sesi terkelola.

Catatan: Petunjuk ini mengasumsikan bahwa Anda tidak menyesuaikan database menggunakan session_service_builder saat mengembangkan agen.

Membuat sesi

Untuk membuat sesi bagi pengguna, gunakan metode AdkApp.async_create_session:

Agent Platform SDK

session = await adk_app.async_create_session(user_id="USER_ID")

print(session)

Library permintaan Python

Jalankan kode berikut:

from google import auth as google_auth
from google.auth.transport import requests as google_requests
import requests
import json

def get_identity_token():
  credentials, _ = google_auth.default()
  auth_request = google_requests.Request()
  credentials.refresh(auth_request)
  return credentials.token

response = requests.post(
  f"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:query",
  headers={
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": f"Bearer {get_identity_token()}",
  },
  data=json.dumps({
    "class_method": "async_create_session",
    "input": {"user_id": "USER_ID"},
  }),
)
print(response.content)

REST API

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:query -d '{"class_method": "async_create_session", "input": {"user_id": "USER_ID"},}'

• USER_ID: Pilih ID pengguna Anda sendiri dengan batas karakter 128. Contoh, user-123.

Sesi dibuat sebagai representasi kamus dari objek sesi ADK.

Mencantumkan sesi

Untuk mencantumkan sesi pengguna, gunakan metode AdkApp.async_list_sessions:

Agent Platform SDK

response = await adk_app.async_list_sessions(user_id="USER_ID"):
for session in response.sessions:
    print(session)

Library permintaan Python

Jalankan kode berikut:

from google import auth as google_auth
from google.auth.transport import requests as google_requests
import requests
import json

def get_identity_token():
  credentials, _ = google_auth.default()
  auth_request = google_requests.Request()
  credentials.refresh(auth_request)
  return credentials.token

response = requests.post(
  f"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:query",
  headers={
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": f"Bearer {get_identity_token()}",
  },
  data=json.dumps({
    "class_method": "async_list_sessions",
    "input": {"user_id": "USER_ID"},
  }),
)
print(response.content)

REST API

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:query -d '{"class_method": "async_list_sessions", "input": {"user_id": "USER_ID"},}'

dengan USER_ID adalah ID pengguna yang Anda tentukan. Contoh, user-123.

Jika ada sesi yang ditampilkan, sesi tersebut menggunakan bentuk kamus dari objek sesi ADK.

Mendapatkan sesi

Untuk mendapatkan sesi tertentu, gunakan metode AdkApp.async_get_session:

Agent Platform SDK

session = await adk_app.async_get_session(user_id="USER_ID", session_id="SESSION_ID")

print(session)

Library permintaan Python

Jalankan kode berikut:

from google import auth as google_auth
from google.auth.transport import requests as google_requests
import requests
import json

def get_identity_token():
  credentials, _ = google_auth.default()
  auth_request = google_requests.Request()
  credentials.refresh(auth_request)
  return credentials.token

response = requests.post(
  f"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:query",
  headers={
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": f"Bearer {get_identity_token()}",
  },
  data=json.dumps({
    "class_method": "async_get_session",
    "input": {"user_id": "USER_ID", "session_id": "SESSION_ID"},
  }),
)
print(response.content)

REST API

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:query -d '{"class_method": "async_get_session", "input": {"user_id": "USER_ID", "session_id": "SESSION_ID"},}'

session adalah representasi kamus dari objek sesi ADK.

Menghapus sesi

Untuk menghapus sesi, gunakan metode AdkApp.async_delete_session:

Agent Platform SDK

await adk_app.async_delete_session(user_id="USER_ID", session_id="SESSION_ID")

Library permintaan Python

Jalankan kode berikut:

from google import auth as google_auth
from google.auth.transport import requests as google_requests
import requests
import json

def get_identity_token():
  credentials, _ = google_auth.default()
  auth_request = google_requests.Request()
  credentials.refresh(auth_request)
  return credentials.token

response = requests.post(
  f"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:query",
  headers={
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": f"Bearer {get_identity_token()}",
  },
  data=json.dumps({
    "class_method": "async_delete_session",
    "input": {"user_id": "USER_ID", "session_id": "SESSION_ID"},
  }),
)
print(response.content)

REST API

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:query -d '{"class_method": "async_delete_session", "input": {"user_id": "USER_ID", "session_id": "SESSION_ID"},}'

Mengalirkan respons terhadap kueri

Untuk melakukan streaming respons dari agen dalam sesi, gunakan metode AdkApp.async_stream_query:

Agent Platform SDK

async for event in adk_app.async_stream_query(
    user_id="USER_ID",
    #session_id="SESSION_ID",  # Optional
    message="What is the exchange rate from US dollars to SEK today?",
):
  print(event)

Library permintaan Python

from google import auth as google_auth
from google.auth.transport import requests as google_requests
import requests

def get_identity_token():
    credentials, _ = google_auth.default()
    auth_request = google_requests.Request()
    credentials.refresh(auth_request)
    return credentials.token

requests.post(
    f"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:streamQuery",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {get_identity_token()}",
    },
    data=json.dumps({
        "class_method": "async_stream_query",
        "input": {
            "user_id": "USER_ID",
            #"session_id": "SESSION_ID",
            "message": "What is the exchange rate from US dollars to SEK today?",
        },
    }),
    stream=True,
)

REST API

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:streamQuery?alt=sse -d '{
  "class_method": "async_stream_query",
  "input": {
    "user_id": "USER_ID",
    #"session_id": "SESSION_ID",
    "message": "What is the exchange rate from US dollars to SEK today?",
  }
}'

Catatan: argumen session_id= bersifat opsional. Jika tidak ditentukan, sesi baru akan otomatis dibuat dan digunakan untuk menayangkan kueri tersebut. Jika ID sesi yang diberikan tidak ada, respons kosong akan ditampilkan. Sebaiknya Anda tidak menyertakannya jika hanya memeriksa apakah agen dapat dijangkau.

Jika Anda menggunakan Agent Platform SDK, Anda akan menerima kelanjutan percakapan seperti urutan kamus berikut:

{'author': 'currency_exchange_agent',
 'content': {'parts': [{'function_call': {'args': {'currency_date': '2025-04-03',
                                                   'currency_from': 'USD',
                                                   'currency_to': 'SEK'},
                                          'id': 'adk-2b9230a6-4b92-4a1b-9a65-b708ff6c68b6',
                                          'name': 'get_exchange_rate'}}],
             'role': 'model'},
 'id': 'bOPHtzji',
 # ...
}
{'author': 'currency_exchange_agent',
 'content': {'parts': [{'function_response': {'id': 'adk-2b9230a6-4b92-4a1b-9a65-b708ff6c68b6',
                                              'name': 'get_exchange_rate',
                                              'response': {'amount': 1.0,
                                                           'base': 'USD',
                                                           'date': '2025-04-03',
                                                           'rates': {'SEK': 9.6607}}}}],
             'role': 'user'},
 'id': '9AoDFmiL',
 # ...
}
{'author': 'currency_exchange_agent',
 'content': {'parts': [{'text': 'The exchange rate from USD to SEK on '
                                '2025-04-03 is 1 USD to 9.6607 SEK.'}],
             'role': 'model'},
 'id': 'hmle7trT',
 # ...
}

Tugas kueri yang berjalan lama

Untuk kueri yang memerlukan waktu lama untuk diselesaikan (hingga tujuh hari), Anda dapat menjalankannya sebagai tugas yang berjalan lama. Tugas ini berjalan secara asinkron. Anda dapat memeriksa status tugas dan mengambil hasil nanti.

Catatan: Anda hanya dapat menjalankan tugas yang berjalan lama di resource reasoningEngine yang telah dibuat pada 22 April 2026 atau yang lebih baru. Anda tidak dapat mengupdate resource reasoningEngine yang dibuat sebelumnya untuk menjalankan tugas yang berjalan lama.

Men-deploy agen untuk kueri asinkron

Untuk men-deploy agen, ikuti petunjuk umum di Men-deploy agen. Untuk deployment berbasis sumber, tetapkan kolom deploymentSpec.agentFramework ke google-adk.

Jika menggunakan endpoint API kustom dengan membuat image container Anda sendiri, Anda harus menambahkan variabel lingkungan berikut saat membuat agen menggunakan SDK:

"env_vars" = {
    "API_ENDPOINT_PREFIX": "/api/myendpoint"
}

Mulai tugas kueri yang berjalan lama

Sebagai prasyarat, Anda harus memberikan peran roles/storage.objectCreator kepada agen layanan [e-mail] untuk bucket penyimpanan file output.

Untuk memulai tugas kueri yang berjalan lama:

Agent Platform SDK

import vertexai

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
)

response = client.agent_engines.run_query_job(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
    config={
        "query": '{"input":{"user_id":"USER_ID", "message":"What is the exchange rate from US dollars to SEK today?"}}',
        "output_gcs_uri": "gs://GCS_BUCKET_NAME/OUTPUT_FILE",
    },
)
print(response)

Dengan SDK, output_gcs_uri dapat berupa direktori atau nama file. Jika berupa nama file, sistem akan menggunakan file ini untuk menyimpan respons. Jika berupa direktori, sistem akan otomatis membuat file untuk respons. Dalam kedua kasus tersebut, kueri input disimpan di direktori yang sama dengan imbuhan nama file yang sama seperti file output.

REST

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:asyncQuery -d \
'{
  "input_gcs_uri": "gs://GCS_BUCKET_NAME/INPUT_FILE",
  "output_gcs_uri": "gs://GCS_BUCKET_NAME/OUTPUT_FILE"
}'

Untuk panggilan REST API, kolom input_gcs_uri harus mengarah ke file yang berisi kueri. Konten file harus berupa objek JSON dengan kolom input yang cocok dengan kolom input dari QueryReasoningEngineRequest (seperti { "input": { "user_id": "hello", "message":"$QUERY"} }). Jika file input ini berada di bucket yang berbeda dengan lokasi output, Anda juga harus memberikan peran roles/storage.objectReader kepada agen layanan [e-mail] ke bucket penyimpanan tempat file input berada.

output_gcs_uri harus berupa nama file.

Memeriksa status tugas kueri yang berjalan lama

Untuk memeriksa status dan mengambil hasil tugas kueri yang berjalan lama:

Agent Platform SDK

response = client.agent_engines.check_query_job(
    name="JOB_NAME",
    config={
        "retrieve_result": True,
    },
)
print(response)

Membatalkan tugas kueri yang berjalan lama

Untuk membatalkan tugas kueri yang berjalan lama, Anda harus memiliki nama resource LRO yang ditampilkan dari tugas kueri yang berjalan lama.

Agent Platform SDK

response = client.agent_engines.cancel_query_job(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
    config={
        "operation_name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
    },
)

REST

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:cancelAsyncQuery -d \
'{
  "name": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
  "operation_name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"
}'

Pembatalan bersifat asinkron. Permintaan pembatalan akan ditampilkan segera setelah diterima, tetapi tugas dapat terus melaporkan status RUNNING dari check_query_job hingga tugas yang sudah dalam proses, seperti panggilan alat pemblokiran, selesai.

Setelah dibatalkan, operasi tugas akan selesai dengan kode error 1 (CANCELLED) dan pesan Cancelled by user.. Perhatikan bahwa check_query_job melaporkan setiap operasi yang selesai dengan error sebagai status FAILED, sehingga tugas yang dibatalkan dilaporkan sebagai FAILED, bukan melalui status dibatalkan yang berbeda. Periksa kode error untuk membedakan pembatalan dengan kegagalan asli.

Mengelola kenangan

AdkApp menggunakan Memory Bank jika Anda menyertakan PreloadMemoryTool dalam definisi agen dan men-deploy agen ke Agent Platform. Bagian ini menjelaskan cara menggunakan pembuatan dan pengambilan memori dari agen melalui penerapan default layanan memori ADK.

Menambahkan sesi ke memori

Untuk menyimpan memori informasi penting dalam sesi (yang dapat digunakan dalam sesi mendatang), gunakan metode async_add_session_to_memory:

Agent Platform SDK

await adk_app.async_add_session_to_memory(session="SESSION_DICT")

dengan SESSION_DICT adalah bentuk kamus dari objek sesi ADK.

Menelusuri kenangan

Untuk menelusuri memori agen, Anda dapat menggunakan metode async_search_memory:

Agent Platform SDK

response = await adk_app.async_search_memory(
    user_id="USER_ID",
    query="QUERY",
)
print(response)

di mana

• USER_ID adalah cakupan untuk kenangan yang relevan.
• QUERY adalah kueri yang akan digunakan untuk melakukan penelusuran kemiripan.

Langkah berikutnya

• Gunakan agen.
• Mengevaluasi agen.
• Mengelola agen yang di-deploy.
• Dapatkan dukungan.