Menggunakan agen Agent Development Kit

Sebelum memulai

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

• Mengembangkan agen Agent Development Kit: untuk mengembangkan 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:

Vertex AI SDK untuk Python

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)

dengan

• PROJECT_ID adalah Google Cloud project ID yang digunakan untuk mengembangkan 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

Mode Ekspres Vertex AI

Anda dapat menggunakan Vertex AI SDK untuk Python dengan Kunci API Mode Ekspres Anda:

import vertexai

client = vertexai.Client(  # For service interactions via client.agent_engines
    api_key="API_KEY",
)

adk_app = client.agent_engines.get(name="AGENT_ENGINE_NAME")

print(adk_app)

dengan

• AGENT_ENGINE_NAME adalah nama lengkap resource Agent Engine Anda.

Catatan: Operasi yang didukung berikut semuanya didukung untuk pengguna Mode Ekspres Vertex AI melalui Vertex AI SDK untuk Python

Saat menggunakan Vertex AI SDK untuk Python, 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:

Vertex AI SDK untuk Python

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 Vertex AI Agent Engine. 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:

Vertex AI SDK untuk Python

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://{adk_app.api_client.api_endpoint}/v1/{adk_app.resource_name}: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:

Vertex AI SDK untuk Python

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://{adk_app.api_client.api_endpoint}/v1/{adk_app.resource_name}: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, Anda memerlukan ID pengguna dan ID sesi:

Vertex AI SDK untuk Python

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://{adk_app.api_client.api_endpoint}/v1/{adk_app.resource_name}: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, Anda memerlukan ID pengguna dan ID sesi:

Vertex AI SDK untuk Python

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://{adk_app.api_client.api_endpoint}/v1/{adk_app.resource_name}: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 men-streaming respons dari agen dalam sesi:

Vertex AI SDK untuk Python

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://{adk_app.api_client.api_endpoint}/v1/{adk_app.resource_name}: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 menggunakan Vertex AI SDK untuk Python, 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',
 # ...
}

Mengelola kenangan

AdkApp menggunakan Vertex AI Agent Engine Memory Bank jika Anda menyertakan PreloadMemoryTool dalam definisi agen dan men-deploy agen ke Vertex AI Agent Engine. Bagian ini menjelaskan cara menggunakan pembuatan dan pengambilan kenangan 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:

Vertex AI SDK untuk Python

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:

Vertex AI SDK untuk Python

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

dengan

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