Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Memecahkan masalah autentikasi Identitas Agen

Untuk mengatasi error umum saat mengautentikasi agen dengan Agent Identity dan pengelola autentikasi Agent Identity, verifikasi konfigurasi penyedia autentikasi, binding peran Identity and Access Management (IAM), cakupan OAuth, dan setelan verifikasi token OpenID Connect (OIDC).

Untuk mengelola penyedia autentikasi, lihat Mengelola penyedia autentikasi Agent Identity. Untuk memverifikasi token ID Identitas Agen di layanan eksternal, lihat Melakukan autentikasi ke layanan eksternal menggunakan identitas agen sendiri.

URI pengalihan tidak cocok

Jika Anda menerima error redirect URI mismatch dari aplikasi pihak ketiga selama alur OAuth, pastikan URI pengalihan yang terdaftar di portal developer pihak ketiga sama persis dengan URI yang dihasilkan oleh pengelola autentikasi.

Untuk mengatasi masalah ini, temukan URI pengalihan yang dihasilkan dengan melihat detail penyedia autentikasi di konsol Google Cloud atau menjalankan perintah gcloud berikut:

gcloud alpha agent-identity authProviders describe AUTH_PROVIDER_NAME \
    --location="LOCATION"

Peran pengguna tidak ada

Jika agen Anda tidak dapat menggunakan penyedia autentikasi, pastikan identitas agen memiliki peran roles/agentidentity.user pada resource penyedia autentikasi.

Untuk mengatasi masalah ini, berikan peran menggunakan konsol Google Cloud atau jalankan perintah add-iam-policy-binding.

Masalah endpoint penerbit

Untuk penyedia OIDC, pastikan endpoint penerbit dapat diakses secara publik dan mendukung dokumen discovery .well-known/openid-configuration.

Jika Google Cloud tidak dapat mengambil metadata OIDC atau JWKS, pastikan endpoint tidak berada di balik firewall atau jaringan yang dibatasi.

Error 401 UNAUTHENTICATED

Jika agen Anda tidak dapat melakukan autentikasi, error berikut mungkin terjadi. Error ini biasanya disebabkan oleh kebijakan Akses Kontekstual yang dikelola Google yang menerapkan binding mTLS dan bukti kriptografis DPoP:

{
  "error": {
    "code": 401,
    "message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
    "status": "UNAUTHENTICATED"
  }
}

Untuk mengatasi error ini, Anda dapat memilih tidak ikut kebijakan Akses Kontekstual default jika memiliki persyaratan berbagi token tertentu atau harus memasukkan token langsung ke header. Untuk memilih tidak ikut, tetapkan variabel lingkungan berikut saat Anda men-deploy agen:

config={
  "env_vars": {
    "GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN": "false",
  }
}

Layanan kunci API diblokir (`API_KEY_SERVICE_BLOCKED`)

Jika Anda memvalidasi kunci API, error berikut mungkin terjadi. Error ini menunjukkan bahwa layanan diblokir:

"details": [
  {
    "@type": "type.googleapis.com/google.rpc.ErrorInfo",
    "reason": "API_KEY_SERVICE_BLOCKED",
    "domain": "googleapis.com",
    "metadata": {
      "methodName": "google.cloud.translate.v2.TranslateService.TranslateText",
      "service": "translate.googleapis.com",
      "consumer": "projects/PROJECT_NUMBER",
      "apiName": "translate"
    }
  },
  {
    "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
    "locale": "en-US",
    "message": "Requests to this API translate method google.cloud.translate.v2.TranslateService.TranslateText are blocked."
  }
]

Error ini terjadi karena layanan API target (misalnya, Cloud Translation API) belum diaktifkan di project Google Cloud Anda, atau batasan kunci API tidak mengizinkan akses ke layanan ini.

Untuk mengatasi error ini, lakukan langkah-langkah berikut:

Di konsol Google Cloud , buka halaman APIs & Services >Library dan pastikan API target diaktifkan.
Buka APIs & Services >Library
Di konsol Google Cloud , buka halaman APIs & Services >Credentials, edit kunci API Anda, dan pastikan pembatasan API-nya mengizinkan akses ke layanan.
Buka APIs & Services >Credentials

