Referensi runtime Python

Anda dapat menggunakan kode Python di alat Python dan di callback. Referensi ini menjelaskan runtime Python, opsi dan class impor, variabel global, dan fungsi yang dapat Anda gunakan dalam kode Anda.

Lingkungan Python

Alat dan callback Python berjalan di lingkungan sandbox yang aman. Lingkungan ini menjalankan Python 3.12.

Impor

Kemampuan Anda untuk mengimpor modul terbatas pada hal berikut:

Class

AsyncTools

Alias class untuk memanggil alat secara asinkron. Lihat variabel global async_tools untuk mengetahui informasi selengkapnya.

Blob

Data byte inline.

Atribut:

Atribut Deskripsi
display_name: Optional[str] Nama tampilan Blob. Digunakan untuk memberikan label atau nama file untuk membedakan blob.
data: Optional[bytes] Byte berenkode base64.
raw_data: Optional[bytes] Byte yang didekodekan mentah.
mime_type: Optional[str] Jenis MIME standar IANA dari data sumber.

Metode:

Metode Deskripsi
transcript() -> Optional[str] Menampilkan transkrip yang di-cache untuk data Blob jika tersedia. Hal ini hanya berlaku untuk blob audio.
from_json(data: str) -> Blob Metode class untuk membuat instance Blob dari string JSON, dengan mime_type ditetapkan ke 'application/json'.

Contoh:

# Create a blob from raw bytes
blob = Blob(mime_type='text/plain')
blob.raw_data = b'hello world'

# Create a blob from a JSON string
Blob.from_json(data='{"key": "value"}')

CallbackContext

Informasi sesi yang tersedia selama callback.

Atribut:

Atribut Deskripsi
user_content: Optional[Content] Input terbaru dari pengguna.
invocation_id: str ID unik untuk pemanggilan callback tertentu, berguna untuk proses debug.
agent_name: str Nama tampilan agen yang terkait dengan panggilan balik saat ini.
session_id: str ID sesi unik dari sesi saat ini yang sedang berlangsung.
variables: dict[str, Any] Kamus yang berisi key-value pair variabel yang ditentukan saat waktu desain atau disuntikkan selama runtime. Ini adalah status variabel saat ini pada saat eksekusi callback.
state: dict[str, Any] Sama seperti properti variables.
events: list[Event] Peristiwa sesi.

Metode:

Metode Deskripsi
get_variable(key: str, default: Any) -> Any Mendapatkan variabel dari status. Jika variabel tidak ada, tampilkan default.
set_variable(key: str, value: Any) -> None Menetapkan variabel dalam status.
remove_variable(key: str) -> None Menghapus variabel dari status.
get_last_user_input() -> list[Part] Mendapatkan daftar semua bagian dalam potongan terakhir peristiwa pengguna.
get_last_agent_output() -> list[Part] Mendapatkan daftar semua bagian dalam bagian terakhir peristiwa agen.
parts() -> list[Part] Daftar semua bagian yang direkam dalam histori sesi.

Content

Isi pesan dari pengguna atau agen.

Atribut:

Atribut Deskripsi
parts: Optional[list[Part]] Daftar bagian yang membentuk satu pesan. Setiap bagian dapat memiliki jenis MIME IANA yang berbeda.
role: Optional[str] Peran penulis konten. 'user' atau 'agent'.

Metode:

Metode Deskripsi
is_user() -> bool Menampilkan True jika perannya adalah 'user'.
is_model() -> bool Menampilkan True jika perannya adalah 'model'.

Event

Representasi peristiwa dalam sesi.

Atribut:

Atribut Deskripsi
id: str ID acara.
invocation_id: str ID pemanggilan peristiwa.
author: str 'user' atau nama agen, yang menunjukkan siapa yang menghadiri acara ke sesi.
timestamp: int Stempel waktu peristiwa.
content: Content Konten yang terkait dengan acara ini.
actions: EventActions Tindakan yang dilakukan oleh agen.
long_running_tool_ids: set[str] Kumpulan ID panggilan fungsi yang berjalan lama.
partial: bool True untuk potongan yang tidak lengkap dari respons streaming LLM.
turn_complete: bool True jika giliran saat ini selesai.
error_code: str Kode error.
error_message: str Pesan kesalahan.
interrupted: bool True jika giliran terganggu.
branch: str Cabang peristiwa.

