Autenticarsi utilizzando OAuth a tre vie con Auth Manager

Console

1. Nella console Cloud de Confiance , vai alla pagina Agent Registry.

   Vai ad Agent Registry

2. Fai clic sul nome dell'agente per cui vuoi creare un provider di autenticazione.
3. Fai clic su Identità.
4. Nella sezione Provider di autenticazione, fai clic su add Aggiungi provider di autenticazione.

5. Nel riquadro Aggiungi provider di autenticazione, inserisci un nome e una descrizione.

   Il nome può contenere solo lettere minuscole, numeri o trattini, non può terminare con un trattino e deve iniziare con una lettera minuscola.

6. Dall'elenco OAuth Type (Tipo di OAuth), seleziona OAuth (3 legged) (OAuth a tre vie) .
7. Fai clic su Crea e continua.
8. Per concedere all'identità dell'agente l'autorizzazione a utilizzare il provider di autenticazione, fai clic su Concedi accesso.

   Questo processo assegna automaticamente il ruolo Utente identità agente (roles/agentidentity.user) all'identità agente sulla risorsa del provider di autenticazione.

9. Copia l'URL di callback.
10. In una scheda separata, registra l'URL di callback nell'applicazione client OAuth di terze parti.
11. Nella sezione Credenziali del provider di autenticazione, inserisci le seguenti informazioni:
    • ID client
    • Client secret
    • URL del token
    • URL di autorizzazione
    • URI di continuazione predefinito: facoltativo. Inserisci un URI di reindirizzamento predefinito a cui reindirizzare gli utenti dopo che hanno concesso il consenso, se non viene fornito un URI di continuazione in fase di runtime.
12. Fai clic su Aggiungi configurazione provider.

Il provider di autenticazione appena creato viene visualizzato nell'elenco Provider di autenticazione.

gcloud CLI

1. Configura l'applicazione client OAuth per registrare il client e ottenere un ID client e un client secret. Specifica l'URI di reindirizzamento utilizzando il modello in quella sezione.

2. Crea il provider di autenticazione utilizzando le tue credenziali client:

   gcloud agent-identity auth-providers create AUTH_PROVIDER_NAME \
       --project="PROJECT_ID" \
       --location="LOCATION" \
       --three-legged-oauth-client-id="CLIENT_ID" \
       --three-legged-oauth-client-secret="CLIENT_SECRET" \
       --three-legged-oauth-authorization-url="AUTHORIZATION_URL" \
       --three-legged-oauth-token-url="TOKEN_URL" \
       --three-legged-oauth-default-continue-uri="DEFAULT_CONTINUE_URI"

   Sostituisci quanto segue:

   • AUTH_PROVIDER_NAME: il nome del tuo provider di autenticazione.
   • PROJECT_ID: l'ID progetto Cloud de Confiance .
   • LOCATION: la regione in cui viene creato il provider di autenticazione.
   • CLIENT_ID: l'ID client della tua applicazione client OAuth.
   • CLIENT_SECRET: il client secret della tua applicazione client OAuth.
   • AUTHORIZATION_URL: l'endpoint del server di autorizzazione a cui gli utenti vengono reindirizzati per concedere il consenso.
   • TOKEN_URL: l'endpoint di scambio dei token sul server di autorizzazione.
   • DEFAULT_CONTINUE_URI: (Facoltativo) L'URI di reindirizzamento predefinito a cui vengono indirizzati gli utenti dopo aver concesso il consenso, utilizzato se non viene fornito alcun URI di continuazione in fase di runtime.
3. Verifica che il tuo provider di autenticazione sia visualizzato nell'elenco e che il suo stato sia ENABLED:

   gcloud agent-identity auth-providers list \
      --project="PROJECT_ID" \
      --location="LOCATION"

4. Concedi le autorizzazioni di accesso per consentire all'agente e all'ambiente di sviluppo locale di recuperare le credenziali dal provider di autenticazione. Per consentire all'agente di cui è stato eseguito il deployment e al tuo account utente personale di accedere al provider di autenticazione, concedi il ruolo Utente identità agente (roles/agentidentity.user) alla risorsa del provider di autenticazione:

   1. Concedi l'accesso all'ID SPIFFE dell'agente di cui è stato eseguito il deployment (Agent Identity):

      gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
          --project="PROJECT_ID" \
          --location="LOCATION" \
          --role="roles/agentidentity.user" \
          --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"

   2. Concedi l'accesso al tuo account utente personale per lo sviluppo e i test locali (adk web):

      gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
          --project="PROJECT_ID" \
          --location="LOCATION" \
          --role="roles/agentidentity.user" \
          --member="user:USER_EMAIL"

