Autenticarsi utilizzando la chiave API 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 Tipo OAuth, seleziona Chiave API .
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. Nella sezione Credenziali del provider di autenticazione, inserisci la Chiave API.
10. Fai clic su Aggiungi configurazione provider.

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

gcloud CLI

1. Crea il provider di autenticazione:

   gcloud agent-identity auth-providers create AUTH_PROVIDER_NAME \
       --project="PROJECT_ID" \
       --location="LOCATION" \
       --api-key="API_KEY"

2. 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"

3. 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, maps-api-key-authprovider).
• API_KEY: la chiave API generata 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. Crea il provider di autenticazione:

   Il metodo authProviders.create dell'API Agent Identity crea un provider di autenticazione con chiave API 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 maps-api-key-authprovider). Il nome può contenere solo lettere minuscole, numeri o trattini, non può terminare con un trattino e deve iniziare con una lettera minuscola.
   • API_KEY: la chiave API generata dal servizio di terze parti.

   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": {
       "apiKey": {
         "apiKey": "API_KEY"
       }
     }
   }
   

   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/maps-api-key-authprovider",
     "createTime": "2026-04-03T21:15:41.367155Z",
     "updateTime": "2026-04-03T21:15:41.367155Z",
     "authProviderTypeParams": {
       "apiKey": {}
     },
     "state": "ENABLED"
   }
   

2. 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 Cloud de Confiance auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# Create Cloud de Confiance 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"
)

# 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="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

Esempio: connessione all'MCP di Google Maps

L'esempio seguente mostra una configurazione agent.py che connette un agente a un server MCP di Google Maps:

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

os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
os.environ["GOOGLE_API_USE_CLIENT_CERTIFICATE"] = "false"

# Register Google Cloud auth provider for Agent Identity Credentials service
CredentialManager.register_auth_provider(GcpAuthProvider())

maps_auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
)

maps_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://mapstools.googleapis.com/mcp"),
    auth_scheme=maps_auth_scheme,
    errlog=None,
)

root_agent = Agent(
    name="root_agent",
    model=Gemini(model="gemini-2.5-flash"),
    instruction=(
        "You are a helpful AI assistant designed to provide accurate and useful "
        "information. You can also use your Google Maps tools to look up "
        "locations and directions."
    ),
    tools=[maps_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())

# Create Auth Config
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
    )
)

# 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)

Esempio: connessione all'API Weather di Google Maps

L'esempio seguente mostra una configurazione agent.py che connette un agente all'API Google Maps Weather utilizzando uno strumento di funzione autenticato:

import os
import httpx
from google.adk.agents import Agent
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.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.models import Gemini
from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool

os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
os.environ["GOOGLE_API_USE_CLIENT_CERTIFICATE"] = "false"

# Register Google Cloud auth provider for Agent Identity Credentials service
CredentialManager.register_auth_provider(GcpAuthProvider())

weather_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
    )
)

async def get_weather(credential: AuthCredential, latitude: float, longitude: float) -> str | dict:
    """Gets current weather conditions for a location."""
    api_key = None
    if http := credential.http:
        if http.additional_headers and "X-GOOG-API-KEY" in http.additional_headers:
            api_key = http.additional_headers["X-GOOG-API-KEY"]
        elif http.credentials and http.credentials.token:
            api_key = http.credentials.token

    if not api_key:
        return "Error: No API key available from the auth provider."

    params = {"location.latitude": latitude, "location.longitude": longitude, "key": api_key}
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://weather.googleapis.com/v1/currentConditions:lookup",
            params=params,
        )
        if response.status_code != 200:
            return f"Error from Weather API: {response.status_code} - {response.text}"
        return response.json()

get_weather_tool = AuthenticatedFunctionTool(
    func=get_weather, auth_config=weather_auth_config
)

root_agent = Agent(
    name="root_agent",
    model=Gemini(model="gemini-2.5-flash"),
    instruction=(
        "You are a helpful AI assistant. You will use your weather tool to "
        "look up current conditions."
    ),
    tools=[get_weather_tool],
)

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

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.

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())

# 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"
    ),
)

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

  

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).