Formatnya seperti agent_1.agent_2.agent_3, dengan agent_1 adalah induk dari agent_2, dan agent_2 adalah induk dari agent_3.

Cabang digunakan saat beberapa sub-agen tidak boleh melihat histori percakapan agen rekan mereka.
grounding_metadata: Any Metadata perujukan peristiwa.

Metode:

Metode Deskripsi
is_user() -> bool True jika penulis acara adalah 'pengguna'.
is_agent(agent_name: Optional[str] = None) -> bool True jika penulis acara adalah agen. Jika agent_name diberikan, kode akan memeriksa apakah penulis cocok dengan agen tertentu tersebut.
has_error() -> bool True jika peristiwa memiliki kode error terkait.
parts() -> list[Part] Metode praktis untuk mendapatkan daftar objek Part dari content peristiwa. Menampilkan daftar kosong jika tidak ada konten atau bagian.

EventActions

Tindakan yang terjadi untuk peristiwa.

Atribut:

Atribut Deskripsi
skip_summarization: bool Jika True, model tidak dipanggil untuk meringkas respons fungsi. Hanya digunakan untuk peristiwa function_response.
state_delta: dict[str,Any] Perubahan pada variabel yang disebabkan oleh peristiwa ini.
artifact_delta: dict[str,Any] Perubahan pada artefak oleh peristiwa ini. Kuncinya adalah nama file, nilainya adalah versi.
transfer_to_agent: str Jika ditetapkan, peristiwa akan ditransfer ke agen yang ditentukan.
escalate: bool Agen mengeskalasikan ke agen tingkat yang lebih tinggi.
requested_auth_configs: dict[str,dict[str,Any]] Konfigurasi autentikasi yang diminta oleh respons alat.

Kolom ini hanya ditetapkan oleh peristiwa respons alat yang menunjukkan kredensial autentikasi permintaan alat.

Kunci: ID panggilan fungsi. Karena satu peristiwa respons fungsi dapat berisi beberapa respons fungsi yang sesuai dengan beberapa panggilan fungsi. Setiap panggilan fungsi dapat meminta konfigurasi autentikasi yang berbeda. ID ini digunakan untuk mengidentifikasi panggilan fungsi.

Nilai: Konfigurasi autentikasi yang diminta.
end_invocation: bool Loop agen terganggu.

ExternalResponse

Mewakili respons dari luar lingkungan Python, seperti panggilan alat atau permintaan HTTP.

Atribut:

Atribut Deskripsi
text: str Isi respons sebagai string.
status_code: int Kode status HTTP.
reason: str Alasan error ditampilkan. Kosong jika tidak ada error.
ok: bool True jika status_code kurang dari 400, atau False jika sebaliknya.

Metode:

Metode Deskripsi
json() -> Any Mengurai JSON atribut teks dan menampilkan hasilnya. Jika penguraian gagal, error akan muncul.
raise_for_status() Memunculkan StatusError jika respons tidak baik (ok == False).

FunctionCall

Mewakili panggilan fungsi.

Atribut:

Atribut Deskripsi
id: Optional[str] ID unik panggilan fungsi.
args: Optional[dict[str,Any]] Parameter dan nilai fungsi dalam format objek JSON.
name: Optional[str] Nama fungsi.

FunctionDeclaration

FunctionCall yang diprediksi ditampilkan dari model yang berisi string yang merepresentasikan atribut FunctionDeclaration name dengan parameter dan nilainya.

Atribut:

Atribut Deskripsi
name: Optional[str] Nama fungsi.

FunctionResponse

Hasil FunctionCall yang berisi string yang merepresentasikan atribut FunctionDeclaration name dan objek JSON terstruktur yang berisi output apa pun dari panggilan fungsi. Bagian ini digunakan sebagai konteks untuk model.

Atribut:

Atribut Deskripsi
id: Optional[str] ID panggilan fungsi yang sesuai.
name: Optional[str] Nama fungsi.
response: Optional[dict[str,Any]] Respons fungsi dalam format objek JSON. Gunakan kunci "output" untuk menentukan output fungsi dan kunci "error" untuk menentukan detail error (jika ada). Jika kunci "output" dan "error" tidak ditentukan, seluruh "respons" akan dianggap sebagai output fungsi.

