Memecahkan masalah penyiapan lingkungan untuk Runtime Agen

Dokumen ini menjelaskan cara mengatasi error yang mungkin Anda temui saat menyiapkan lingkungan untuk Runtime Agen. Dokumen ini mencakup langkah-langkah pemecahan masalah untuk masalah impor paket.

Error saat mengimpor Agent Platform SDK

Jika Anda tidak dapat mengimpor Agent Platform SDK untuk Python, hal ini mungkin disebabkan oleh salah satu masalah berikut:

Versi Agent Platform SDK untuk Python yang sudah tidak berlaku

Masalah:

Anda menerima pesan error yang mirip dengan berikut ini:

ImportError: cannot import name 'reasoning_engines' from 'vertexai.preview'

atau

ImportError: cannot import name 'agent_angines' from 'vertexai'

Kemungkinan penyebab:

Hal ini mungkin terjadi jika versi paket google-cloud-aiplatform Anda lebih lama dari 1.82.0 (untuk agent_engines) atau 1.47.0 (untuk reasoning_engines). Untuk memeriksa versi paket google-cloud-aiplatform, jalankan perintah berikut di terminal:

pip show google-cloud-aiplatform

Solusi yang direkomendasikan:

Jalankan perintah berikut di terminal untuk mengupdate paket google-cloud-aiplatform:

pip install google-cloud-aiplatform --upgrade

Verifikasi bahwa versi yang diupdate adalah 1.82.0 atau yang lebih baru dengan menjalankan perintah berikut:

pip show google-cloud-aiplatform

Jika Anda berada di instance notebook (Misalnya, Jupyter atau Colab atau Workbench), Anda mungkin perlu memulai ulang runtime untuk menggunakan paket yang diupdate.

Error Otorisasi 401

Masalah:

Anda menerima pesan error yang mirip dengan berikut ini:

Error Code: "401"
Error Details: "Context-Aware Access requirements are not met"

ATAU

Agent Engine Error: An error occurred during invocation. Exception: API request failed with status 401:
Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.

Kemungkinan penyebab:

Secara default, saat Anda menggunakan Identitas Agen dengan Runtime Agen, token akses terikat sertifikat digunakan untuk autentikasi guna mencegah pencurian token. Error 401 dapat terjadi saat runtime dalam salah satu dari dua skenario berikut:

  1. Pengguna atau Agen mencoba menggunakan token akses di luar konteks saat token tersebut dikeluarkan, seperti meneruskan token antar-agen.
  2. Agen memanggil endpoint API yang tidak kompatibel dengan mTLS, seperti telemetry.googleapis.com, bukan telemetry.mtls.googleapis.com.

Solusi yang direkomendasikan:

Untuk skenario #1, jika Anda memiliki alasan yang sah untuk membagikan token antar-agen, Anda dapat memilih untuk tidak menggunakan kebijakan Akses Kontekstual (CAA) default. Tindakan ini sangat tidak disarankan, karena membuat agen rentan terhadap pencurian kredensial.

Pilih untuk tidak menggunakan kebijakan CAA default dengan menetapkan variabel lingkungan berikut saat Anda membuat instance Runtime Agen:

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

Untuk skenario #2, Anda dapat menetapkan variabel GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES ke False untuk mengizinkan agen menggunakan endpoint API non-mTLS sebagai solusi sementara. Dalam hal ini, masalah yang mendasarinya dapat berupa masalah umum dengan ADK.