Dokumen ini menjelaskan cara mengatasi error yang mungkin Anda alami saat men-deploy agen ke Agent Runtime. Topik ini membahas berbagai masalah umum, termasuk kegagalan serialisasi, error izin, dan pelanggaran batas VPC-SC.
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.
Error build dan startup container
Jika deployment Anda gagal saat Agent Runtime membangun atau memulai container agen, salah satu masalah berikut mungkin menjadi penyebabnya:
Build image container gagal
Masalah:
Deployment gagal dengan status 400, INVALID_ARGUMENT
(REASONING_ENGINE_BUILD_FAILED) dan pesan yang mirip dengan berikut ini:
The Reasoning Engine could not be deployed because its container image failed to build.
Kemungkinan penyebab:
Saat Anda men-deploy agen dari objek agen, dari file sumber, atau dari Dockerfile, Agent Runtime akan membangun image container untuk agen tersebut. Build akan gagal jika salah satu langkah berikut gagal:
- Menginstal persyaratan paket: Paket di
requirementsatau file persyaratan file sumber Anda tidak ada, menyematkan versi yang tidak ada, bertentangan dengan paket lain, atau tidak mendukung versi Python agen. - Menginstal wheel lokal: File wheel yang tercantum di
requirementsjuga tidak disertakan dalamextra_packages, sehingga tidak tersedia untuk diinstal. - Menjalankan skrip penginstalan: Skrip di direktori
installation_scriptskeluar dengan error. - Membangun Dockerfile Anda: Saat Anda men-deploy dari Dockerfile
(
image_spec), petunjuk di Dockerfile Anda gagal.
Solusi yang direkomendasikan:
- Periksa log build yang ditautkan di kolom
logs_urlmetadata error untuk menemukan langkah yang gagal. Entri log build menyertakan ID logreasoning_engine_build. Untuk membuat kueri log, lihat Membuat kueri. Untuk mereproduksi kegagalan secara lokal, instal persyaratan yang sama di lingkungan virtual baru yang menggunakan versi Python agen yang di-deploy, dan perbaiki error yang dilaporkan
pip:python -m venv agent-envagent-env/bin/pip install -r requirements.txtAgar build menginstal versi yang Anda uji secara lokal, sematkan versi paket Anda. Lihat Menentukan persyaratan paket.
Jika Anda menginstal wheel lokal, sertakan dalam
requirementsdanextra_packages. Lihat Menentukan paket tambahan.Jika Anda menggunakan skrip penginstalan, pastikan setiap skrip keluar dengan berhasil saat dijalankan dengan izin root di lingkungan yang bersih. Lihat Menentukan opsi build.
Jika Anda men-deploy dari Dockerfile, bangun image container secara lokal dari file sumber yang sama (misalnya, dengan
docker build) dan perbaiki petunjuk yang gagal.
Solusi yang tidak berlaku:
- Mencoba ulang deployment tanpa mengubah persyaratan, skrip penginstalan, atau Dockerfile akan gagal dengan cara yang sama, karena build menjalankan langkah yang sama.
Waktu tunggu build image container habis
Masalah:
Deployment gagal dengan status 504, DEADLINE_EXCEEDED
(REASONING_ENGINE_BUILD_TIMEOUT) dan pesan yang menyatakan bahwa image container
agen tidak selesai di-build tepat waktu.
Kemungkinan penyebab:
Saat Anda men-deploy dari file sumber, Agent Runtime akan membangun image container yang menginstal kode Anda dan dependensinya. Deployment akan gagal jika build masih berjalan saat waktu yang diizinkan habis. Build biasanya memerlukan waktu terlalu lama karena dependensi yang diinstal, misalnya:
- Daftar panjang paket di
requirements, termasuk paket yang tidak digunakan agen. - Paket tanpa wheel bawaan untuk lingkungan build, yang dikompilasi dari sumber selama build.
- Versi yang tidak disematkan atau disematkan secara longgar, yang memperlambat resolusi dependensi.
Solusi yang direkomendasikan:
- Periksa log build yang ditautkan di kolom
logs_urlmetadata error untuk melihat langkah mana yang sedang berjalan saat build berhenti. - Hapus dependensi yang tidak diperlukan dan sematkan versi semua paket yang diperlukan.
- Prioritaskan paket dan versi yang memublikasikan wheel bawaan, sehingga tidak ada yang dikompilasi selama build.
- Coba lagi deployment. Build terkadang dapat berjalan lebih lama dari biasanya karena alasan yang tidak terkait dengan kode Anda.
Container gagal memulai
Masalah:
Deployment gagal dengan status 400, INVALID_ARGUMENT
(REASONING_ENGINE_CONTAINER_FAILED_TO_START) dan pesan yang menyatakan bahwa
container agen tidak mulai menyajikan dalam waktu tunggu startup.
Kemungkinan penyebab:
Agent Runtime memulai agen Anda dalam container dan menunggu agen tersebut menerima permintaan. Deployment akan gagal jika container keluar, atau tidak merespons, sebelum waktu tunggu startup habis. Penyebab umumnya dapat mencakup hal berikut:
- Dependensi tidak ada: Agen Anda mengimpor paket yang tidak tercantum dalam
requirementsatauextra_packages, sehingga pemuatan agen gagal dengan error sepertiModuleNotFoundError. - Ketidakcocokan versi paket: Paket yang diinstal di lingkungan yang di-deploy berbeda dengan paket di lingkungan pengembangan Anda, sehingga pemuatan agen gagal dengan error seperti
AttributeError: Can't get attribute. Lihat Error serialisasi. - Error selama inisialisasi: Metode
set_up()agen Anda, atau kode lain yang berjalan saat agen dimuat, memunculkan pengecualian atau menunggu resource yang tidak dapat dijangkau. - Inisialisasi lambat: Pemuatan agen memerlukan waktu lebih lama daripada waktu tunggu startup.
- Container kustom tidak memproses: Container kustom harus memproses permintaan HTTP di
0.0.0.0pada port8080. Lihat kontrak runtime. - Agent Gateway memblokir startup: Saat Anda merutekan traffic melalui Agent Gateway, startup akan gagal jika Identity-Aware Proxy (IAP) memblokir panggilan inisialisasi, jika identitas agen tidak memiliki peran yang diperlukan, atau jika container kustom tidak memercayai root certificate gateway. Lihat Error selama startup Agent Runtime dan Agen yang di-deploy dengan container kustom (BYOC) gagal terhubung ke Agent Gateway.
Solusi yang direkomendasikan:
- Periksa log agen yang ditautkan di kolom
logs_urlmetadata error untuk menemukan error yang menghentikan container. Lihat Melihat log untuk agen. - Tambahkan paket yang tidak ada ke
requirementsatauextra_packages, dan sematkan versi yang Anda gunakan dalam pengembangan. - Untuk mereproduksi kegagalan secara lokal, instal hanya paket yang tercantum dalam
requirementsdi lingkungan yang bersih dengan versi Python yang sama, lalu impor dan buat instance agen Anda. - Pindahkan pekerjaan yang lambat atau rentan gagal, seperti menghubungkan ke layanan eksternal, dari inisialisasi agen.
- Untuk container kustom, pastikan server memproses
0.0.0.0dan port dalam variabel lingkunganPORT(default8080).
Solusi yang tidak berlaku:
- Mencoba ulang deployment tanpa mengubah agen atau dependensinya biasanya akan gagal dengan cara yang sama, karena penyebabnya ada dalam kode agen atau lingkungannya.
Container tidak dimulai tepat waktu
Masalah:
Deployment gagal dengan status 504, DEADLINE_EXCEEDED
(REASONING_ENGINE_CONTAINER_START_TIMEOUT) dan pesan yang menyatakan bahwa
container agen tidak mulai menyajikan tepat waktu.
Kemungkinan penyebab:
Setelah image dibuat, Agent Runtime akan memulai container agen dan menunggu hingga container siap menyalurkan permintaan. Deployment akan gagal jika container masih dimulai saat waktu yang diizinkan habis. Penyebab umumnya dapat mencakup hal berikut:
- Pekerjaan yang lambat pada waktu impor, seperti memuat model atau file besar saat modul agen diimpor.
- Pekerjaan yang lambat atau memblokir dalam metode
set_up()agen, seperti panggilan jaringan yang menunggu layanan yang tidak dapat dijangkau.
Solusi yang direkomendasikan:
- Periksa log container yang ditautkan di kolom
logs_urlmetadata error untuk melihat tempat startup terhenti. - Pindahkan inisialisasi yang mahal dari waktu impor modul, dan minimalkan
jumlah langkah di
set_up()dengan cepat. Tunda pekerjaan yang tidak diperlukan untuk menyajikan permintaan pertama. - Pastikan layanan apa pun yang dipanggil agen selama startup dapat dijangkau dari agen, dan tetapkan waktu tunggu pada panggilan tersebut sehingga tidak dapat memblokir startup tanpa batas waktu.
- Jika log container menunjukkan bahwa agen dimulai secara normal, coba deploy ulang. Startup terkadang dapat memerlukan waktu lebih lama dari biasanya karena alasan yang tidak terkait dengan kode Anda.
Error Template yang Telah Dibuat Sebelumnya
Jika Anda mengalami masalah dengan template LangchainAgent selama deployment, hal ini mungkin disebabkan oleh salah satu masalah di bagian ini.
Error server internal
Masalah:
Anda akan menerima pesan error yang mirip dengan berikut ini:
InternalServerError: 500 Revision YYY is not ready and cannot serve traffic.
Sayangnya, ini adalah error umum untuk setiap masalah pada container saat runtime, dan kemungkinan penyebabnya adalah salah satu dari banyak error yang mungkin terjadi.
Kemungkinan penyebab:
- Status kotor pada
LangchainAgent. Hal ini mungkin terjadi jika.set_up()dipanggil diLangchainAgentsebelum men-deploy agen. - Versi paket yang tidak konsisten. Hal ini dapat terjadi jika paket yang diinstal di lingkungan pengembangan berbeda dengan paket yang diinstal di lingkungan jarak jauh di Agent Runtime.
Solusi yang direkomendasikan:
- Status kotor pada
LangchainAgent. Buat instance baru dariLangchainAgentatau hapusagent.set_up()dari kode sebelum men-deploy agen. - Spesifikasi paket tidak konsisten. Lihat bagian tentang memecahkan masalah error serialisasi.
Error serialisasi
Secara umum, penting untuk memastikan bahwa lingkungan "lokal" dan "jarak jauh"
disinkronkan saat men-deploy agen. Anda dapat memastikannya dengan menentukan
requirements= saat
men-deploy agen.
Jika Anda mengalami masalah terkait serialisasi (error yang terkait dengan "pickle" atau "pickling" identik dengan error "serialisasi"), hal ini mungkin disebabkan oleh salah satu masalah yang dijelaskan di bagian ini.
Versi Pydantic
Masalah:
Anda akan menerima pesan error yang mirip dengan berikut ini:
PicklingError: Can't pickle <cyfunction str_validator at 0x7ca030133d30>: it's
not the same object as pydantic.validators.str_validator
Kemungkinan penyebab:
Hal ini mungkin terjadi jika paket pydantic Anda lebih lama dari versi 2.6.4. Untuk memeriksa versi yang Anda gunakan, jalankan perintah berikut di terminal:
pip show pydanticSolusi yang direkomendasikan:
Update paket Anda dengan menjalankan perintah berikut di terminal:
pip install pydantic --upgradeJalankan perintah berikut di terminal untuk memverifikasi bahwa Anda menggunakan versi
2.6.4 atau yang lebih baru:
pip show pydanticJika Anda berada di instance notebook (misalnya, Jupyter, Colab, atau Workbench), Anda mungkin perlu memulai ulang runtime untuk menggunakan paket yang diupdate.
Versi Cloudpickle
Masalah:
Anda akan menerima pesan error yang mirip dengan berikut ini:
AttributeError: Can't get attribute '_class_setstate' on <module 'cloudpickle.cloudpickle'
from '/usr/local/lib/python3.10/site-packages/cloudpickle/cloudpickle.py'>
Kemungkinan penyebab:
Hal ini dapat terjadi jika versi paket cloudpickle Anda berbeda di lingkungan pengembangan dan lingkungan deployment. Untuk memeriksa versi yang Anda gunakan dalam pengembangan, jalankan perintah berikut di terminal:
pip show cloudpickleSolusi yang direkomendasikan:
Deploy versi cloudpickle yang sama di kedua lingkungan, seperti lingkungan pengembangan lokal dan agen yang di-deploy dari jarak jauh dengan menentukan requirements= saat men-deploy agen.
Error server internal
Masalah:
Anda akan menerima pesan error yang mirip dengan berikut ini:
InternalServerError: 500 Revision YYY is not ready and cannot serve traffic.
Kemungkinan penyebab:
Hal ini mungkin terjadi jika sys_version=
berbeda dari lingkungan pengembangan saat men-deploy agen.
Solusi yang direkomendasikan:
Setelah men-deploy agen, pertimbangkan untuk menghapus sys_version= dari argumen input.
Jika Anda masih mengalami masalah, laporkan bug.
Error bucket Cloud Storage
Jika Anda mengalami masalah dengan bucket staging Cloud Storage yang digunakan pada waktu deployment untuk mengumpulkan dan mengupload agen, hal ini mungkin disebabkan oleh salah satu masalah berikut:
Error izin
Solusi yang direkomendasikan:
Jika Anda ingin menggunakan bucket yang sudah ada: pastikan akun utama yang
diautentikasi untuk menggunakan Agent Platform (baik Anda sendiri atau akun layanan)
memiliki akses Storage Admin ke bucket, dan berikan izin ke
akun layanan.
Atau, Anda dapat menentukan bucket baru saat men-deploy agen dan SDK akan membuat bucket dengan izin yang diperlukan.
Jika Anda masih mengalami masalah, laporkan bug.
Subdirektori bucket Cloud Storage tidak dibuat
Masalah:
Anda akan menerima pesan error yang mirip dengan berikut ini:
NotFound: 404 Can not copy from \"gs://[LOCATION]-*/agent_engine/agent_engine.pkl\" to \"gs://*/code.pkl\", check if the source object and target bucket exist.
(Error 404 terjadi saat sistem mencoba menyalin ke folder yang tidak ada.)
Kemungkinan penyebab:
Hal ini mungkin disebabkan oleh masalah interpolasi string di versi
google-cloud-aiplatform sebelum versi 1.49.0. Masalah ini diperbaiki
di versi yang lebih baru. Untuk memeriksa versi google-cloud-aiplatform yang Anda gunakan, jalankan perintah berikut di terminal:
pip show google-cloud-aiplatformSolusi yang direkomendasikan:
Update paket Anda dengan menjalankan perintah berikut di terminal:
pip install google-cloud-aiplatform --upgradePastikan Anda menggunakan google-cloud-aiplatform versi 1.49.0 atau yang lebih baru
dengan menjalankan perintah berikut di terminal:
pip show google-cloud-aiplatformJika Anda menggunakan instance notebook (misalnya, Jupyter atau Colab atau Workbench), Anda mungkin perlu memulai ulang runtime sebelum dapat menggunakan paket yang diupdate.
Error pelanggaran VPC-SC
Jika Anda mengalami masalah dengan VPC-SC, salah satu masalah berikut mungkin menjadi penyebabnya:
Error izin
Masalah:
Anda akan menerima pesan error yang mirip dengan berikut ini:
Reasoning Engine instance REASONING_ENGINE_ID failed to start and cannot serve traffic.
atau:
Request is prohibited by organization's policy.
Kemungkinan penyebab:
Hal ini kemungkinan disebabkan oleh tidak adanya aturan ingress yang diperlukan di perimeter VPC-SC.
Solusi yang direkomendasikan:
Jika Anda menggunakan Agent Platform di lingkungan VPC-SC, Anda harus membuat aturan ingress di perimeter Anda untuk mengizinkan ingress dari Agen Layanan Mesin Penalaran (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com) ke layanan storage.googleapis.com dan layanan artifactregistry.googleapis.com.
Error akun layanan kustom
Jika Anda mengalami masalah dengan akun layanan, salah satu masalah berikut mungkin menjadi penyebabnya:
Bertindak sebagai akun layanan
Masalah:
Anda akan menerima pesan error yang mirip dengan berikut ini:
You do not have permission to act as service_account.
Kemungkinan penyebab:
Anda mungkin tidak memiliki izin iam.serviceAccounts.actAs di
akun layanan kustom yang digunakan untuk deployment. Perhatikan bahwa dalam sistem multi-agen
yang memiliki beberapa akun layanan kustom, satu
penulis atau deployer agen dapat bertindak sebagai beberapa akun layanan. Jika Anda
menggunakan akun layanan yang salah, error ini adalah perilaku yang diharapkan
Selain itu, Anda mungkin mengalami error ini jika akun layanan kustom berada di project yang berbeda dengan project tempat Anda men-deploy agen, dan kebijakan organisasi iam.disableCrossProjectServiceAccountUsage diterapkan di project akun layanan.
Lihat Akun layanan kustom lintas project untuk mengetahui daftar lengkap konfigurasi yang diperlukan untuk skenario ini.
Solusi yang direkomendasikan:
Pastikan Anda menggunakan akun layanan yang diinginkan. Periksa apakah Anda memiliki peran
Service Account User (roles/iam.serviceAccountUser) di akun layanan
ini. Jika tidak, minta administrator untuk memberi Anda peran di akun layanan ini.
Jika Anda berada dalam skenario lintas project, periksa apakah project akun layanan Anda
telah menerapkan kebijakan organisasi iam.disableCrossProjectServiceAccountUsage.
Jika demikian, minta administrator Anda untuk menonaktifkan kebijakan tersebut.
Server metadata tidak tersedia
Masalah:
Anda akan menerima pesan error yang mirip dengan berikut ini:
ServiceUnavailable: 503 Getting metadata from plugin failed with error
atau
Compute Engine Metadata server unavailable due to : Could not fetch URI /computeMetadata/v1/instance/service-accounts/default/token
Kemungkinan penyebab:
Hal ini dapat terjadi jika akun layanan kustom dan agen Anda berada di project yang berbeda dan Agen Layanan Agent Platform (service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com) tidak memiliki izin iam.serviceAccounts.getAccessToken di akun layanan kustom.
Lihat Akun layanan kustom lintas project untuk mengetahui daftar lengkap konfigurasi yang diperlukan untuk skenario ini.
Solusi yang direkomendasikan:
Minta administrator Anda untuk memberikan peran Service Account Token Creator
(roles/iam.serviceAccountTokenCreator) pada akun layanan kustom kepada Agen Layanan Agent Platform
(service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com)
dari project agen.
Agen Layanan Agent Platform harus berada dalam project yang sama dengan yang Anda gunakan untuk men-deploy agen. Binding IAM dari pemberian peran harus berada dalam project tempat akun layanan kustom berada.
Penyediaan lingkungan gagal
Masalah:
Pembuatan agen gagal dengan status 500, INTERNAL (REASONING_ENGINE_PROVISIONING_FAILED) dan pesan yang menyatakan bahwa lingkungan agen yang dikelola Google tidak dapat disediakan.
Kemungkinan penyebab:
Sebelum Agent Runtime men-deploy agen pertama Anda dalam project dan region, Agent Runtime menyiapkan resource yang dikelola Google untuk agen Anda, seperti agen layanan dan lingkungan hosting. Jika penyiapan ini gagal, setiap pembuatan agen yang tertunda di project dan region tersebut akan gagal dengan error ini.
Solusi yang direkomendasikan:
Hubungi dukungan dan sertakan nama operasi yang gagal dalam format projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID.
Solusi yang tidak berlaku:
- Mencoba kembali pembuatan agen tidak akan menyelesaikan error ini, karena Google harus memperbaiki penyiapan yang gagal terlebih dahulu.
- Mengubah kode, persyaratan, atau
resource_limitsagen Anda tidak akan membantu, karena kegagalan terjadi sebelum Agent Runtime men-deploy agen Anda. - Meminta peningkatan kuota untuk project Anda tidak akan berpengaruh, karena Google mengelola resource ini.
Error resource habis
Jika deployment Anda gagal dengan status 429, RESOURCE_EXHAUSTED, salah satu
masalah berikut mungkin menjadi penyebabnya:
Batas kapasitas atau kuota API terlampaui
Masalah:
Deployment gagal dengan status Error 429 atau RESOURCE_EXHAUSTED.
Kemungkinan penyebab:
Project telah melampaui batas kapasitas API atau kuota permintaan serentak.
Solusi yang direkomendasikan:
- Terapkan strategi backoff eksponensial dan percobaan ulang dalam skrip deployment.
- Verifikasi penggunaan saat ini terhadap batas di halaman Google Cloud Kuota untuk "Agent Platform API".
- Mengurangi frekuensi deployment serentak.
Region mencapai batas kapasitas untuk sementara
Masalah:
Deployment gagal dengan status 429, RESOURCE_EXHAUSTED dan pesan yang menyatakan bahwa region tersebut untuk sementara mencapai kapasitas untuk jumlah total memori atau CPU yang diizinkan.
Kemungkinan penyebab:
Deployment agen di suatu region memanfaatkan kumpulan kapasitas inferensi yang dikelola oleh Agent Runtime untuk Anda dan digunakan bersama oleh semua pelanggan di region tersebut. Jika pool habis, deployment baru di region tersebut akan gagal hingga kapasitas tersedia.
Batas ini bukan salah satu kuota project Anda. Kuota ini tidak muncul di halamanGoogle Cloud Kuota, dan tidak dapat dinaikkan dengan meminta penambahan kuota.
Solusi yang direkomendasikan:
- Deploy ke wilayah yang didukung lainnya. Ini adalah cara tercepat untuk membatalkan pemblokiran deployment.
- Coba lagi nanti. Region yang mencapai kapasitas adalah masalah sementara yang biasanya akan teratasi dengan sendirinya.
- Minta jumlah memori atau CPU yang lebih kecil untuk agen Anda. Deployment yang lebih kecil mungkin sesuai dengan kapasitas yang tersisa.
- Hubungi dukungan jika deployment di suatu region terus gagal dengan cara ini. Meskipun kami tidak dapat menaikkan batas, laporan Anda membantu kami mengarahkan kapasitas ke tempat yang diperlukan.
Solusi yang tidak berlaku:
- Menghapus agen yang ada tidak akan mengosongkan kapasitas untuk batas ini, karena kapasitas tidak digunakan oleh project Anda saja.
- Meminta penambahan kuota tidak akan berpengaruh, karena batas tersebut bukan kuota project.
Instance maksimum melebihi batas regional
Masalah:
Deployment gagal dengan status 429, RESOURCE_EXHAUSTED dan pesan yang menyatakan bahwa spec.deployment_spec.max_instances melebihi jumlah maksimum instance yang didukung untuk CPU atau memori yang diminta di resource_limits region.
Kemungkinan penyebab:
Saat Anda men-deploy agen, Agent Runtime akan mengalikan
spec.deployment_spec.max_instances dengan cpu dan memory per instance di
spec.deployment_spec.resource_limits dan memeriksa apakah alokasi puncak agen tunggal ini
sesuai dengan batas regional project penyajian yang mendasarinya. Jika
Anda tidak menentukan max_instances, Agent Runtime akan menerapkan nilai default
(seperti 200), yang di region dengan batas lebih rendah dapat melebihi instance maksimum
yang didukung saat dikalikan dengan cpu atau
memory yang dikonfigurasi per instance.
Solusi yang direkomendasikan:
- Tetapkan
spec.deployment_spec.max_instanceske nilai maksimum yang ditampilkan dalam pesan error (atau lebih sedikit). - Kurangi nilai
cpuataumemoryper instance dispec.deployment_spec.resource_limits. - Deploy agen ke wilayah yang didukung lain dengan batas yang lebih tinggi.
Solusi yang tidak berlaku:
- Meminta penambahan kuota di halaman Kuota Google Cloud project Anda tidak akan berpengaruh, karena batas ini diterapkan pada project penyaluran yang dikelola Google, bukan project Anda.
- Menghapus agen lain dalam project Anda atau mencoba lagi tanpa mengubah
max_instancesatauresource_limitstidak akan menyelesaikan error ini, karena pemeriksaan mengevaluasi alokasi puncak deployment tunggal terhadap batas statis.
Pencarian Agent Gateway dibatasi
Masalah:
Men-deploy atau mengupdate agen yang menggunakan Gateway Agen akan gagal
dengan status 429, RESOURCE_EXHAUSTED
(REASONING_ENGINE_AGENT_GATEWAY_LOOKUP_THROTTLED) dan pesan yang mirip dengan
berikut:
The Reasoning Engine could not be created or updated because the request to look up Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` was throttled. Wait about a minute, then try again.
Kemungkinan penyebab:
Sebelum deployment atau update dimulai, Agent Runtime akan mencari setiap
Agent Gateway
di spec.deployment_spec.agent_gateway_config agen untuk memvalidasi
permintaan. Error ini berarti bahwa pencarian dibatasi kapasitasnya untuk sementara. Permintaan
ditolak sebelum deployment atau update dimulai, sehingga agen Anda tidak
dibuat atau diubah.
Solusi yang direkomendasikan:
- Tunggu sekitar satu menit, lalu coba lagi deployment atau update.
- Dalam alur kerja otomatis, coba lagi permintaan dengan backoff eksponensial.
- Hubungi dukungan jika error berlanjut.
Solusi yang tidak berlaku:
- Mengubah kode,
requirements, atauresource_limitsagen Anda tidak akan menyelesaikan error ini, dan memeriksa log traffic container atau Agent Gateway tidak akan menampilkan error, karena permintaan ditolak sebelum Agent Runtime membangun atau memulai container agen Anda.
Error akses Secret Manager
Masalah:
Deployment gagal dengan status 400, INVALID_ARGUMENT
(REASONING_ENGINE_SECRET_ACCESS_DENIED) dan pesan yang mirip dengan
berikut:
The Reasoning Engine could not access `projects/PROJECT_NUMBER/secrets/SECRET_ID/versions/VERSION_ID` referenced by `spec.deployment_spec.secret_env` (reason: FAILURE_REASON).
Kemungkinan penyebab:
NOT_FOUND: ID secret atau ID versi yang ditentukan disecret_envtidak ada di Secret Manager dalam project yang sama dengan agen yang di-deploy, atau berisi kesalahan ketik.DESTROYEDatauDISABLED: Versi secret yang direferensikan di Secret Manager dalam status dihancurkan atau dinonaktifkan.PERMISSION_DENIED: Pada deployment berbasis akun layanan (service_accountkustom atau Agen Layanan Mesin Penalaran platform AI default), akun layanan yang dikonfigurasi tidak memiliki peran Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) pada secret yang direferensikan selama validasi deployment.
Solusi yang direkomendasikan:
- Untuk
NOT_FOUND,DESTROYED, atauDISABLED:- Di halaman Secret Manager project tempat Anda men-deploy agen, pastikan setiap
SECRET_IDdanVERSION_IDyang direferensikan disecret_envada dan dalam status Enabled. - Jika versi yang direferensikan dinonaktifkan atau dihancurkan, aktifkan versi yang valid atau update
secret_envuntuk mereferensikan versi yang diaktifkan.
- Di halaman Secret Manager project tempat Anda men-deploy agen, pastikan setiap
Untuk
PERMISSION_DENIED: Ikuti Mengelola akses ke secret untuk memberikan peran Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) pada secret tertentu ke akun layanan kustom khusus yang dikonfigurasi pada agen (atau beralih ke identitas agen yang terisolasi).
Kegagalan startup container saat menggunakan secret_env dengan AGENT_IDENTITY
Masalah:
Agen yang dikonfigurasi dengan identity_type = AGENT_IDENTITY dan secret_env gagal
atau waktu habis selama startup container (bukan menampilkan
REASONING_ENGINE_SECRET_ACCESS_DENIED selama validasi deployment).
Kemungkinan penyebab:
Untuk deployment AGENT_IDENTITY, Agent Runtime melewati validasi akses secret pada waktu deployment dan mengambil secret yang direferensikan saat startup container. Jika Anda
meneruskan secret_env selama pembuatan awal (sebelum identitas agen yang disediakan
ada dan telah diberi akses), jika identitas agen yang disediakan tidak memiliki
roles/secretmanager.secretAccessor pada secret yang direferensikan, atau jika versi secret
yang direferensikan tidak ada (NOT_FOUND), dinonaktifkan (DISABLED), atau dihancurkan
(DESTROYED), startup container akan berulang kali gagal mengambil secret.
Solusi yang direkomendasikan:
- Buat agen dengan
AGENT_IDENTITYterlebih dahulu tanpasecret_env. - Ikuti Mengelola akses ke secret
untuk memberikan
roles/secretmanager.secretAccessorpada secret tertentu ke identitas agen yang disediakan agen (tambahkanprincipal://kespec.effective_identitysaat menentukan anggota IAM—misalnya,--member="principal://EFFECTIVE_IDENTITY"). - Pastikan setiap versi secret yang direferensikan ada dan diaktifkan, lalu update
agen untuk melampirkan
secret_env. Batasi izinaiplatform.reasoningEngines.updatepada agen sehingga hanya akun utama yang diizinkan yang dapat mengubah kode yang berjalan sebagai identitasnya.
Error binding Agent Gateway
Jika Anda merutekan traffic melalui Agent Gateway dan men-deploy atau mengupdate agen gagal sebelum agen dimulai, salah satu masalah berikut mungkin menjadi penyebabnya:
Waktu tunggu binding Agent Gateway habis
Masalah:
Men-deploy atau mengupdate agen gagal dengan status 504, DEADLINE_EXCEEDED
(REASONING_ENGINE_AGENT_GATEWAY_PROVISION_TIMEOUT) dan pesan yang mirip dengan
berikut:
The Reasoning Engine timed out waiting for an in-progress operation on shared Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` to finish. Wait for the other operation to complete, then try again.
Kemungkinan penyebab:
Agen Agent Runtime dalam project dan region yang sama berbagi satu binding ke setiap Agent Gateway yang dikonfigurasi. Menyiapkan atau menghapus binding bersama dapat memerlukan waktu beberapa menit lebih lama daripada memasang agen ke binding aktif. Waktu deployment atau update Anda akan habis jika operasi pengikatan atau pelepasan ikatan lain dalam project dan region yang sama tidak selesai dalam waktu yang diizinkan. Penyebab umumnya dapat mencakup hal berikut:
- Binding awal serentak: Anda mengikat beberapa agen ke Agent Gateway dalam project dan region yang sama sebelum penyiapan bersama awal selesai.
- Pelepasan ikatan yang sedang berlangsung: Anda melepaskan ikatan atau menghapus agen terakhir yang terikat gateway dalam project dan region, lalu mengikat agen lain ke gateway yang sama atau berbeda sebelum penghapusan bersama selesai.
- Mencoba lagi setelah binding gagal: Deployment atau update yang mengikat gateway gagal, dan Anda mencobanya lagi sebelum Agent Runtime selesai membersihkan penyiapan yang gagal.
Solusi yang direkomendasikan:
- Tunggu beberapa menit hingga operasi lain pada gateway yang disebutkan dalam error selesai, lalu coba lagi deployment atau update.
- Untuk mengikat beberapa agen dalam project dan region tanpa binding Agent Gateway yang aktif, ikat satu agen terlebih dahulu dan tunggu hingga operasi tersebut berhasil. Kemudian, deploy atau update agen yang tersisa secara serentak.
- Dalam alur kerja otomatis, hindari melepaskan atau menghapus agen terakhir yang terikat gateway dalam project dan region tepat sebelum mengikat agen lain. Menghapus agen terakhir yang terikat gateway akan menghapus binding bersama, sehingga deployment berikutnya akan mengulangi penyiapan lengkap.
Solusi yang tidak berlaku:
- Memeriksa log container atau log traffic Agent Gateway tidak akan menunjukkan error untuk kegagalan ini, karena waktu tunggu habis terjadi sebelum Agent Runtime memulai container agen Anda.
- Mengubah kode agen,
requirements, atauresource_limitstidak akan mengurangi waktu penyiapan binding bersama.
Jika binding gateway berhasil, tetapi container gagal dimulai, lihat Error selama startup Agent Runtime.
Pengikatan Agent Gateway dibatalkan
Masalah:
Men-deploy atau mengupdate agen gagal dengan status 409, ABORTED
(REASONING_ENGINE_AGENT_GATEWAY_CONCURRENT_PROVISION_ABORTED) dan pesan
yang mirip dengan berikut ini:
The Reasoning Engine could not be bound to Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` because a concurrent shared gateway provisioning operation failed and rolled back. Try again.
Kemungkinan penyebab:
Agen Agent Runtime dalam project dan region yang sama menggunakan satu binding ke setiap Agent Gateway yang dikonfigurasi. Saat Anda mengikat beberapa agen ke gateway yang sama sebelum binding bersamanya disiapkan, satu deployment atau update akan menyiapkan binding dan yang lainnya akan menunggu. Jika deployment atau update tersebut gagal sebelum binding siap, Agent Runtime akan me-roll back binding, dan setiap deployment atau update yang menunggu binding tersebut akan gagal dengan error ini. Deployment atau update yang menyiapkan binding akan melaporkan errornya sendiri, yang mungkin tidak terkait dengan Agent Gateway.
Solusi yang direkomendasikan:
- Tunggu minimal 10 menit hingga Agent Runtime selesai me-roll back
penyiapan yang gagal, lalu coba lagi deployment atau update. Percobaan ulang yang dimulai sebelum rollback selesai dapat gagal dengan status
504,DEADLINE_EXCEEDED. Lihat Waktu tunggu binding Agent Gateway habis. - Untuk mencoba kembali beberapa deployment atau update, coba lagi satu deployment atau update terlebih dahulu dan tunggu hingga
operasi tersebut berhasil, lalu coba lagi deployment atau update lainnya secara serentak. Jika operasi pertama tersebut gagal, operasi tersebut akan menampilkan error yang mendasarinya, bukan
409,ABORTED(misalnya, Binding Agent Gateway tidak tersedia untuk sementara atau Build image container gagal), yang dapat Anda cari di katalog error.
Solusi yang tidak berlaku:
- Memeriksa log container atau log traffic Agent Gateway tidak akan menunjukkan error untuk kegagalan ini, karena kegagalan terjadi sebelum Agent Runtime memulai container agen Anda.
- Mengubah kode,
requirements, atauresource_limitsagen Anda tidak akan membantu, karena deployment atau update lain yang menyebabkan error ini, bukan agen Anda.
Binding Agent Gateway tidak tersedia untuk sementara
Masalah:
Men-deploy atau mengupdate agen gagal dengan status 503, UNAVAILABLE
(REASONING_ENGINE_AGENT_GATEWAY_PROVISION_UNAVAILABLE) dan pesan yang mirip
dengan berikut ini:
The Reasoning Engine could not be bound to Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` because network provisioning encountered a transient upstream service error. Try again.
Kemungkinan penyebab:
Saat agen pertama dalam project dan region terikat ke
Agent Gateway, Agent Runtime menyiapkan resource jaringan bersama yang dikelola Google
yang menghubungkan agen ke gateway. Jika layanan Google Cloud
yang diandalkan oleh penyiapan ini terus menampilkan error sementara setelah
beberapa kali percobaan ulang otomatis, Agent Runtime akan me-roll back penyiapan dan
deployment atau update akan gagal dengan error ini. Deployment atau update lain yang
menunggu penyiapan yang sama akan gagal dengan status 409, ABORTED. Lihat
Pengikatan Agent Gateway
dibatalkan.
Solusi yang direkomendasikan:
- Tunggu minimal 10 menit hingga Agent Runtime selesai me-roll back
penyiapan yang gagal, lalu coba lagi deployment atau update. Percobaan ulang yang dimulai sebelum rollback selesai dapat gagal dengan status
504,DEADLINE_EXCEEDED. Lihat Waktu tunggu binding Agent Gateway habis. - Jika error tetap berlanjut setelah beberapa kali percobaan ulang, hubungi
dukungan dan sertakan nama operasi yang gagal dalam format
projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID.
Solusi yang tidak berlaku:
- Mengubah kode,
requirements, atauresource_limitsagen Anda tidak akan membantu, karena kegagalan terjadi sebelum Agent Runtime men-deploy agen Anda. - Meminta penambahan kuota untuk project Anda tidak akan berpengaruh, karena Google mengelola resource jaringan ini.
Referensi dukungan
Jika masalah Anda masih belum terselesaikan, lihat panduan dukungan kami untuk mendapatkan bantuan.