GenerateContentConfig

Parameter konfigurasi model opsional.

Atribut:

Atribut Deskripsi
system_instruction: Optional[Content] Petunjuk untuk model agar mengarahkannya ke performa yang lebih baik. Misalnya, "Jawab sesingkat mungkin" atau "Jangan gunakan istilah teknis dalam respons Anda".
tools: Optional[list[ToolDeclaration]] Daftar alat yang tersedia yang dapat dijalankan model.
excluded_tools: Optional[list[str]] Daftar nama alat yang akan diabaikan oleh model. Kolom ini menggantikan tools.

Metode:

Metode Deskripsi
hide_tool(tool_name: str) Menambahkan tool_name ke daftar excluded_tools.

HttpMethod

Enum string untuk merepresentasikan metode HTTP. Kemungkinan nilainya adalah:

  • GET
  • POST
  • PUT
  • DELETE
  • PATCH
  • HEAD
  • OPTIONS

LlmRequest

Model data untuk merepresentasikan permintaan ke LLM.

Atribut:

Atribut Deskripsi
model: Optional[str] Nama model
contents: List[Content] Daftar konten yang dikirim ke model.
config: Optional[GeneralContentConfig] Parameter konfigurasi model.

LlmResponse

Model data untuk merepresentasikan respons dari LLM.

Atribut:

Atribut Deskripsi
content: Content Content pertama yang direspons model.
partial: Optional[bool] Menunjukkan apakah konten mewakili respons model yang tidak lengkap. Agen akan melanjutkan pemrosesan setelah mengirimkan respons parsial.

Metode:

Metode Deskripsi
from_parts(parts: list[Part]) -> LlmResponse Metode class yang menampilkan LlmResponse dari model.

Contoh:

response = LlmResponse.from_parts(
  parts=[
    Part.from_text(text="hello world")
  ]
)

Part

Jenis data yang berisi konten media. Tepat satu kolom dalam Part harus ditetapkan, yang merepresentasikan jenis konten tertentu yang disampaikan. Penggunaan beberapa kolom dalam instance Part yang sama dianggap tidak valid.

Atribut:

Atribut Deskripsi
function_call: Optional[FunctionCall] FunctionCall yang diprediksi dan ditampilkan dari model yang berisi string yang merepresentasikan nama fungsi dan objek JSON terstruktur yang berisi parameter dan nilainya.
function_response: Optional[FunctionResponse] Output hasil FunctionCall yang berisi string yang merepresentasikan nama fungsi dan objek JSON terstruktur yang berisi output apa pun dari panggilan fungsi. Bagian ini digunakan sebagai konteks untuk model.
text: Optional[str] Teks pesan.
inline_data: Optional[Blob] Data byte inline.

Metode:

Metode Deskripsi
text_or_transcript() -> Optional[str] Menampilkan teks jika tersedia, atau menampilkan transkrip data inline.
has_function_call(name) -> bool Menampilkan True jika bagian tersebut berisi panggilan fungsi tertentu.
has_function_response(name) -> bool Menampilkan True jika bagian tersebut menyimpan respons fungsi tertentu.
from_text(text: str) -> Part Metode class yang membuat teks Part.
from_function_call(name: str, args: dict[str, Any]) -> Part Metode class yang membuat panggilan fungsi Part.
from_function_response(name: str, response: dict[str, Any]) -> Part Metode class yang membuat respons fungsi Part.
from_inline_data(data: bytes, mime_type: str) -> Part Metode class yang membuat data inline Part.
from_json(data: str) -> Part Metode class yang membuat data inline JSON Part.
from_agent_transfer(agent: str) -> Part Metode class yang membuat Part untuk ditransfer ke agen lain.
from_end_session(*, reason: str, escalated: bool = False) -> Part Metode class yang membuat Part untuk menghentikan sesi.
from_customized_response(*, content: str, disable_barge_in: bool = False, enable_dtmf: bool = False, dtmf_finish_digit = str: '#', dtmf_endpointing_timeout: int = 3) -> Part Metode class yang membuat Part untuk respons dengan perilaku yang disesuaikan (misalnya, menonaktifkan barege-in, mengaktifkan input DTMF, dll.).

Contoh:

text_part = ces_public.Part.from_text(text="Hello from the user!")

