Variabel

Variabel digunakan untuk menyimpan dan mengambil data di seluruh giliran percakapan. Alat ini memungkinkan agen mengingat informasi dan mempertahankan konteks. Saat menulis petunjuk perintah untuk agen Anda, Anda dapat menyertakan referensi ke variabel ini.

Jenis variabel

Pembuat agen mendukung dua jenis variabel yang berbeda dalam petunjuk: variabel statis dan variabel dinamis.

Memilih jenis yang tepat bergantung pada apakah nilai variabel perlu berubah selama sesi pengguna, dan seberapa besar Anda perlu mengoptimalkan latensi.

Variabel statis

Variabel statis dikompilasi langsung ke perintah agen sebelum panggilan model terjadi. Entitas ini berfungsi sebagai penggantian teks 1:1 langsung dan jarang diperbarui.

Variabel statis memaksimalkan kualitas mengikuti petunjuk dan cocok untuk petunjuk bersyarat dalam banyak skenario. Gunakan variabel statis untuk data konfigurasi, aturan bisnis yang ketat, atau payload kontekstual besar yang tidak berubah selama masa aktif satu percakapan.

Untuk mereferensikan variabel statis menurut nama dalam petunjuk Anda, gunakan tanda kurung kurawal ganda: {{variable_name}}.

Misalnya, jika Anda membuat agen retail dengan katalog produk statis yang besar, Anda dapat menggunakan perintah seperti:

You are a helpful shopping assistant.
Please follow these business rules: {{business_rules}}.

Variabel dinamis

Variabel dinamis dapat diupdate kapan saja selama percakapan oleh alat, callback, atau permintaan API. Kata-kata tersebut tidak langsung diganti dalam teks perintah Anda. Sebaliknya, saat diperbarui, nilai barunya ditambahkan sebagai peristiwa state update ke histori percakapan. Misalnya: <state_update>var_name: value</state_update>

Gunakan variabel dinamis untuk informasi yang diekstrak dari pengguna selama sesi, output yang diambil dari API (alat) eksternal, atau status apa pun yang berubah saat percakapan berlangsung.

Kekurangan berikut berlaku untuk variabel dinamis:

  • Variabel dinamis ditambahkan ke histori percakapan, jadi jika sesi yang panjang melampaui batas jendela konteks, agen dapat melupakan nilai variabel yang hilang saat memangkas histori.
  • Variabel dinamis dapat menyebabkan kepatuhan terhadap petunjuk yang sedikit lebih rendah dibandingkan dengan variabel statis. Hal ini disebabkan oleh nilai variabel yang ditentukan lebih jauh dari petunjuk. Hal ini juga dapat menambah latensi, karena pemikiran model perlu menemukan nilai yang lebih jauh dari petunjuk.

Untuk mereferensikan variabel dinamis menurut nama dalam petunjuk Anda, gunakan kurung kurawal tunggal: {variable_name}.

Misalnya, jika Anda membuat agen yang perlu mengautentikasi pengguna lalu mencari detail akun spesifik mereka menggunakan alat, Anda dapat menggunakan petunjuk seperti:

If the user asks for their balance, call the {@TOOL: LookupBalance}.
The tool will update the {current_account_balance} variable.
Always share the {current_account_balance} with the user.

Data variabel

Variabel memiliki data berikut:

  • Nama: Nama variabel menggunakan snake case
  • Jenis: Jenis data pokok:
    • Teks: Nilai string
    • Angka: Nilai numerik
    • Ya/Tidak: Nilai boolean
    • Objek Kustom: Anda memberikan skema untuk objek
    • Daftar: Daftar variabel. Berikan nilai sebagai daftar yang dipisahkan koma.
  • Nilai default: Nilai default untuk variabel
  • Deskripsi: Deskripsi opsional variabel

Memperbarui nilai variabel

Agen itu sendiri tidak dapat memperbarui nilai variabel, tetapi alat dan callback dapat memperbarui nilai variabel.

Variabel agen menggunakan status konteks ADK, yang dapat digunakan untuk mengupdate variabel. Variabel global bernama context tersedia untuk digunakan dalam kode alat Python Anda. Misalnya, Anda dapat menggunakan pernyataan berikut di alat Python untuk memperbarui variabel menggunakan fitur ADK:

context.state["variable_name"] = value

Variabel konteks sesi bawaan

Selain variabel kustom, alat OpenAPI dan MCP dapat mereferensikan variabel konteks sesi bawaan. Nilai ini tersedia secara default dan dapat diteruskan dalam header HTTP atau parameter permintaan. Variabel ini tidak dapat dirujuk dalam petunjuk, dan tidak dapat ditimpa secara manual. Variabel bawaan berikut tersedia:

  • $context.project_id, $context.project_number, $context.location, $context.app_id, $context.session_id, $context.turn_index untuk ID resource tingkat aplikasi/tingkat sesi.
  • $context.variables.variable_name untuk nilai variabel agen tertentu.
  • $context.variables untuk semua nilai variabel agen sebagai objek.