Sostituisci quanto segue:

• PROJECT_ID: l'ID progetto Cloud de Confiance .
• LOCATION: la località in cui è stato eseguito il deployment del provider di autenticazione e dell'agente (ad esempio, us-west1).
• AUTH_PROVIDER_NAME: il nome del provider di autenticazione (ad esempio, bigquery-mcp-3lo-authprovider).
• AUTHORIZATION_URL: l'URL del server di autorizzazione (ad esempio, https://accounts.google.com/o/oauth2/v2/auth).
• TOKEN_URL: l'URL del server token (ad esempio https://oauth2.googleapis.com/token).
• CLIENT_ID: l'ID client OAuth generato dal servizio di terze parti.
• CLIENT_SECRET: il client secret OAuth generato dal servizio di terze parti.
• ORGANIZATION_ID: il tuo ID organizzazione Cloud de Confiance .
• PROJECT_NUMBER: il tuo numero di progetto Cloud de Confiance .
• ENGINE_ID: l'ID dell'agente del motore di ragionamento di cui è stato eseguito il deployment.
• USER_EMAIL: l'indirizzo email del tuo account utente personale.

REST

1. Configura l'applicazione client OAuth per registrare il client e ottenere un ID client e un client secret. Specifica l'URI di reindirizzamento utilizzando il modello in quella sezione.

2. Crea il provider di autenticazione:

   Il metodo authProviders.create dell'API Agent Identity crea un provider di autenticazione OAuth a tre vie in un progetto e in una località.

   Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

   • PROJECT_ID: l'ID progetto Cloud de Confiance . Gli ID progetto sono stringhe alfanumeriche, come my-project.
   • LOCATION: la località in cui è stato eseguito il deployment del provider di autenticazione e dell'agente (ad esempio, us-west1).
   • AUTH_PROVIDER_NAME: il nome del provider di autenticazione (ad esempio, bigquery-mcp-3lo-authprovider). Il nome può contenere solo lettere minuscole, numeri o trattini, non può terminare con un trattino e deve iniziare con una lettera minuscola.
   • CLIENT_ID: l'ID client OAuth che hai generato dal servizio di terze parti.
   • CLIENT_SECRET: il client secret OAuth che hai generato dal servizio di terze parti.
   • AUTHORIZATION_URL: L'URL del server di autorizzazione (ad esempio, https://accounts.google.com/o/oauth2/v2/auth).
   • TOKEN_URL: l'URL del server token (ad esempio, https://oauth2.googleapis.com/token).
   • DEFAULT_CONTINUE_URI: (Facoltativo) L'URI predefinito a cui reindirizzare gli utenti dopo che hanno concesso il consenso se non fornisci un URI di continuazione in fase di runtime.

   Metodo HTTP e URL:

   POST https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders?authProviderId=AUTH_PROVIDER_NAME

   Corpo JSON della richiesta:

   {
     "authProviderTypeParams": {
       "threeLeggedOauth": {
         "clientId": "CLIENT_ID",
         "clientSecret": "CLIENT_SECRET",
         "authorizationUrl": "AUTHORIZATION_URL",
         "tokenUrl": "TOKEN_URL",
         "defaultContinueUri": "DEFAULT_CONTINUE_URI"
       }
     }
   }
   

   Per inviare la richiesta, espandi una di queste opzioni:

   curl (Linux, macOS o Cloud Shell)

   Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders?authProviderId=AUTH_PROVIDER_NAME"

   PowerShell (Windows)

   Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders?authProviderId=AUTH_PROVIDER_NAME" | Select-Object -Expand Content

   Explorer API (browser)

   Copia il corpo della richiesta e apri la pagina di riferimento del metodo. Sul lato destro della pagina si apre il riquadro Explorer API. Puoi interagire con questo strumento per inviare richieste. Incolla il corpo della richiesta in questo strumento, compila gli altri campi obbligatori e fai clic su Esegui.

   Dovresti ricevere una risposta JSON simile alla seguente:

   {
     "name": "projects/my-project/locations/us-west1/authProviders/bigquery-mcp-3lo-authprovider",
     "createTime": "2026-04-03T21:15:41.367155Z",
     "updateTime": "2026-04-03T21:15:41.367155Z",
     "authProviderTypeParams": {
       "threeLeggedOauth": {
         "clientId": "my-oauth-client-id",
         "redirectUrl": "https://agentidentitycredentials.googleapis.com/v1/projects/my-project/locations/us-west1/authProviders/bigquery-mcp-3lo-authprovider/oauthcallback",
         "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth",
         "tokenUrl": "https://oauth2.googleapis.com/token",
         "defaultContinueUri": "http://localhost:8501/validateUserId"
       }
     },
     "state": "ENABLED"
   }
   

