Bagian ini menjelaskan cara menggunakan Sesi Agent Platform untuk mengelola sesi menggunakan konsol Google Cloud atau panggilan API langsung. Anda dapat menggunakan konsol Google Cloud atau panggilan API langsung jika tidak ingin menggunakan agen ADK untuk mengelola sesi.
Untuk mengelola sesi menggunakan agen ADK, lihat Mengelola sesi dengan Agent Development Kit (ADK).
Membuat instance Agent Runtime
Untuk mengakses Agent Platform Sessions, Anda harus menggunakan instance Agent Runtime terlebih dahulu. Anda tidak perlu men-deploy kode apa pun untuk mulai menggunakan Sesi. Jika Anda pernah menggunakan Agent Runtime sebelumnya, membuat instance Agent Runtime hanya memerlukan waktu beberapa detik tanpa deployment kode. Proses ini mungkin memerlukan waktu lebih lama jika ini adalah pertama kalinya Anda menggunakan Agent Runtime.
Jika Anda belum memiliki instance Agent Runtime, buat instance menggunakan kode berikut:
import agentplatform
client = agentplatform.Client(
project="PROJECT_ID",
location="LOCATION"
)
# If you don't have an Agent Runtime instance already, create an instance.
remote_agent = client.runtimes.create()
# Optionally, print out the Agent Runtime resource name. You will need the
# resource name to interact with Sessions later on.
print(remote_agent.api_resource.name)
Ganti kode berikut:
- PROJECT_ID: Project ID Anda.
- LOCATION: Region Anda. Lihat wilayah yang didukung untuk Sesi.
Mencantumkan sesi
Mencantumkan sesi yang terkait dengan instance Agent Runtime Anda.
Konsol
Untuk agen yang di-deploy, Anda dapat menggunakan konsol Google Cloud untuk mencantumkan sesi yang terkait dengan agen Anda:
- Di konsol Google Cloud , buka halaman Deployments Agent Platform.
Instance Agent Engine yang merupakan bagian dari project yang dipilih akan muncul dalam daftar. Anda dapat menggunakan kolom Filter untuk memfilter daftar menurut kolom yang ditentukan.
Klik nama instance Agent Engine Anda.
Klik tab Sesi. Daftar sesi ditampilkan menurut ID.
Python
for session in client.sessions.list(
name=remote_agent.api_resource.name, # Required
):
print(session)
# To list sessions for a specific user:
for session in client.sessions.list(
name=remote_agent.api_resource.name, # Required
config={"filter": "user_id=USER_ID"},
):
print(session)
- USER_ID: Pilih ID pengguna Anda sendiri dengan batas karakter 128.
Contoh,
user-123.
Secara default, client.sessions.list menampilkan sesi yang diurutkan berdasarkan waktu pembuatan
dalam urutan menurun (create_time desc). Urutan default ini menjaga penomoran halaman tetap
stabil saat sesi aktif diperbarui secara serentak. Python SDK tidak mengekspos opsi order_by. Untuk mengurutkan berdasarkan kolom lain, gunakan REST API.
REST
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- PROJECT_ID: Project ID Anda.
- LOCATION: Region tempat Anda membuat instance Agent Engine.
- AGENT_ENGINE_ID: ID resource instance Agent Engine Anda.
Metode HTTP dan URL:
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions
Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl
Jalankan perintah berikut:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions"
PowerShell
Jalankan perintah berikut:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions" | Select-Object -Expand Content
Anda akan melihat daftar sesi yang ditampilkan.
Secara opsional, untuk mencantumkan sesi bagi pengguna tertentu, Anda dapat menambahkan parameter kueri ?filter=user_id=\"USER_ID\", dengan USER_ID adalah ID pengguna yang ingin Anda kueri.
Untuk mengurutkan sesi yang ditampilkan, tambahkan parameter kueri
?orderBy=ORDER_BY, dengan
ORDER_BY adalah create_time, update_time, atau
display_name. Anda dapat menambahkan %20desc untuk urutan menurun, seperti
?orderBy=create_time%20desc. Jika Anda menghilangkan orderBy, API akan menampilkan sesi yang diurutkan berdasarkan create_time desc. Gunakan create_time desc saat Anda
membuat nomor halaman melalui sesi selama update serentak sehingga update tidak
menggeser sesi melintasi batas halaman.
Membuat sesi
Membuat sesi yang terkait dengan ID pengguna.
Konsol
Untuk agen yang di-deploy, Anda dapat menggunakan konsol Google Cloud untuk membuat sesi:
- Di konsol Google Cloud , buka halaman Deployments Agent Platform.
Instance Agent Engine yang merupakan bagian dari project yang dipilih akan muncul dalam daftar. Anda dapat menggunakan kolom Filter untuk memfilter daftar menurut kolom yang ditentukan.
Klik nama instance Agent Engine Anda.
Klik tab Playground.
Klik Sesi baru untuk membuat sesi baru.
Python
session = client.sessions.create(
name=remote_agent.api_resource.name, # Required
user_id=USER_ID, # Required
session_id=SESSION_ID,
)
dengan USER_ID sebagai ID pengguna yang Anda tentukan. Contoh,
user-123.
Untuk SESSION_ID, pertimbangkan batasan berikut untuk mencegah tabrakan dengan ID yang dibuat sistem:
- Jika karakter pertama adalah huruf, ID dapat memiliki panjang hingga 63 karakter.
Karakter yang valid adalah huruf kecil, angka, dan tanda hubung (
[a-z0-9-]). Karakter terakhir harus berupa huruf atau angka - Jika karakter pertama adalah angka, ID dapat memiliki panjang hingga 9 karakter.
Karakter yang valid adalah angka (
[0-9]) tanpa angka nol di awal.
REST
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- PROJECT_ID: Project ID Anda.
- LOCATION: Region tempat Anda membuat instance Agent Engine.
- AGENT_ENGINE_ID: ID resource instance Agent Engine Anda.
- USER_ID: ID pengguna yang Anda tentukan. Contoh,
sessions-agent. - SESSION_ID: ID sesi yang Anda tentukan. Contoh,
my-custom-session.Untuk mencegah konflik dengan ID yang dibuat sistem, ikuti batasan berikut saat Anda menentukan ID sesi kustom:
- Jika karakter pertama adalah huruf, ID dapat memiliki panjang hingga 63 karakter. Karakter yang valid adalah huruf kecil, angka, dan tanda hubung (`[a-z0-9-]`). Karakter terakhir harus berupa huruf atau angka.
- Jika karakter pertama adalah angka, ID dapat memiliki panjang hingga 9 karakter. Karakter yang valid adalah angka (`[0-9]`) tanpa angka nol di awal.
Metode HTTP dan URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions
Meminta isi JSON:
{ "userId": USER_ID }Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl
Simpan isi permintaan dalam file bernama
request.json, dan jalankan perintah berikut:curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions"PowerShell
Simpan isi permintaan dalam file bernama
request.json, dan jalankan perintah berikut:$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions" | Select-Object -Expand ContentAnda akan menerima operasi yang berjalan lama yang dapat Anda kueri untuk memeriksa status pembuatan sesi Anda.
Mengonfigurasi time to live (TTL) sesi
Semua sesi harus memiliki waktu habis masa berlaku. Anda dapat menentukan waktu habis masa berlaku ini saat membuat atau memperbarui sesi. Sesi dan peristiwa turunannya akan otomatis dihapus setelah waktu habis masa berlaku berlalu. Anda dapat menetapkan waktu habis masa berlaku (expire_time) secara langsung atau menetapkan masa aktif (ttl) dalam detik. Jika tidak ada yang ditentukan, sistem akan menerapkan TTL default selama 365 hari.
Time to live (TTL)
Jika Anda menetapkan waktu aktif, server akan menghitung waktu habis masa berlaku sebagai create_time + ttl untuk sesi yang baru dibuat atau update_time + ttl untuk sesi yang diperbarui.
client.sessions.create(
name=remote_agent.api_resource.name, # Required
user_id=USER_ID, # Required
config={
# Session will be deleted 10 days after creation time.
"ttl": f"{24 * 60 * 60 * 10}s"
}
)
Waktu habis masa berlaku
import datetime
client.sessions.create(
name=remote_agent.api_resource.name, # Required
user_id=USER_ID, # Required
config={
# Session will be deleted at the provided time (10 days after current time).
"expire_time": datetime.datetime.now(tz=datetime.timezone.utc) + datetime.timedelta(seconds=24 * 60 * 60 * 10),
}
)
Mendapatkan sesi
Mendapatkan sesi tertentu yang terkait dengan instance Agent Platform Anda.
Konsol
Untuk agen yang di-deploy, Anda dapat menggunakan konsol Google Cloud untuk membuat sesi:
- Di konsol Google Cloud , buka halaman Deployments Agent Platform.
Instance Agent Engine yang merupakan bagian dari project yang dipilih akan muncul dalam daftar. Anda dapat menggunakan kolom Filter untuk memfilter daftar menurut kolom yang ditentukan.
Klik nama instance Agent Engine Anda.
Klik tab Playground.
Klik tab Sesi. Daftar sesi ditampilkan menurut ID.
Klik sesi yang ingin Anda lihat secara lebih detail.
Python
session = client.sessions.get(
name='projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID', # Required
user_id=USER_ID, # Required
)
# session.name will correspond to
# 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID'
REST
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- PROJECT_ID: Project ID Anda.
- LOCATION: Region tempat Anda membuat instance Agent Engine.
- AGENT_ENGINE_ID: ID resource instance Agent Engine Anda.
- SESSION_ID: ID resource sesi yang ingin Anda ambil. Anda bisa mendapatkan ID sesi dari respons yang Anda terima saat membuat sesi.
Metode HTTP dan URL:
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID
Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl
Jalankan perintah berikut:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID"
PowerShell
Jalankan perintah berikut:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID" | Select-Object -Expand Content
Dalam respons, Anda akan melihat informasi tentang sesi Anda.
Menghapus sesi
Menghapus sesi yang terkait dengan instance Agent Platform Anda.
Konsol
Untuk agen yang di-deploy, Anda dapat menggunakan konsol Google Cloud untuk menghapus sesi yang terkait dengan agen Anda:
- Di konsol Google Cloud , buka halaman Deployments Agent Platform.
Instance Agent Engine yang merupakan bagian dari project yang dipilih akan muncul dalam daftar. Anda dapat menggunakan kolom Filter untuk memfilter daftar menurut kolom yang ditentukan.
Klik nama instance Agent Engine Anda.
Klik tab Sesi. Daftar sesi ditampilkan menurut ID.
Klik menu tindakan lainnya () dari sesi yang ingin Anda hapus.
Klik Hapus.
Klik Hapus sesi.
Python
client.sessions.delete(name=session.name)
REST
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- PROJECT_ID: Project ID Anda.
- LOCATION: Region tempat Anda ingin membuat instance Example Store.
- AGENT_ENGINE_ID: ID resource instance Agent Engine Anda.
- SESSION_ID: ID resource sesi yang ingin Anda ambil.
Metode HTTP dan URL:
DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID
Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl
Jalankan perintah berikut:
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID"
PowerShell
Jalankan perintah berikut:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method DELETE `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID" | Select-Object -Expand Content
Anda akan menerima kode status berhasil (2xx) dan respons kosong.
Mencantumkan peristiwa dalam sesi
Mencantumkan peristiwa dalam sesi yang terkait dengan instance Agent Platform Anda.
Konsol
Untuk agen yang di-deploy, Anda dapat menggunakan konsol Google Cloud untuk membuat sesi:
- Di konsol Google Cloud , buka halaman Deployments Agent Platform.
Instance Agent Engine yang merupakan bagian dari project yang dipilih akan muncul dalam daftar. Anda dapat menggunakan kolom Filter untuk memfilter daftar menurut kolom yang ditentukan.
Klik nama instance Agent Engine Anda.
Klik tab Playground.
Klik tab Sesi. Daftar sesi ditampilkan menurut ID.
Klik sesi yang ingin Anda lihat secara lebih detail.
Klik tab Events untuk melihat peristiwa yang terkait dengan sesi.
Python
for session_event in client.sessions.events.list(
name=session.name,
):
print(session_event)
REST
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- PROJECT_ID: Project ID Anda.
- LOCATION: Region tempat Anda membuat instance Agent Engine.
- AGENT_ENGINE_ID: ID resource instance Agent Engine Anda.
- SESSION_ID: ID resource sesi yang ingin Anda ambil.
Metode HTTP dan URL:
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID/events
Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl
Jalankan perintah berikut:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID/events"
PowerShell
Jalankan perintah berikut:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID/events" | Select-Object -Expand Content
Dalam respons, Anda akan melihat daftar peristiwa yang terkait dengan sesi Anda.
Menambahkan peristiwa ke sesi
Menambahkan peristiwa ke sesi yang terkait dengan instance Agent Platform.
Konsol
Untuk agen yang di-deploy, Anda dapat menggunakan konsol Google Cloud untuk membuat sesi:
- Di konsol Google Cloud , buka halaman Deployments Agent Platform.
Instance Agent Engine yang merupakan bagian dari project yang dipilih akan muncul dalam daftar. Anda dapat menggunakan kolom Filter untuk memfilter daftar menurut kolom yang ditentukan.
Klik nama instance Agent Engine Anda.
Klik tab Playground.
Klik tab Sesi. Daftar sesi ditampilkan menurut ID.
Klik sesi yang ingin Anda lihat secara lebih detail.
Klik tab Events untuk melihat peristiwa yang terkait dengan sesi.
Ketik pesan, lalu tekan Enter untuk menambahkan peristiwa baru ke sesi.
Python
import datetime
client.sessions.events.append(
name=session.name,
author="user", # Required.
invocation_id="1", # Required.
timestamp=datetime.datetime.now(tz=datetime.timezone.utc), # Required.
config={
"content": {
"role": "user",
"parts": [{"text": "hello"}]
},
},
)
Atau, Anda dapat menggunakan kolom raw_event untuk menyertakan data arbitrer dalam peristiwa sesi. Hal ini berguna untuk interoperabilitas dengan framework agen lain atau untuk menyimpan data peristiwa kustom.
client.sessions.events.append(
name=session.name,
author="user", # Required.
invocation_id="1", # Required.
timestamp=datetime.datetime.now(tz=datetime.timezone.utc), # Required.
config={
"raw_event": {
"content": "hello",
"custom_field": "custom_value"
},
},
)
REST
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- PROJECT_ID: Project ID Anda.
- LOCATION: Region tempat Anda membuat instance Agent Engine.
- AGENT_ENGINE_ID: ID resource instance Agent Engine Anda.
- USER_ID: ID pengguna yang Anda tentukan. Contoh,
sessions-agent. - SESSION_ID: ID sesi yang Anda tentukan. Contoh,
my-custom-session.Untuk mencegah konflik dengan ID yang dibuat sistem, ikuti batasan berikut saat Anda menentukan ID sesi kustom:
- Jika karakter pertama adalah huruf, ID dapat memiliki panjang hingga 63 karakter. Karakter yang valid adalah huruf kecil, angka, dan tanda hubung (`[a-z0-9-]`). Karakter terakhir harus berupa huruf atau angka.
- Jika karakter pertama adalah angka, ID dapat memiliki panjang hingga 9 karakter. Karakter yang valid adalah angka (`[0-9]`) tanpa angka nol di awal.
Metode HTTP dan URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions
Meminta isi JSON:
{ "userId": USER_ID }Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl
Simpan isi permintaan dalam file bernama
request.json, dan jalankan perintah berikut:curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions"PowerShell
Simpan isi permintaan dalam file bernama
request.json, dan jalankan perintah berikut:$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions" | Select-Object -Expand ContentAnda akan menerima operasi yang berjalan lama yang dapat Anda kueri untuk memeriksa status pembuatan sesi Anda.
Pembersihan
Untuk membersihkan semua resource yang digunakan dalam project ini, Anda dapat menghapus instance Agent Platform beserta resource turunannya:
remote_agent.delete(force=True)