Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Mengelola sesi menggunakan panggilan API atau konsol Google Cloud

Bagian ini menjelaskan cara menggunakan Sesi Platform Agen untuk mengelola sesi menggunakan konsol Google Cloud atau panggilan API langsung. Anda dapat menggunakan panggilan API langsung atau konsol jika tidak ingin menggunakan agen ADK untuk mengelola sesi. Google Cloud

Untuk mengelola sesi menggunakan agen ADK, lihat Mengelola sesi dengan Agent Development Kit.

Membuat instance Agent Runtime

Untuk mengakses Sesi Platform Agen, Anda harus menggunakan instance Runtime Agen terlebih dahulu. Anda tidak perlu men-deploy kode apa pun untuk mulai menggunakan Sesi. Jika Anda pernah menggunakan Agent Engine sebelumnya, pembuatan instance Runtime Agen hanya memerlukan waktu beberapa detik tanpa deployment kode. Proses ini mungkin memerlukan waktu lebih lama jika Anda menggunakan Agent Engine untuk pertama kalinya.

Jika Anda belum memiliki instance Agent Runtime, buat instance menggunakan kode berikut:

import vertexai

client = vertexai.Client(
  project="PROJECT_ID",
  location="LOCATION"
)
# If you don't have an Agent Engine instance already, create an instance.
agent_engine = client.agent_engines.create()

# Optionally, print out the Agent Engine resource name. You will need the
# resource name to interact with Sessions later on.
print(agent_engine.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.

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 Anda tentukan.
Klik nama instance Agent Engine Anda.
Klik tab Sesi. Daftar sesi ditampilkan menurut ID.

Python

for session in client.agent_engines.sessions.list(
    name=agent_engine.api_resource.name,  # Required
):
    print(session)

# To list sessions for a specific user:
for session in client.agent_engines.sessions.list(
    name=agent_engine.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.

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

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

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

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

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.

Jika perlu, untuk mencantumkan sesi pengguna tertentu, Anda dapat menambahkan parameter kueri ?filter=user_id=\"USER_ID\", dengan USER_ID adalah ID pengguna yang ingin Anda kueri.

Membuat sesi

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

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 Anda tentukan.
Klik nama instance Agent Engine Anda.
Klik tab Playground.
Klik Sesi baru untuk membuat sesi baru.

Python

session = client.agent_engines.sessions.create(
    name=agent_engine.api_resource.name,  # Required
    user_id=USER_ID, # Required
    session_id=SESSION_ID,
)

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

Untuk SESSION_ID, pertimbangkan batasan berikut untuk mencegah konflik 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 depannya.

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 bentrokan 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 depannya.
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

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

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

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

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.

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 menyetel waktu habis masa berlaku (expire_time) secara langsung atau menyetel waktu aktif (ttl) dalam detik. Jika tidak ada yang ditentukan, sistem akan menerapkan TTL default 365 hari.

Time to live (TTL)

Jika Anda menetapkan time to live (TTL), 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.agent_engines.sessions.create(
    name=agent_engine.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.agent_engines.sessions.create(
    name=agent_engine.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.

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 Anda tentukan.
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.agent_engines.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.

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 Anda tentukan.
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.agent_engines.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 Platform Agen 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.

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 Anda tentukan.
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 Peristiwa untuk melihat peristiwa yang terkait dengan sesi.

Python

for session_event in client.agent_engines.list_session_events(
    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 Platform Agen.

Konsol

Untuk agen yang di-deploy, Anda dapat menggunakan konsol Google Cloud untuk membuat sesi:

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 Anda tentukan.
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 Peristiwa untuk melihat peristiwa yang terkait dengan sesi.
Ketik pesan dan tekan Enter untuk menambahkan peristiwa baru ke sesi.

Python

import datetime

client.agent_engines.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 lainnya atau untuk menyimpan data peristiwa kustom.

client.agent_engines.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 bentrokan 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 depannya.
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

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

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

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

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.

Pembersihan

Untuk membersihkan semua resource yang digunakan dalam project ini, Anda dapat menghapus instance Agent Platform beserta resource turunannya:

agent_engine.delete(force=True)

Mengelola sesi menggunakan panggilan API atau konsol Google Cloud Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Membuat instance Agent Runtime

Mencantumkan sesi

Konsol

Python

REST

curl

PowerShell

Membuat sesi

Konsol

Python

REST

curl

PowerShell

Mengonfigurasi time to live (TTL) sesi

Time to live (TTL)

Waktu habis masa berlaku

Mendapatkan sesi

Konsol

Python

REST

curl

PowerShell

Menghapus sesi

Konsol

Python

REST

curl

PowerShell

Mencantumkan peristiwa dalam sesi

Konsol

Python

REST

curl

PowerShell

Menambahkan peristiwa ke sesi

Konsol

Python

REST

curl

PowerShell

Pembersihan

Mengelola sesi menggunakan panggilan API atau konsol Google Cloud