Kunci API tidak valid (`API_KEY_INVALID`)

Saat mengirim permintaan ke layanan pihak ketiga, error berikut mungkin terjadi. Error ini menunjukkan bahwa kunci API tidak valid:

"details": [
  {
    "@type": "type.googleapis.com/google.rpc.ErrorInfo",
    "reason": "API_KEY_INVALID",
    "domain": "googleapis.com",
    "metadata": {
      "service": "translate.googleapis.com"
    }
  },
  {
    "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
    "locale": "en-US",
    "message": "API key not valid. Please pass a valid API key."
  }
]

Error ini terjadi karena string kunci API yang diteruskan di header permintaan Anda salah, salah format, atau tidak ada di kredensial project Anda.

Untuk mengatasi error ini, pastikan Anda menyalin string kunci API yang benar dari halaman Credentials di konsol Google Cloud dan tidak menyertakan spasi kosong di awal atau di akhir.

Izin ditolak saat mengambil kredensial (`agentidentity.authProviders.retrieveCredentials`)

Saat menjalankan adk web secara lokal atau berinteraksi dengan agen yang di-deploy, error 403 Forbidden berikut mungkin terjadi:

google.api_core.exceptions.Forbidden: 403 POST https://agentidentitycredentials.mtls.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME/credentials:retrieve?%24alt=json%3Benum-encoding%3Dint: Permission 'agentidentity.authProviders.retrieveCredentials' denied on resource '//agentidentity.googleapis.com/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME' (or it may not exist).

Error ini terjadi karena akun utama yang mencoba memanggil penyedia autentikasi tidak memiliki izin IAM yang diperlukan untuk mengambil kredensial.

Untuk mengatasi error ini, berikan peran Agent Identity User (roles/agentidentity.user) kepada akun utama:

Jika error ini terjadi selama pengembangan lokal (uv run adk web atau uvicorn), pastikan Anda telah memberikan peran tersebut ke akun pengguna pribadi Anda (user:USER_EMAIL).
Jika error ini terjadi saat berinteraksi dengan agen yang di-deploy, pastikan Anda telah memberikan peran tersebut ke akun utama ID SPIFFE agen Anda (principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID).

Kegagalan deployment umum

Saat men-deploy agen menggunakan uv run adk deploy, perintah mungkin gagal dengan pesan error umum.

Error ini terjadi karena dependensi Python yang tidak ada, error sintaksis di agent.py, atau variabel lingkungan yang salah dikonfigurasi.

Untuk mengatasi error ini, lakukan hal berikut:

Buka konsol Google Cloud , lalu buka halaman Logs Explorer.
Telusuri log container deployment sementara (misalnya, maps_mcp_agent_tmp... atau bigquery_mcp_agent_tmp...).
Periksa traceback Python untuk mengidentifikasi error sintaksis atau melacak paket yang tidak ada.
Pastikan semua paket yang diperlukan tercantum dalam file requirements.txt Anda.

Loop autentikasi ServiceNow atau cakupan yang tidak terduga

Saat agen melakukan autentikasi ke ServiceNow menggunakan 3-legged OAuth, alur autentikasi mungkin gagal atau agen mungkin memasuki loop permintaan.

Masalah ini terjadi karena ServiceNow menentukan cakupan yang diberikan di tingkat aplikasi, bukan dari cakupan yang diminta oleh agen. Jika administrator mengonfigurasi cakupan tertentu pada aplikasi ServiceNow (misalnya, useraccount), ServiceNow akan menampilkan token yang hanya berisi cakupan yang dikonfigurasi tersebut, meskipun agen meminta cakupan yang berbeda (seperti mcp_server). Jika agen benar-benar mengharapkan atau memvalidasi cakupan yang diminta, agen akan menolak token yang diterima dan mungkin akan meminta ulang kredensial dalam loop.

Untuk mengatasi masalah ini, lakukan langkah berikut:

Login ke instance ServiceNow Anda sebagai administrator.
Buka konfigurasi aplikasi OAuth ServiceNow.
Pastikan semua cakupan yang diperlukan oleh agen Anda ditambahkan secara eksplisit ke daftar cakupan yang diizinkan untuk aplikasi.
Konfigurasikan agen Anda untuk hanya meminta cakupan yang diaktifkan di ServiceNow.