3. Per consentire all'agente di cui è stato eseguito il deployment e al tuo account utente personale di recuperare le credenziali dal provider di autenticazione, concedi il ruolo Agent Identity User (roles/agentidentity.user) sulla risorsa del provider di autenticazione:

   Il metodo authProviders.setIamPolicy dell'API Agent Identity imposta la policy di autorizzazione sulla risorsa del provider di autenticazione.

   Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

   • PROJECT_ID: l'ID progetto Cloud de Confiance . Gli ID progetto sono stringhe alfanumeriche, come my-project.
   • LOCATION: la località in cui è stato eseguito il deployment del provider di autenticazione e dell'agente (ad esempio, us-west1).
   • AUTH_PROVIDER_NAME: il nome del provider di autenticazione.
   • ORGANIZATION_ID: il tuo ID organizzazione Cloud de Confiance.
   • PROJECT_NUMBER: il numero di progetto Cloud de Confiance numerico del progetto in cui è stato eseguito il deployment dell'agente (ad esempio, 987654321098).
   • ENGINE_ID: l'ID dell'agente del motore di ragionamento di cui è stato eseguito il deployment.
   • USER_EMAIL: l'indirizzo email del tuo account utente personale.

   Metodo HTTP e URL:

   POST https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME:setIamPolicy

   Corpo JSON della richiesta:

   {
     "policy": {
       "bindings": [
         {
           "role": "roles/agentidentity.user",
           "members": [
             "principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID",
             "user:USER_EMAIL"
           ]
         }
       ]
     }
   }
   

   Per inviare la richiesta, espandi una di queste opzioni:

   curl (Linux, macOS o Cloud Shell)

   Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME:setIamPolicy"

   PowerShell (Windows)

   Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME:setIamPolicy" | Select-Object -Expand Content

   Explorer API (browser)

   Copia il corpo della richiesta e apri la pagina di riferimento del metodo. Sul lato destro della pagina si apre il riquadro Explorer API. Puoi interagire con questo strumento per inviare richieste. Incolla il corpo della richiesta in questo strumento, compila gli altri campi obbligatori e fai clic su Esegui.

   Dovresti ricevere una risposta JSON simile alla seguente:

   {
     "version": 1,
     "etag": "BwYKmjvelug=",
     "bindings": [
       {
         "role": "roles/agentidentity.user",
         "members": [
           "principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/987654321098/locations/us-west1/reasoningEngines/112233445566778899",
           "user:alex@example.com"
         ]
       }
     ]
   }
   

ADK

Fai riferimento al provider di autenticazione nel codice dell'agente utilizzando il set di strumenti MCP nell'ADK.

from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.auth.auth_tool import AuthConfig

# Register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is granted.
# Optional if default_continue_uri is configured on the auth provider.
CONTINUE_URI = "https://YOUR_FRONTEND_URL/validateUserId"

# Create auth provider scheme
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME",
    continue_uri=CONTINUE_URI
)

# Configure an MCP tool with the authentication scheme.
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://YOUR_MCP_SERVER_URL"),
    auth_scheme=auth_scheme,
)