tool_part = ces_public.Part.from_function_call(
  name="get_weather",
  args={"location": "Mountain View"}
)

Requests

Alias class untuk membuat permintaan HTTP. Lihat variabel global ces_requests untuk mengetahui informasi selengkapnya.

Metode:

  • get(url, params=None, **kwargs)
  • post(url, data=None, json=None, **kwargs)
  • put(url, data=None, json=None, **kwargs)
  • delete(url, **kwargs)
  • patch(url, data=None, json=None, **kwargs)
  • head(url, **kwargs)
  • options(url, **kwargs)

StatusError

Digunakan untuk error yang muncul dengan kode status.

Atribut:

Atribut Deskripsi
status_code: int Kode status HTTP yang terkait dengan error ini.
reason: str Alasan error ditampilkan.

Tool

Menampilkan alat dengan nama dan deskripsi.

Atribut:

Atribut Deskripsi
name: str Nama alat.
description: str Deskripsi tentang fungsi alat.

ToolContext

Diperoleh dari CallbackContext. Informasi sesi yang tersedia saat menjalankan alat.

Atribut:

Atribut Deskripsi
function_call_id: str ID panggilan fungsi dari panggilan alat saat ini yang sedang dieksekusi.

Tools

Class alias untuk memanggil alat secara sinkron. Lihat variabel global alat untuk mengetahui informasi selengkapnya.

ToolDeclaration

Skema alat yang dapat ditampilkan ke model.

Atribut:

Atribut Deskripsi
function_declarations: Optional[list[FunctionDeclaration]] Daftar deklarasi fungsi yang didukung alat.

Fungsi

get_variable

Fungsi ini mengambil nilai dari status sesi menggunakan kunci yang diberikan. Tindakan ini berfungsi sebagai pintasan untuk context.state.get(key) atau context.variables.get(key).

Contoh kode:

def get_a_value() -> int:
  # Retrieve the value of 'my_key' from the state
  my_value = get_variable('my_key')
  return my_value + 5

remove_variable

Fungsi ini menghapus pasangan nilai kunci dari status sesi. Ini adalah pintasan untuk del context.state[key].

Contoh kode:

def remove_a_value() -> None:
  # Delete 'my_key' from the state
  remove_variable('my_key')

set_variable

Fungsi ini menetapkan nilai untuk kunci tertentu dalam status sesi. Jika kunci sudah ada, nilainya akan diperbarui. Ini adalah pintasan untuk context.state[key] = value.

Contoh kode:

def set_a_value() -> None:
  # Set the value of 'my_key' to 10
  set_variable('my_key', 10)

Variabel global

async_tools

Instance AsyncTools, yang memungkinkan Anda melakukan panggilan asinkron ke alat.

Contoh:

response_future = async_tools.<TOOL_DISPLAY_NAME>(<ARGS_AS_DICT>)
# ... misc work
response = response_future() # poll for response

# Check if the tool call was successful
try:
  response.raise_for_status()
except StatusError:
  print(f"Request failed with status {response.status_code}")

# Convert the response to json
data = response.json()

ces_requests

Instance Requests. Requests memungkinkan Anda melakukan panggilan HTTP dengan sintaksis yang serupa dengan modul permintaan Python yang populer.

Contoh:

# Make a GET request
response = ces_requests.get('https://api.example.com/data')

# Check if the request was successful
try:
  response.raise_for_status()
except StatusError:
  print(f"Request failed with status {response.status_code}")

# Convert the response to json
data = response.json()

tools

Instance Tools, yang memungkinkan Anda melakukan panggilan sinkron ke alat.

Contoh:

response = tools.<TOOL_DISPLAY_NAME>(<ARGS_AS_DICT>)

# Check if the tool call was successful
try:
  response.raise_for_status()
except StatusError:
  print(f"Request failed with status {response.status_code}")

# Convert the response to json
data = response.json()

context

Dalam kode, Anda dapat mengakses konteks ADK, yang dapat digunakan untuk membaca dan menulis banyak jenis data konteks ADK. Variabel global bernama context tersedia untuk digunakan dalam kode Anda.

Objek context.state dan context.variables dapat dipertukarkan. Objek state didukung untuk kompatibilitas dengan kode ADK, tetapi kode baru harus menggunakan objek variables.