Mengelola sesi menggunakan panggilan API atau konsol Google Cloud

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:

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:

  1. Di konsol Google Cloud , buka halaman Deployments Agent Platform.

    Buka Deployment

    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.

  2. Klik nama instance Agent Engine Anda.

  3. 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:

  1. Di konsol Google Cloud , buka halaman Deployments Agent Platform.

    Buka Deployment

    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.

  2. Klik nama instance Agent Engine Anda.

  3. Klik tab Playground.

  4. 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 Content

    Anda 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:

  1. Di konsol Google Cloud , buka halaman Deployments Agent Platform.

    Buka Deployment

    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.

  2. Klik nama instance Agent Engine Anda.

  3. Klik tab Playground.

  4. Klik tab Sesi. Daftar sesi ditampilkan menurut ID.

  5. 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:

  1. Di konsol Google Cloud , buka halaman Deployments Agent Platform.

    Buka Deployment

    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.

  2. Klik nama instance Agent Engine Anda.

  3. Klik tab Sesi. Daftar sesi ditampilkan menurut ID.

  4. Klik menu tindakan lainnya () dari sesi yang ingin Anda hapus.

  5. Klik Hapus.

  6. 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:

  1. Di konsol Google Cloud , buka halaman Deployments Agent Platform.

    Buka Deployment

    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.

  2. Klik nama instance Agent Engine Anda.

  3. Klik tab Playground.

  4. Klik tab Sesi. Daftar sesi ditampilkan menurut ID.

  5. Klik sesi yang ingin Anda lihat secara lebih detail.

  6. 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:

  1. Di konsol Google Cloud , buka halaman Deployments Agent Platform.

    Buka Deployment

    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.

  2. Klik nama instance Agent Engine Anda.

  3. Klik tab Playground.

  4. Klik tab Sesi. Daftar sesi ditampilkan menurut ID.

  5. Klik sesi yang ingin Anda lihat secara lebih detail.

  6. Klik tab Events untuk melihat peristiwa yang terkait dengan sesi.

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

    Anda 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)