# Initialize the agent with the authenticated tools.
agent = Agent(
    name="AGENT_NAME",
    model="MODEL_NAME (ex. gemini-2.5-flash)",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

Esempio: connessione a BigQuery MCP

L'esempio seguente mostra una configurazione agent.py che connette un agente al server MCP BigQuery:

import os
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.models import Gemini
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
import google.auth
from google.genai import types

_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

bigquery_mcp_auth_provider_id = "AUTH_PROVIDER_NAME"
bigquery_mcp_endpoint = os.environ.get(
    "BIGQUERY_MCP_ENDPOINT", "https://bigquery.googleapis.com/mcp"
)

# Register Cloud de Confiance auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# URI to redirect user to after consent is granted.
CONTINUE_URI = "http://127.0.0.1:8501/validateUserId"

bigquery_mcp_auth_scheme = GcpAuthProviderScheme(
    name=f"projects/{project_id}/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME",
    scopes=["https://www.googleapis.com/auth/bigquery"],
    continue_uri=CONTINUE_URI,
)

bigquery_mcp_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url=bigquery_mcp_endpoint),
    auth_scheme=bigquery_mcp_auth_scheme,
    errlog=None,
)

root_agent = Agent(
    name="root_agent",
    model=Gemini(
        model="gemini-2.5-flash",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction=(
        "You are a helpful AI assistant designed to provide accurate and useful"
        " information. You can also use your BigQuery MCP tools to look up"
        " BigQuery data."
    ),
    tools=[bigquery_mcp_tools],
)

app = App(
    root_agent=root_agent,
    name="AGENT_NAME",
)

ADK

Fai riferimento al provider di autenticazione nel codice dell'agente utilizzando uno strumento di funzione autenticato nell'ADK.

import httpx
from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_identity import GcpAuthProviderScheme
from google.adk.apps import App
from google.adk.auth.auth_credential import AuthCredential
from google.adk.auth.auth_tool import AuthConfig
from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool
from vertexai import agent_engines

# First, register Cloud de Confiance auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is completed.
CONTINUE_URI = "WEB_APP_VALIDATE_USER_URI"

# Create Auth Config
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME",
        continue_uri=CONTINUE_URI
    )
)

# Use the Auth Config in Authenticated Function Tool
spotify_search_track_tool = AuthenticatedFunctionTool(
    func=spotify_search_track, auth_config=spotify_auth_config
)

# Sample function tool
async def spotify_search_track(credential: AuthCredential, query: str) -> str | list:
    token = None
    if credential.http and credential.http.credentials:
        token = credential.http.credentials.token

    if not token:
        return "Error: No authentication token available."

    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.spotify.com/v1/search",
            headers={"Authorization": f"Bearer {token}"},
            params={"q": query, "type": "track", "limit": 1},
        )
        # Add your own logic here

agent = Agent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

app = App(
    name="APP_NAME",
    root_agent=agent,
)

vertex_app = agent_engines.AdkApp(app_name=app)

ADK

Fai riferimento al provider di autenticazione nel codice dell'agente utilizzando il set di strumenti MCP del registry degli agenti nell'ADK.

Non devi creare uno schema di autenticazione per questo flusso. Il binding in uscita del server MCP registra già quale provider di autenticazione utilizzare. Passa continue_uri per specificare dove reindirizzare l'utente dopo il consenso.

from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_registry import AgentRegistry

# First, register Cloud de Confiance auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is completed.
CONTINUE_URI="WEB_APP_VALIDATE_USER_URI"

# Set Agent Registry. LOCATION must be the same region as the auth provider.
registry = AgentRegistry(project_id="PROJECT_ID", location="LOCATION")

# The auth provider is resolved from the MCP server's outbound binding.
toolset = registry.get_mcp_toolset(
    mcp_server_name=(
        "projects/PROJECT_ID/locations/"
        "LOCATION/mcpServers/"
        "agentregistry-00000000-0000-0000-0000-000000000000"
    ),
    continue_uri=CONTINUE_URI,
)

