Questa guida ti aiuta a eseguire il debug e a risolvere i problemi di connettività con la piattaforma Gemini Enterprise Agent, in particolare quando utilizzi Agent Gateway, l'identità dell'agente, le policy di Identity and Access Management (IAM) e l'autorizzazione delegata con Service Extensions.
Se il deployment o l'aggiornamento dell'agente non va a buon fine prima dell'avvio, consulta Risolvi i problemi di deployment di un agente. Se l'associazione di un gateway non riesce, consulta Errori di associazione di Agent Gateway.
Risolvi i problemi utilizzando la skill di risoluzione dei problemi di Agent Platform
Per diagnosticare i problemi di connettività, autorizzazione e avvio in modo interattivo con un assistente di coding AI, puoi installare la skill agent-platform-troubleshooting dal repository delle skill dell'agente Google Cloud .
Questa skill fornisce agli agenti AI playbook diagnostici specifici per il dominio, filtri dei log e passaggi di risoluzione nello stack della piattaforma degli agenti, tra cui:
- Rifiuti in uscita di Agent Gateway: diagnosi degli errori
403 Forbiddenintercettati dal gateway e verifica delle decisioni di autorizzazione IAP. - Errori di avvio di Agent Runtime: identificazione dei ruoli mancanti (come
roles/browseroresourcemanager.projects.get) ed eccezioni di bootstrap. - Problemi relativi alla destinazione Agent Registry: verifica delle voci di servizio, delle interfacce degli endpoint e delle configurazioni consolidate delle API di Google.
- Policy di accesso IAM: convalida delle associazioni delle Unified Access Policies (UAP), delle espressioni delle condizioni e della definizione dell'ambito del confine di accesso dell'entità (PAB).
- Attendibilità dei container: diagnosi degli errori di handshake e certificato TLS per i container personalizzati (BYOC) o le autorità di certificazione (CA) private.
Per installare la skill nell'ambiente dell'agente, esegui questo comando:
npx skills add https://github.com/google/skills --skill agent-platform-troubleshooting
Flusso di richieste in uscita
Agent Platform adotta un criterio default-deny per tutto il traffico in uscita. Affinché un agente possa connettersi a risorse esterne, devi consentire esplicitamente l'accesso a ogni livello di rete e identità. Quando Agent Gateway è abilitato, il gateway intercetta tutte le richieste dell'agente e applica le policy configurate.
Affinché una richiesta vada a buon fine, deve soddisfare tutte le seguenti condizioni:
- Policy di accesso IAM: all'identità dell'agente assegnata all'agente deve essere concessa l'autorizzazione
iap.resources.egressViaIAPsulla risorsa di destinazione, direttamente o tramite un set di entità. Per maggiori dettagli, consulta Crea policy degli agenti IAM. Scopri come risolvere i problemi relativi alle policy IAP. - Agent Registry: ti consigliamo di registrare le destinazioni in Agent Registry per applicare policy di accesso granulari per risorsa e controlli a livello di strumento. Se l'agente sta tentando di raggiungere una destinazione non registrata, devi concedere l'autorizzazione
iap.resources.egressViaIAPall'identità dell'agente configurando una policy per un endpoint non registrato. - Agent Gateway: il gateway deve essere associato a una policy di autorizzazione che lo ha come target esplicito. Per impostazione predefinita, il gateway utilizza IAP e Model Armor per proteggere le richieste.
- Autorizzazione delegata con Service Extensions: puoi delegare le decisioni di autorizzazione a un motore di autorizzazione personalizzato utilizzando Service Extensions. A seconda della policy di autorizzazione configurata, uno o più di questi motori di autorizzazione consentiranno o negheranno la richiesta.
Problemi comuni
Esamina questi problemi comuni e le relative soluzioni durante la risoluzione dei problemi di Agent Gateway.
Errori durante l'avvio di Agent Runtime
Se le istanze di Agent Runtime non si avviano o non vengono sottoposte a deployment, potrebbe significare che IAP sta bloccando il traffico interno o che l'agente non dispone dei ruoli di base necessari per l'inizializzazione.
Verifica che IAP non blocchi le chiamate ai servizi interni
Sintomo: errori
403 Forbiddendurante l'avvio.Causa: Agent Gateway utilizza una policy di negazione predefinita per tutto il traffico. Pertanto, quando IAP è in modalità di applicazione forzata, blocca le chiamate anche ai servizi interni (come
aiplatformologging), a meno che non siano registrati e l'agente non disponga delle autorizzazioni IAM richieste.Correzione: passa temporaneamente IAP alla modalità dry run per vedere quali connessioni non vanno a buon fine senza bloccare l'avvio oppure esegui una query su Cloud Logging per identificare i nomi host bloccati esatti. Dopo aver identificato i nomi host dei servizi target, registrali in Agent Registry e concedi l'autorizzazione
iap.resources.egressViaIAPall'agente.Per trovare nomi host bloccati specifici utilizzando Cloud Logging, esegui questa query in Esplora log:
resource.type="networkservices.googleapis.com/Gateway" resource.labels.gateway_type="SECURE_WEB_GATEWAY" httpRequest.status=403
Esamina i campi
httpRequest.requestUrlojsonPayload.authzPolicyInfonei risultati per trovare i nomi host di destinazione.I servizi interni comuni che potrebbero richiedere la registrazione durante l'avvio includono:
- Agent Platform (Motore di ragionamento e sessioni di Agent Platform):
https://REGION-aiplatform.mtls.googleapis.com - Resource Manager:
https://cloudresourcemanager.mtls.googleapis.comehttps://cloudresourcemanager.mtls.googleapis.com/ - Google Cloud Observability (se abilitato):
https://telemetry.mtls.googleapis.com/ - Cloud Logging (se abilitato):
https://logging.googleapis.com/ - Cloud Monitoring:
https://monitoring.googleapis.com/ehttps://monitoring.mtls.googleapis.com/ - Cloud Trace:
https://cloudtrace.googleapis.com/ehttps://cloudtrace.mtls.googleapis.com/ - Secret Manager:
https://secretmanager.googleapis.com/ehttps://secretmanager.mtls.googleapis.com/
- Agent Platform (Motore di ragionamento e sessioni di Agent Platform):
Verifica che l'identità dell'agente disponga dei ruoli di base richiesti
Sintomi: nei log di
aiplatform.googleapis.com/reasoning_engine_stderr, vengono visualizzati errori comegoogle.api_core.exceptions.Unknown: NoneoFailed to convert project number to project ID. L'errore viene visualizzato durante l'avvio del motore di ragionamento.Causa. L'identità dell'agente non dispone dell'autorizzazione
resourcemanager.projects.getrichiesta per risolvere il nome del progetto durante l'inizializzazione.Correggi. Assicurati che l'identità dell'agente (o il suo set di entità) disponga delle autorizzazioni necessarie per leggere la propria configurazione di runtime. Sono richiesti i seguenti ruoli:
roles/aiplatform.agentDefaultAccess: ruolo predefinito dell'agente.roles/aiplatform.user: obbligatorio per eseguire l'agente.roles/agentregistry.viewer: obbligatorio per visualizzare le risorse registrate.roles/logging.logWritereroles/monitoring.metricWriter: obbligatori per l'osservabilità.roles/browser: obbligatorio per eseguireresourcemanager.projects.getdurante l'inizializzazione dell'SDK.
Per verificare i ruoli assegnati all'identità dell'agente, esegui il comando seguente:
gcloud projects get-iam-policy PROJECT_ID \ --flatten="bindings[].members" \ --filter="bindings.members:AGENT_IDENTITY_PRINCIPAL"
Sostituisci quanto segue:
PROJECT_ID: l'ID progetto Google Cloud .AGENT_IDENTITY_PRINCIPAL: l'entità Agent Identity. Utilizza il formato:principal://TRUST_DOMAIN/resources/SERVICE/RESOURCE_PATH
Per scoprire come concedere i ruoli, consulta Utilizza l'identità dell'agente con Agent Runtime.
403 Forbidden errori
Se riscontri un errore 403 Forbidden, verifica che sia correlato al traffico in uscita di Agent Gateway. Ecco un esempio di messaggio di errore in uscita:
{"code": 403, "message": "403 Forbidden. {'message': 'Egress request is not authorized.', 'status': 'Forbidden'}"}
Esegui una query sui log dell'agente in Logging per trovare le chiamate specifiche che non vanno a buon fine:
resource.type="aiplatform.googleapis.com/ReasoningEngine" resource.labels.location="LOCATION" resource.labels.reasoning_engine_id="AGENT_ID" textPayload:"403"
Sostituisci quanto segue:
LOCATION: la regione in cui è stato eseguito il deployment dell'agente, ad esempious-central1.AGENT_ID: l'ID dell'agente (motore di ragionamento).
Cerca il messaggio Egress request is not authorized nel campo textPayload della voce di log. Se l'errore 403 contiene un testo diverso, è possibile che il servizio di destinazione rifiuti direttamente la chiamata, anziché Agent Gateway.
Puoi anche visualizzare i log del traffico in uscita, inclusi i rifiuti di 403, utilizzando la dashboard di osservabilità integrata.
Impossibile connettersi alle destinazioni CA private o autofirmate
- Sintomo: l'agente non riesce a connettersi alle destinazioni che presentano certificati autofirmati o emessi da CA private.
- Causa: per impostazione predefinita, Agent Gateway considera attendibili solo i certificati emessi da CA attendibili pubblicamente. La connessione a destinazioni che utilizzano CA private o certificati autofirmati richiede una configurazione aggiuntiva.
- Mitigazione: per connetterti alle destinazioni utilizzando CA private o certificati autofirmati, devi configurare trust anchor TLS personalizzati utilizzando l'impostazione
tlsConfigin un template di connettività dell'agente. Se i tuoi agenti si connettono anche alle API Google Cloud (*.googleapis.com) o ad altri endpoint HTTPS pubblici, assicurati cheadditionalRootssia impostato suPUBLICLY_TRUSTED_ROOTSintlsConfig. Se aggiorni le impostazioni ditlsConfig, devi associare un nuovo template di connettività (o annullare l'associazione e riassociarlo) perché Agent Gateway non rileva automaticamente le modifiche ditlsConfigin un template collegato.
L'agente di cui è stato eseguito il deployment con un container personalizzato (BYOC) non riesce a connettersi ad Agent Gateway
- Sintomo: l'agente BYOC non riesce a stabilire connessioni quando viene instradato tramite Agent Gateway. I log potrebbero mostrare errori di TLS handshake o di verifica del certificato.
- Causa: il container personalizzato dell'agente non considera attendibile l'autorità di certificazione di Agent Gateway.
- Correzione: assicurati di aver aggiunto il certificato radice di Agent Gateway allo store CA del container. Consulta Configura gli agenti container personalizzati (BYOC) per Agent Gateway.
L'associazione delle policy non va a buon fine o simula un rifiuto della governance
- Sintomo: le configurazioni delle associazioni delle policy non vanno a buon fine, ti viene richiesto in modo interattivo un
etagdurante l'associazione delle policy o le richieste non vanno a buon fine con un errore di rifiuto della governance falso (ad esempio "destinazione non registrata rifiutata correttamente"). - Causa: l'API Identity-Aware Proxy (
iap.googleapis.com) è disabilitata nel tuo progetto. - Correzione: abilita l'API IAP.
Errori durante la gestione di Agent Gateway con la federazione delle identità della forza lavoro
Potresti riscontrare questo problema se gestisci Agent Gateway nella consoleGoogle Cloud o utilizzi gcloud CLI dopo l'autenticazione con la federazione delle identità per la forza lavoro (WIF).
La console visualizza errori di caricamento o creazione generici, ad esempio:
- "Si è verificato un errore durante il caricamento…"
- "Il server non è riuscito a completare la tua richiesta"
- Impossibile creare l'Agent Gateway
- "Impossibile caricare"
Inoltre, i comandi gcloud (come gcloud network-services agent-gateways
import) potrebbero restituire un errore interno, ad esempio error 13: an internal error
has occurred.
Per risolvere il problema, esegui l'autenticazione con un Account Google standard gestito tramite Cloud Identity o Google Workspace con le autorizzazioni richieste, ad esempio roles/networkservices.admin.
Le identità federate hanno un supporto limitato nei servizi Agent Platform Governance e Gateway in anteprima. La concessione di ruoli IAM più ampi a un'entità federata non risolve il problema.
Workflow di debug
Se una delle condizioni descritte nella sezione Flusso di richieste in uscita non è presente, le tue richieste potrebbero essere bloccate.
Esamina la decisione di IAP
Per restringere la ricerca dei log alle decisioni relative al traffico in uscita di IAP, esegui la seguente query in Logging:
protoPayload.serviceName="iap.googleapis.com" protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP" protoPayload.metadata.mcp_attributes.base_protocol_method="true"
Se non vedi alcuna voce di log IAP corrispondente, il gateway potrebbe aver rifiutato la richiesta prima che IAP la valutasse. Vai al passaggio successivo.
Se vedi una voce di log corrispondente, esamina i seguenti campi:
protoPayload.authorizationInfo[].granted: indica se la richiesta è stata consentita (true) o negata (false).protoPayload.authenticationInfo.principalSubject: l'ID SPIFFE o l'identitàprincipal://...del chiamante. Verifica che corrisponda all'identità del tuo agente.protoPayload.authorizationInfo[].resource: la risorsa di destinazione registrata a cui è stata risolta la chiamata.labels."iap.googleapis.com/audited_resource_name": se questo valore èunregisteredResource, il nome host di destinazione non è registrato. Registra il nome host di destinazione con Agent Registry e assicurati che l'agente disponga dell'autorizzazioneiap.resources.egressViaIAPper questa destinazione.- Modalità di applicazione forzata: esamina la modalità di applicazione forzata della richiesta. Per filtrare le richieste dry run, puoi aggiungere
protoPayload.metadata.iamEnforcementMode="DRY_RUN"alla query. In modalitàDRY_RUN, IAP registra i rifiuti, ma non li applica. Pertanto, se l'agente non va a buon fine con un errore403in modalità dry run, il rifiuto probabilmente proviene dal proxy in uscita del gateway o dalla risorsa di destinazione.
Esamina la decisione di Agent Gateway
Per esaminare il modo in cui Agent Gateway ha valutato la richiesta, esegui una query sui log del gateway in Logging. In questo esempio, filtriamo i log solo per gli errori 403:
resource.type="networkservices.googleapis.com/Gateway" resource.labels.gateway_type="SECURE_WEB_GATEWAY" resource.labels.location="REGION" resource.labels.gateway_name="AGENT_GATEWAY_NAME" httpRequest.status=403 -httpRequest.requestMethod="CONNECT"
Esamina i seguenti campi nella voce di log corrispondente:
jsonPayload.authzPolicyInfo.policies.result: il risultato complessivo dell'autorizzazione,ALLOWEDoDENIED.httpRequest.requestUrl: prendi nota dell'URL di destinazione esatto che l'agente ha tentato di raggiungere. Nel passaggio successivo, controlliamo se il nome host utilizzato dalla risorsa di destinazione è stato registrato in Agent Registry.
Verifica la registrazione della destinazione e la copertura delle policy di accesso IAM
L'accesso alle destinazioni richiede sempre una policy di autorizzazione IAM che conceda l'autorizzazione iap.resources.egressViaIAP all'identità dell'agente.
Ti consigliamo di registrare le destinazioni in Agent Registry per applicare policy di accesso granulari per risorsa e garantire una corrispondenza accurata dei nomi host. Per le destinazioni non registrate, verifica se una policy per gli endpoint non registrati concede l'autorizzazione richiesta all'identità dell'agente.
Se utilizzi policy per risorsa, ogni nome host di destinazione e tutte le sue varianti che l'agente tenta di raggiungere devono essere registrati in Agent Registry. Questo perché un'API di Google come aiplatform.googleapis.com può essere risolta tramite più nomi host a seconda della versione dell'SDK, della configurazione del client regionale o dell'utilizzo di mTLS (ad esempio, us-central1-aiplatform.googleapis.com o us-central1-aiplatform.mtls.googleapis.com).
Poiché il gateway corrisponde esattamente ai nomi host, se registri
aiplatform.googleapis.com, ma l'agente chiama
us-central1-aiplatform.googleapis.com, il gateway la considera una
risorsa non registrata e nega la richiesta.
Esegui il seguente script di esempio per elencare le voci del registry in base al tipo di risorsa e controlla le voci per il nome host specifico utilizzato dalla chiamata dell'agente:
HOSTNAME="HOSTNAME" PROJECT_ID="PROJECT_ID" LOCATION="REGION" echo "Checking Endpoints..." gcloud agent-registry endpoints list \ --project="$PROJECT_ID" \ --location="$LOCATION" | grep "$HOSTNAME" echo "Checking MCP Servers..." gcloud agent-registry mcp-servers list \ --project="$PROJECT_ID" \ --location="$LOCATION" | grep "$HOSTNAME" echo "Checking Agents..." gcloud agent-registry agents list \ --project="$PROJECT_ID" \ --location="$LOCATION" | grep "$HOSTNAME"
Sostituisci quanto segue:
HOSTNAME: il nome host di destinazione che l'agente sta tentando di raggiungere, ad esempious-central1-aiplatform.mtls.googleapis.com.PROJECT_ID: l'ID progetto Google Cloud .REGION: la località delle risorse Agent Registry e Agent Gateway, ad esempious-central1.
Output 1: il nome host è già registrato
Se il nome host esiste in una voce del registro degli agenti, l'output è simile al seguente esempio:
Checking Endpoints... url: https://us-central1-aiplatform.mtls.googleapis.com Checking MCP Servers... Checking Agents...
Vai a Verifica le associazioni IAM sulla risorsa di destinazione per controllare se una policy per risorsa o a livello di registry concede l'accesso all'identità dell'agente.
Output 2: il nome host non esiste nel registry
Se il nome host non esiste nel registry, viene visualizzato un output simile al seguente esempio:
Checking Endpoints... Checking MCP Servers... Checking Agents...
Se prevedi di utilizzare policy per risorsa o a livello di registry, registra prima la destinazione in Agent Registry. Se utilizzi policy per gli endpoint non registrati, vai a Verifica le associazioni IAM sulla risorsa di destinazione.
Verifica le associazioni IAM sulla risorsa di destinazione
Assicurati che l'identità dell'agente o il set di entità disponga dell'autorizzazione iap.googleapis.com/resources.egressViaIAP (iap.resources.egressViaIAP nelle policy di autorizzazione V1 legacy) sulla destinazione.
Puoi configurare le associazioni delle policy in tre ambiti:
- A livello di registry: accesso a ogni agente, server MCP ed endpoint registrato nel registry.
- Per risorsa: accesso limitato. Nelle policy di autorizzazione V1 legacy, un'associazione per risorsa sostituisce l'associazione a livello di registry per quella risorsa specifica anziché unirsi a questa.
- Policy per gli endpoint non registrati: accesso a una lista consentita di domini con ambito di destinazioni non registrate in Agent Registry.
Controlla le UAP (iapPolicyVersion: "V2", consigliato)
Elenca le associazioni UAP collegate al progetto che ospita l'Agent Gateway:
gcloud iam policy-bindings list \ --project=PROJECT_ID \ --location=global \ --filter='target.resource="//cloudresourcemanager.googleapis.com/projects/PROJECT_ID"'
Esamina ogni UAP associato per verificarne le entità, le autorizzazioni (
iap.googleapis.com/resources.egressViaIAP) e le condizioni del Common Expression Language (CEL):gcloud iam access-policies describe POLICY_ID \ --project=PROJECT_ID \ --location=global
Sostituisci quanto segue:
PROJECT_ID: l'ID progetto in cui è stato eseguito il deployment di Agent Gateway.PROJECT_NUMBER: il numero del progetto in cui è stato eseguito il deployment di Agent Gateway.POLICY_ID: l'ID univoco della piattaforma UAP restituito dagcloud iam policy-bindings list.ORGANIZATION_ID: l'ID organizzazione Google Cloudse la policy è definita a livello di organizzazione.
Verifica quanto segue nelle regole della policy:
L'elenco
principalsinclude la Workload Identity dell'agente (principal://agents.global.org-...) o il set di entità del progetto (principalSet://agents.global.org-...).Le condizioni delle risorse registrate (
destination.agent_registry.endpoint.name,destination.agent_registry.mcp_server.nameodestination.agent_registry.agent.name) omettono una barra iniziale prima diprojects/.Le condizioni degli endpoint non registrati (
destination.is_registered == false) includono ogni variante di nome host standard, regionale e mTLS chiamata dall'SDK dell'agente indestination.unregistered.host in [...]e nessuna regolaDENYgenerale bloccadestination.is_registered == false.
Controlla le policy di autorizzazione V1 legacy (iapPolicyVersion: "V1")
Se l'estensione dell'autorizzazione del gateway utilizza iapPolicyVersion: "V1", utilizza uno dei seguenti comandi per verificare la presenza di associazioni roles/iap.egressor V1:
Per verificare la presenza di associazioni delle policy IAM a livello di registry, esegui il seguente comando:
curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -d '{}' \ -X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry:getIamPolicy" \ -H "Content-Type: application/json"Per verificare la presenza di associazioni delle policy IAM per endpoint, esegui il seguente comando:
export HOSTNAME=HOSTNAME ENDPOINT_ID=$(gcloud agent-registry endpoints list \ --project="PROJECT_ID" \ --location="REGION" \ --filter="interfaces.url:$HOSTNAME" \ --format="value(name.basename())") echo "ENDPOINT_ID=$ENDPOINT_ID" curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json" \ -d '{}' \ -X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry/endpoints/${ENDPOINT_ID}:getIamPolicy"
Sostituisci
HOSTNAMEcon il nome host della destinazione che l'agente sta tentando di raggiungere, ad esempious-central1-aiplatform.mtls.googleapis.com.Per verificare le associazioni delle policy IAM per server MCP, esegui il seguente comando:
export MCP_SERVER=MCP_SERVER MCP_SERVER_ID=$(gcloud agent-registry mcp-servers list \ --project="PROJECT_ID" \ --location="REGION" \ --filter="interfaces.url:$MCP_SERVER" \ --format="value(name.basename())") echo "MCP_SERVER_ID=$MCP_SERVER_ID" curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json" \ -d '{}' \ -X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry/mcpServers/${MCP_SERVER_ID}:getIamPolicy"
Sostituisci
MCP_SERVERcon l'URL del server MCP (ad esempiohttps://example-abc12345-uc.a.run.app/mcp).
Nelle informazioni sulle policy restituite, cerca un'associazione con l'autorizzazione iap.resources.egressViaIAP (roles/iap.egressor) che corrisponda all'identità o al set di entità dell'agente. Se l'output restituito contiene un campo "etag", ma nessuna associazione, non esiste alcuna policy IAM V1 su quella risorsa.
Se esiste un'associazione, ma include un condition, verifica che l'espressione CEL non escluda l'agente. Una condizione che filtra in base a un attributo che l'agente non ha potrebbe escludere l'agente senza avvisare.
Concedi le autorizzazioni in uscita mancanti
Se la destinazione di destinazione non ha un'associazione di norma di corrispondenza che concede l'autorizzazione in uscita all'identità dell'agente o al set di entità, concedi l'autorizzazione utilizzando una delle seguenti opzioni di policy:
- Policy a livello di registry (consigliata): configura una policy da agente a registry per concedere l'accesso a tutte le risorse registrate in Agent Registry.
- Policy per risorsa (server o endpoint MCP): registra il server MCP o registra l'endpoint in Agent Registry e crea una policy da agente a server MCP o una policy da agente a endpoint.
- Lista consentita di domini con ambito per endpoint non registrati: configura una policy per gli endpoint non registrati per concedere l'accesso a un elenco esplicito di nomi host senza registrare la risorsa.
Verifica l'ambito dell'associazione delle policy
Anche se una UAP IAM concede iap.resources.egressViaIAP per la risorsa di destinazione, la policy viene valutata solo se è associata al progetto o all'istanza Agent Gateway specifica che gestisce la richiesta:
- Binding del progetto: applicato da tutte le istanze di Agent Gateway nel progetto.
- Binding dell'istanza di Agent Gateway: applicato solo da quell'istanza specifica di Agent Gateway.
Per verificare quali policy sono associate al tuo progetto o alla tua istanza di Agent Gateway, esegui questo comando:
gcloud iam policy-bindings search-target-policy-bindings \
--project=PROJECT_ID \
--location=global \
--target=TARGET_RESOURCE
Sostituisci quanto segue:
PROJECT_ID: il tuo ID progetto Google Cloud .TARGET_RESOURCE: l'URI completo della risorsa del progetto (//cloudresourcemanager.googleapis.com/projects/PROJECT_ID) o dell'istanza Agent Gateway (//networkservices.googleapis.com/projects/PROJECT_ID/locations/LOCATION/agentGateways/GATEWAY_NAME). Per un target Agent Gateway, sostituisci quanto segue:LOCATION: la regione dell'istanza di Agent Gateway, ad esempious-central1.GATEWAY_NAME: il nome dell'istanza di Agent Gateway.
Per la risoluzione dei problemi dettagliata delle regole UAP, delle condizioni CEL e degli errori di associazione, consulta Risolvi i problemi relativi alle policy di accesso uniforme IAM.
Esamina la policy di autorizzazione e l'estensione
In questa sezione ci assicuriamo che esista una policy di autorizzazione che ha come target esplicito l'Agent Gateway associato all'agente.
Recupera i dettagli dell'estensione dell'autorizzazione associata al gateway e verifica che l'estensione che stai utilizzando sia configurata come previsto.
gcloud service-extensions authz-extensions describe AUTHORIZATION_EXTENSION_NAME \ --location=LOCATION \ --project=PROJECT_IDSostituisci AUTHORIZATION_EXTENSION_NAME con il nome dell'estensione associata al gateway. Se non conosci il nome dell'estensione, puoi andare alla pagina dei dettagli del gateway nella consoleGoogle Cloud Google Cloud e prendere nota del valore del campo Nome estensione in Service Extensions.
Verifica che una policy di autorizzazione abbia come target esplicito la risorsa gateway e rimandi alla stessa estensione dell'autorizzazione. Puoi andare alla pagina dei dettagli del gateway nella console Google Cloud Google Cloud e prendere nota del valore del campo Nome policy in Estensioni di servizio.
Se nessuna policy ha come target il gateway o se la mappatura tra gateway e policy non è corretta, l'estensione dell'autorizzazione non verrà eseguita.
Controlla le policy sul confine di accesso dell'entità
Le policy sul confine di accesso dell'entità hanno la precedenza sulle policy di autorizzazione IAM. Ciò significa che, anche se hai configurato correttamente tutte le associazioni IAM, una richiesta non andrà a buon fine se è attiva una policy Principal Access Boundary che esclude la risorsa di destinazione dall'ambito dell'agente.
Per elencare le policy a livello di organizzazione, esegui:
gcloud iam principal-access-boundary-policies list \ --organization="ORGANIZATION_ID" \ --location=global
Per trovare le policy associate al set di entità dell'agente, esegui:
gcloud iam policy-bindings search-target-policy-bindings \ --project="PROJECT_ID" \ --target="PRINCIPAL_SET"
Sostituisci quanto segue:
ORGANIZATION_ID: l'ID organizzazione Google Cloud.PROJECT_ID: l'ID progetto Google Cloud .PRINCIPAL_SET: l'insieme di entità dell'identità dell'agente.
Se esiste un'associazione, controlla il campo details.rules[].resources[] per verificare che la destinazione rientri nell'ambito dell'agente.
Testa le associazioni di entità e set di entità
Se le autorizzazioni funzionano in modo incoerente o non funzionano in modo imprevisto, il problema potrebbe riguardare il modo in cui è configurata l'identità di gruppo dell'agente (il set di entità). Le autorizzazioni basate su set di entità potrebbero non riuscire per i seguenti motivi:
- Ritardi di sincronizzazione: quando aggiungi un'identità a un set, l'aggiornamento e il riconoscimento del nuovo membro da parte di IAM possono richiedere alcuni minuti.
- Attributi mancanti: se l'appartenenza a un set di entità richiede determinati attributi, l'identità dell'agente deve contenere esattamente questi attributi (ad esempio, etichette di reparto o team). Se l'identità non dispone di questi attributi, l'agente potrebbe essere escluso dal gruppo senza preavviso.
Per verificare se il problema è l'appartenenza al gruppo, concedi le autorizzazioni direttamente all'agente specifico aggiungendo un'associazione principal:// diretta alla risorsa interessata. Se l'agente si connette correttamente con l'associazione diretta, la causa principale è probabilmente una mancata corrispondenza degli attributi o un ritardo di sincronizzazione con il set di entità.
Per risolvere il problema, verifica e correggi gli attributi di identità dell'agente o utilizza
associazioni principal:// dirette.
Passaggi successivi
Codelab: gestisci i workload degli agenti con Agent Platform
Scopri come gestire i workload degli agenti con Agent Gateway su Gemini Enterprise Agent Platform.