Memecahkan masalah penggunaan agen dengan Agent Runtime

Dokumen ini menjelaskan cara mengatasi error yang mungkin Anda alami saat menggunakan agen.

Catatan: Untuk menelusuri dan memfilter log error agen, gunakan Logs Explorer, pilih RESOURCE TYPE ke "Vertex AI Mesin Penalaran", lalu pilih nilai RESOURCE CONTAINER (yaitu nomor project) dan nilai REASONING ENGINE ID yang sesuai.

Skema operasi kosong

Jika agen Anda menampilkan daftar kosong dari .operation_schemas(), hal ini mungkin disebabkan oleh salah satu masalah berikut:

Gagal membuat skema selama pembuatan agen

Masalah:

Saat men-deploy agen, Anda akan menerima peringatan seperti berikut:

WARNING:vertexai.agent_engines:failed to generate schema: issubclass() arg 1 must be a class

Kemungkinan penyebab:

Peringatan ini mungkin muncul jika Anda men-deploy agen menggunakan template LangchainAgent bawaan pada versi google-cloud-aiplatform yang lebih lama dari 1.49.0. Untuk memeriksa versi yang Anda gunakan, 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

Setelah mengupdate paket google-cloud-aiplatform, jalankan perintah berikut untuk memverifikasi bahwa versinya adalah 1.49.0 atau yang lebih baru:

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. Setelah memverifikasi bahwa versi google-cloud-aiplatform Anda adalah 1.49.0 atau yang lebih baru, coba deploy agen Anda lagi.

Error PermissionDenied saat mengkueri agen Anda

Kueri Anda mungkin gagal jika Anda tidak memiliki izin yang diperlukan.

Izin ekstensi Agent Platform

Masalah

Anda mungkin menerima error PermissionDenied yang mirip dengan berikut ini:

Permission 'aiplatform.extensions.get' denied on resource
'//aiplatform.googleapis.com/projects/{PROJECT_ID}/locations/{LOCATION}/extensions/
{EXTENSION}' (or it may not exist). [reason: "IAM_PERMISSION_DENIED"
domain: "aiplatform.googleapis.com"
metadata {
  key: "permission"
  value: "aiplatform.extensions.get"
}
metadata {
  key: "resource"
  value: "projects/{PROJECT_ID}/locations/{LOCATION}/extensions/{EXTENSION}"
}
]

Agen Anda tidak memiliki izin ekstensi Agent Platform. Untuk menggunakan ekstensi Agent Platform dengan Agent Runtime, berikan peran Agent Platform User (roles/aiplatform.user) ke akun layanan identitas agen Anda. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan identitas dan izin untuk agen Anda.

Izin LLM

Masalah:

Anda mungkin menerima error PermissionDenied yang mirip dengan berikut ini:

PermissionDenied: 403 Permission 'aiplatform.endpoints.predict' denied on resource
'//aiplatform.googleapis.com/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/
google/models/{MODEL}' (or it may not exist). [reason: "IAM_PERMISSION_DENIED"
domain: "aiplatform.googleapis.com"
metadata {
  key: "permission"
  value: "aiplatform.endpoints.predict"
}
metadata {
  key: "resource"
  value: "projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL}"
}
]

Kemungkinan penyebab:

Akun layanan identitas agen Anda mungkin tidak memiliki izin yang tepat untuk mengkueri model bahasa besar (LLM) Anda.

Solusi yang direkomendasikan:

Pastikan akun layanan Anda memiliki izin Identity and Access Management (IAM) yang tepat yang tercantum dalam pesan error. Contoh izin IAM yang mungkin tidak Anda miliki adalah aiplatform.endpoints.predict. Lihat Menyiapkan identitas dan izin untuk agen Anda untuk mengetahui informasi selengkapnya.

Permintaan ditolak sebelum mencapai agen Anda

Jika permintaan Anda gagal sebelum Agent Runtime mengirimkannya ke agen, salah satu masalah berikut mungkin menjadi penyebabnya:

Agen tidak ditemukan

Masalah:

Permintaan gagal dengan status 404, NOT_FOUND (REASONING_ENGINE_NOT_FOUND) dan pesan yang mirip dengan berikut ini:

The Reasoning Engine `projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID` was not found.

Kemungkinan penyebab:

  • Project, lokasi, atau ID resource dalam permintaan salah.
  • Agen telah dihapus.

Solusi yang direkomendasikan:

  • Bandingkan nama resource dalam pesan error dengan agen yang Anda deploy. Lihat Daftar agen yang di-deploy.
  • Pastikan klien Anda mengirim permintaan ke project dan region tempat Anda men-deploy agen.

Agen tidak aktif

Masalah:

Permintaan gagal dengan status 403, PERMISSION_DENIED (REASONING_ENGINE_NOT_ACTIVE) dan pesan yang mirip dengan berikut ini:

The Reasoning Engine `projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID` is not active, so it can't serve requests.

Kemungkinan penyebab:

  • Agen masih dibuat.
  • Agen gagal dibuat.
  • Agen sedang dihapus.

Solusi yang direkomendasikan:

  • Jika Anda baru saja membuat agen, tunggu hingga pembuatan selesai, lalu coba lagi permintaan tersebut.
  • Jika pembuatan agen gagal, periksa log yang ditautkan di kolom logs_url metadata error untuk menemukan penyebabnya. Perbaiki error dan deploy agen lagi. Lihat Memecahkan masalah deployment agen.