agent = Agent(
    name="AGENT_NAME",
    model="MODEL_NAME",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

Chiama direttamente l'API

Se non utilizzi l'ADK, l'agente deve chiamare l'API agentidentitycredentials.retrieveCredentials per ottenere il token.

Poiché si tratta di un flusso OAuth in più passaggi, l'agente deve gestire il ciclo di vita dell'operazione:

1. Richiesta iniziale: l'agente chiama retrieveCredentials.
2. Consenso richiesto: se l'utente non ha concesso il consenso, l'API restituisce una risposta contenente il risultato uri_consent_required. Questo conterrà authorization_uri e un consent_nonce.
3. Reindirizzamento del frontend: l'applicazione deve reindirizzare l'utente a authorization_uri.
4. Completamento: dopo che l'utente ha concesso il consenso, chiama FinalizeCredentials utilizzando consent_nonce per completare il flusso e ottenere il token.

Server UI di esempio

Puoi scaricare ed eseguire un server UI di esempio completo che utilizza uvicorn. Prima di iniziare, assicurati di avere un account GitHub e di aver installato pip.

Per configurare ed eseguire il server UI di esempio, segui questi passaggi:

1. Clona il repository GitHub adk-python:

   git clone https://github.com/google/adk-python.git

2. Vai al repository e attiva un ambiente virtuale Python:

   cd adk-python
   python3 -m venv .venv
   source .venv/bin/activate

3. Vai alla directory del client UI di esempio:

   cd contributing/samples/integrations/gcp_auth/client

4. Installa le dipendenze del client:

   pip install -r requirements.txt

5. Prima di avviare il server, imposta la variabile di ambiente AGENT_PROJECT_DIR per specificare la directory in cui si trova il codice dell'agente. In caso contrario, l'applicazione cerca gli agenti nella cartella principale della directory del client per impostazione predefinita.

   Avvia il server UI di esempio utilizzando uvicorn. Assicurati che la porta corrisponda all'URI di reindirizzamento configurato nel client OAuth:

   export AGENT_PROJECT_DIR="/path/to/your/agent_project"
   uvicorn main:app --port 8501 --reload

6. Apri http://localhost:8501 nel browser. (Nota: devi utilizzare localhost e non 127.0.0.1, perché l'URL di reindirizzamento OAuth richiede specificamente il nome host localhost.) Specifica le impostazioni, fai clic su Salva e applica le impostazioni, quindi interagisci con l'agente.

Applicazione UI personalizzata

Per implementare queste funzionalità direttamente in un'applicazione UI personalizzata, segui questi passaggi:

• Gestisci il trigger di autorizzazione
• Implementa un endpoint di convalida degli utenti
• Riprendi la conversazione con l'agente

Gestisci il trigger di autorizzazione

Quando un agente ha bisogno del consenso dell'utente, restituisce una chiamata di funzione adk_request_credential. L'applicazione deve intercettare questa chiamata per avviare una finestra di dialogo o un reindirizzamento di autorizzazione dell'utente.

Gestisci il contesto della sessione registrando il consent_nonce fornito dal provider di autenticazione. Questo nonce è necessario per verificare l'utente durante la fase di convalida. Salva i valori auth_config e auth_request_function_call_id all'interno della sessione per facilitare la ripresa del flusso dopo che l'utente ha concesso il consenso.

if (fc := get_auth_request_function_call(event_data)):
    print("--> Authentication required by agent.")
    try:
        auth_config = get_auth_config(fc)
        auth_uri, consent_nonce = handle_adk_request_credential(
            auth_config, AUTH_PROVIDER_NAME, request.user_id
        )
        if auth_uri:
            event_data['popup_auth_uri'] = auth_uri
            fc_id = (
                fc.get('id') if isinstance(fc, dict)
                else getattr(fc, 'id', None)
            )
            event_data['auth_request_function_call_id'] = fc_id
            event_data['auth_config'] = auth_config.model_dump()

            # Store session state
            if session_id:
                consent_sessions[session_id] = {
                    "user_id": request.user_id,
                    "consent_nonce": consent_nonce
                }
    except Exception as e:
        print(f"Error handling adk_request_credential: {e}")
        # Optionally, add logic to inform the user about the error.

def handle_adk_request_credential(auth_config, auth_provider_name, user_id):
    ec = auth_config.exchanged_auth_credential
    if ec and ec.oauth2:
        oauth2 = ec.oauth2
        return oauth2.auth_uri, oauth2.nonce
    return None, None

Implementa un endpoint di convalida dell'utente

Implementa un endpoint di convalida sul tuo server web (lo stesso URI fornito come continue_uri durante la configurazione). Questo endpoint deve:

1. Ricevi user_id_validation_state, auth_provider_name e uuid come parametri di ricerca.
2. Recupera i valori user_id e consent_nonce dallo spazio di archiviazione della sessione. Se vengono eseguiti più flussi di autorizzazione contemporaneamente, utilizza uuid per trovare la sessione corretta.
3. Chiama l'API FinalizeCredentials del provider di autenticazione con questi parametri.
4. Chiudi la finestra di autorizzazione dopo aver ricevuto una risposta di operazione riuscita.

Esempio: endpoint di convalida FastAPI (main.py)

L'esempio seguente mostra un endpoint di convalida FastAPI completo che gestisce il callback OAuth e finalizza le credenziali utente:

@app.api_route("/validateUserId", methods=["GET"])
async def validate_user(request: Request):
    auth_provider_name = request.query_params.get("auth_provider_name")
    session_id = request.cookies.get("session_id")
    session = consent_sessions.get(session_id, {})

    payload = {
        "userId": session.get("user_id"),
        "userIdValidationState": request.query_params.get(
            "user_id_validation_state"
        ),
        "consentNonce": session.get("consent_nonce"),
    }

    base_url = "https://agentidentitycredentials.googleapis.com/v1"
    finalize_url = f"{base_url}/{auth_provider_name}/credentials:finalize"

    try:
        async with httpx.AsyncClient(timeout=30.0) as client:
            resp = await client.post(finalize_url, json=payload)
            resp.raise_for_status()
    except httpx.HTTPError as e:
        err_text = e.response.text if hasattr(e, "response") else str(e)
        status = e.response.status_code if hasattr(e, "response") else 500
        return HTMLResponse(err_text, status_code=status)

    return HTMLResponse("""
        <script>
            window.close();
        </script>
        <p>Success. You can close this window.</p>
    """)

Riprendi la conversazione con l'agente

Dopo che l'utente ha concesso il consenso e la finestra di autorizzazione si è chiusa, recupera i valori auth_config e auth_request_function_call_id dai dati della sessione. Per continuare la conversazione, includi questi dettagli in una nuova richiesta all'agente come function_response.

if (request.is_auth_resume and session.auth_request_function_call_id
    and session.auth_config):
    auth_content = types.Content(
        role='user',
        parts=[
            types.Part(
                function_response=types.FunctionResponse(
                    id=session.auth_request_function_call_id,
                    name='adk_request_credential',
                    response=session.auth_config
                )
            )
        ],
    )
    # Send message to agent
    async for event in agent.async_stream_query(
        user_id=request.user_id,
        message=auth_content,
        session_id=session_id,
    ):
        # ...

Agent CLI

Se utilizzi l'Agent Development Kit (ADK) e l'interfaccia a riga di comando dell'agente, segui questi passaggi per eseguire il deployment dell'agente con l'identità dell'agente abilitata:

1. Nella cartella dell'applicazione dell'agente, crea un file di configurazione denominato .agent_engine_config.json per abilitare l'identità dell'agente:

   echo '{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json

2. Esegui il deployment dell'agente in Agent Runtime su Gemini Enterprise Agent Platform:

   uv run adk deploy agent_engine AGENT_NAME \
       --project="PROJECT_ID" \
       --region="LOCATION"

   Sostituisci quanto segue:

   • AGENT_NAME: il nome della cartella dell'applicazione dell'agente (ad esempio, maps_agent).
   • PROJECT_ID: il tuo ID progetto Cloud de Confiance.
   • LOCATION: la regione supportata in cui vuoi eseguire il deployment dell'agente (ad esempio, us-west1).

SDK Python

Se esegui il deployment in modo programmatico utilizzando l'SDK Vertex AI per Python, utilizza il flag identity_type=AGENT_IDENTITY:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider

# Initialize the Vertex AI client with v1beta1 API for Agent Identity support
client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=dict(api_version="v1beta1")
)

# Register the auth provider in set_up() so that it runs in the deployed
# container. Use the proper wrapper class for your Agent Framework (for example, AdkApp).
class AuthenticatedAdkApp(AdkApp):
    def set_up(self):
        CredentialManager.register_auth_provider(GcpAuthProvider())
        super().set_up()

app = AuthenticatedAdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": [
            "google-cloud-aiplatform[agent_engines,adk]",
            "google-adk[agent-identity,mcp]>=2.7.1",
        ],
    },
)

Sostituisci quanto segue:

• PROJECT_ID: l'ID progetto Cloud de Confiance .
• LOCATION: la regione supportata in cui vuoi eseguire il deployment dell'agente (ad esempio, us-west1).