Menggunakan agen ADK

Sebelum memulai

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

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

Mendapatkan instance agen

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

Untuk mendapatkan AdkApp yang sesuai dengan ID resource tertentu:

Agent Platform SDK

Jalankan kode berikut:

import agentplatform

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

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

print(adk_app)

di mana

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

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 AgentRuntime 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 AgentRuntime, yang diberi nama adk_app.

Operasi yang didukung

Operasi berikut didukung untuk AdkApp:

• async_stream_query: untuk menstreaming respons ke 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 kenangan dari suatu 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

Direpresentasikan dalam 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 bagi 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 sebagai ID pengguna yang Anda tentukan. Contoh, user-123.

Jika ada sesi yang ditampilkan, sesi tersebut akan 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"},}'

Melakukan streaming respons terhadap kueri

Catatan: Durasi maksimum untuk permintaan streamQuery adalah 10 menit. Untuk alur kerja yang memerlukan waktu eksekusi lebih lama, gunakan Tugas kueri yang berjalan lama.

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 menyajikan kueri tersebut. Jika ID sesi yang diberikan tidak ada, respons kosong akan ditampilkan. Sebaiknya Anda tidak menyertakan ini 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 hasilnya 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 Anda menggunakan endpoint API kustom dengan membangun image container Anda sendiri, Anda harus menambahkan variabel lingkungan berikut saat membuat agen menggunakan SDK:

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

Memulai tugas kueri yang berjalan lama

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

Untuk memulai tugas kueri yang berjalan lama:

Agent Platform SDK

import agentplatform

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

response = client.runtimes.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 awalan nama file yang sama dengan 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 dari 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.runtimes.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.runtimes.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 pekerjaan yang sudah berjalan, seperti panggilan alat pemblokiran, selesai.

Setelah tugas dibatalkan, operasinya 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 dari kegagalan yang sebenarnya.

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, membuat, dan mengambil memori dari agen melalui implementasi default layanan memori ADK.

Menambahkan sesi ke memori

Untuk mempertahankan memori informasi yang bermakna 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 memori yang relevan.
• QUERY adalah kueri untuk melakukan penelusuran kemiripan.

Langkah berikutnya

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