Agen tidak memiliki instance yang berjalan

Masalah:

Permintaan gagal dengan status 400, FAILED_PRECONDITION (REASONING_ENGINE_NO_RUNNING_INSTANCES) dan pesan yang mirip dengan berikut:

The Reasoning Engine `projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID` has no running instances because no agent is deployed to it.

Kemungkinan penyebab:

Resource ada, tetapi tidak ada agen (objek, file sumber, atau image container) yang ditentukan untuk deployment selama pembuatan atau update.

Solusi yang direkomendasikan:

Perbarui resource dengan agen yang akan di-deploy. Lihat Mengupdate agen yang di-deploy.

Metode A2A tidak ditentukan

Masalah:

Permintaan A2A gagal dengan status 400, FAILED_PRECONDITION (REASONING_ENGINE_A2A_NOT_CONFIGURED) dan pesan yang mirip dengan berikut ini:

The Reasoning Engine `projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID` does not define A2A methods, so it can't serve A2A requests.

Kemungkinan penyebab:

Anda mengirim permintaan A2A, seperti permintaan untuk Kartu Agen atau pesan, ke agen yang tidak dibuat sebagai agen A2A.

Solusi yang direkomendasikan:

Payload permintaan terlalu besar

Masalah:

Permintaan gagal dengan status 400, FAILED_PRECONDITION (REASONING_ENGINE_REQUEST_TOO_LARGE) atau error HTTP 413 Request Entity Too Large, dan pesan yang mirip dengan berikut ini:

The request to the Reasoning Engine `projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID` exceeds the 32 MiB maximum HTTP payload size (about 24 MiB for Base64-encoded files).

Kemungkinan penyebab:

  • Agent Runtime menerapkan ukuran isi permintaan HTTP maksimum tetap sebesar 32 MiB.
  • Lampiran file inline yang dienkode Base64 dalam JSON akan bertambah sekitar 33%, sehingga file yang lebih besar dari sekitar 24 MiB akan melebihi batas payload 32 MiB.
  • Dalam percakapan multi-turn, akumulasi histori percakapan dan lampiran sebelumnya yang dikirim dalam payload permintaan akan mendorong total isi permintaan melebihi 32 MiB.

Solusi yang direkomendasikan:

  • Upload file besar ke Cloud Storage dan teruskan URI gs:// dalam permintaan Anda, bukan byte berenkode Base64 inline.
  • Kompresi, pisahkan, atau perkecil lampiran berukuran besar sebelum mengirimkannya agar total isi permintaan HTTP yang diserialisasi tetap di bawah 32 MiB (sekitar 24 MiB file mentah).
  • Mulai percakapan baru atau pangkas lampiran sebelumnya dari histori percakapan saat konteks multi-turn mendekati batas.

Eksekusi Mesin Penalaran gagal

Jika Anda menerima pesan error "Reasoning Engine Execution failed" saat mengkueri agen, hal ini mungkin disebabkan oleh salah satu masalah yang dijelaskan di bagian ini.

Input tidak valid untuk .query()

Masalah:

Anda mungkin menerima error FailedPrecondition yang mirip dengan berikut ini:

FailedPrecondition: 400 Reasoning Engine Execution failed. Error Details:
{"detail":"Invalid request: `{'query': ...}`"}

Kemungkinan penyebab:

Error ini terjadi saat Anda menentukan input ke kueri sebagai argumen posisional, bukan argumen kata kunci. Misalnya, Anda memanggil agent.query(query_str), bukan agent.query(input=query_str).

Solusi yang direkomendasikan:

Saat mengkueri instance mesin penalaran yang telah di-deploy, tentukan semua input sebagai argumen kata kunci.

Kuota model Gemini habis

Masalah:

Anda mungkin menerima error yang mirip dengan salah satu error berikut, yang menunjukkan bahwa error tersebut muncul dari panggilan ke Gemini:

FailedPrecondition: 400 Reasoning Engine Execution failed. Error Details:
{"detail":"...langchain_google_vertexai/chat_models.py...google.api_core.exceptions.ResourceExhausted: 429 Unable to submit request because the service is temporarily out of capacity. Try again later."}

atau, pesan error yang berbeda:

FailedPrecondition: 400 Reasoning Engine Execution failed. Error Details:
{"detail":"...langchain_google_vertexai/chat_models.py...google.api_core.exceptions.InternalServerError: 500 Internal error occurred."}

Kemungkinan penyebab:

Hal ini mungkin terjadi jika Anda telah mengirim terlalu banyak permintaan baru-baru ini dan telah menghabiskan kuota model Gemini.

Solusi yang direkomendasikan:

Ikuti proses pengelolaan kuota model Gemini untuk meningkatkan kuota. Atau, batasi kapasitas pengujian Anda dan coba lagi nanti.

ID Mesin Penalaran Salah

Masalah:

Anda mungkin menerima error bahwa Reasoning Engine Execution gagal dengan detail Not Found.

Kemungkinan penyebab:

Error ini dapat terjadi jika Anda menggunakan ID mesin penalaran yang salah saat membuat kueri agen.

Solusi yang direkomendasikan:

Pastikan Anda menggunakan ID mesin penalaran yang benar untuk agen Anda.

Referensi dukungan

Jika masalah Anda masih belum terselesaikan, lihat panduan dukungan kami untuk mendapatkan bantuan.