Untuk mengetahui informasi selengkapnya, lihat Layanan pihak ketiga yang didukung.

Error beberapa cakupan GitHub atau Microsoft

Saat mengonfigurasi penyedia autentikasi untuk GitHub atau Microsoft, autentikasi akan gagal jika Anda meminta beberapa cakupan OAuth.

Pengelola autentikasi mendukung integrasi cakupan tunggal untuk GitHub dan Microsoft. Pengelola autentikasi tidak mendukung permintaan beberapa cakupan secara bersamaan.

Untuk mengatasi masalah ini, konfigurasikan agen atau penyedia autentikasi Anda agar hanya meminta satu cakupan yang diperlukan untuk integrasi.

Untuk mengetahui informasi selengkapnya, lihat Layanan pihak ketiga yang didukung.

Error endpoint JWKS dan penemuan OpenID Connect

Layanan eksternal atau pihak tepercaya dapat mengkueri endpoint Google Cloud Security Token Service OpenID Connect Discovery (/.well-known/openid-configuration) atau JSON Web Key Set (/openid/jwks) untuk memverifikasi token ID Identitas Agen. Saat membuat kueri endpoint ini, permintaan mungkin gagal dengan error HTTP 400, 404, 429, atau 500.

Tabel berikut menjelaskan penyebab dan penyelesaian untuk error ini:

Status HTTP	Penyebab	Resolusi
`400 Bad Request`	Error ini terjadi karena nama resource workload identity pool dalam URL permintaan tidak valid, atau permintaan menyertakan header HTTP `Authorization`.	Untuk mengatasi error ini, lakukan hal berikut: Pastikan nama resource workload identity pool menggunakan format domain kepercayaan agen yang didukung (`agents.global.org-ORGANIZATION_ID.system.id.goog` atau `agents.global.proj-PROJECT_NUMBER.system.id.goog`). Hapus header `Authorization` atau OAuth dari permintaan. Endpoint `/.well-known/openid-configuration` dan `/openid/jwks` bersifat publik dan tidak diautentikasi; meneruskan header autentikasi akan menyebabkan permintaan gagal dengan error `HTTP 400`.
`404 Not Found`	Error ini terjadi karena ID organisasi, nomor project, atau workload identity pool yang ditentukan tidak ada, atau jalur URL salah.	Untuk mengatasi error ini, pastikan ID organisasi, nomor project, dan domain kepercayaan (ID workload identity pool) di URL sudah akurat. Pastikan juga jalur URL diakhiri dengan `/.well-known/openid-configuration` atau `/openid/jwks`.
`429 Too Many Requests`	Error ini terjadi karena pemverifikasi Anda melebihi batas rasio permintaan dengan mengkueri endpoint penemuan atau JWKS tanpa meng-cache respons.	Untuk mengatasi error ini, konfigurasikan pemverifikasi Anda untuk meng-cache dokumen penemuan dan JWKS hingga 24 jam sesuai dengan header respons `Cache-Control: public, max-age=86400, must-revalidate`.
`500 Internal Server Error`	Error ini terjadi karena server mengalami masalah internal sementara saat mengambil kunci penandatanganan publik.	Untuk mengatasi error ini, gunakan JWKS yang di-cache jika tersedia, atau coba lagi permintaan dengan backoff eksponensial.

Verifikasi tanda tangan token gagal setelah rotasi kunci

Saat layanan eksternal memverifikasi token ID Identitas Agen, verifikasi tanda tangan mungkin gagal untuk token yang baru diterbitkan meskipun token sebelumnya dari agen yang sama berhasil.

Masalah ini terjadi karena Google Cloud secara berkala merotasi kunci penandatanganan pribadi dan publik untuk workload identity pool. Akibatnya, kid (ID kunci) token yang masuk mungkin tidak ada dalam cache kunci lokal pemverifikasi Anda.

Untuk mengatasi masalah ini, konfigurasikan pemverifikasi Anda sehingga saat menerima token dengan kid yang tidak dikenali, pemverifikasi akan mengambil JWKS baru dari endpoint /openid/jwks sebelum menolak token.