Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Autenticarsi utilizzando la chiave API con Auth Manager

Per consentire agli agenti di autenticarsi a strumenti esterni come le API Google Maps o Meteo, configura l'autenticazione in uscita utilizzando i provider di autenticazione con chiave API in Gestore autenticazione identità agente.

I provider di autenticazione con chiave API gestiscono le chiavi di crittografia per te. Questa funzionalità elimina la necessità di codificare le chiavi nel codice dell'agente o di gestirle manualmente.

Flusso di lavoro della chiave API

I provider di autenticazione con chiave API utilizzano l'identità dell'agente e non richiedono il consenso dell'utente. Google adotta misure per proteggere la chiave API durante l'archiviazione. Quando utilizzi Agent Development Kit (ADK), recupera e inserisce automaticamente la chiave API nelle intestazioni di chiamata dello strumento.

Prima di iniziare

Verifica di aver scelto il metodo di autenticazione corretto.
Abilita l'API del connettore di identità dell'agente.
Ruoli necessari per abilitare le API
Per abilitare le API, devi disporre del ruolo IAM Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.
Abilitare l'API
Crea ed esegui il deployment di un agente.
Ottieni la chiave API dal servizio di terze parti a cui vuoi connetterti.
Verifica di disporre dei ruoli necessari per completare questa attività.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare e utilizzare un provider di autenticazione con chiave API, chiedi all'amministratore di concederti i seguenti ruoli IAM per il progetto:

Per creare provider di autenticazione:
- Amministratore connettore IAM (roles/iamconnectors.admin)
- Editor connettore IAM (roles/iamconnectors.editor)
Per utilizzare i provider di autenticazione:
- Utente connettore IAM (roles/iamconnectors.user)
- Accesso predefinito agente (roles/aiplatform.agentDefaultAccess)
- Editor contesto agente (roles/aiplatform.agentContextEditor)
- Utente Vertex AI (roles/aiplatform.user)
- Consumer Service Usage (roles/serviceusage.serviceUsageConsumer)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per creare e utilizzare un provider di autenticazione con chiave API. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per creare e utilizzare un provider di autenticazione con chiave API sono necessarie le seguenti autorizzazioni:

Per creare provider di autenticazione: iamconnectors.connectors.create
Per utilizzare i provider di autenticazione:
- iamconnectors.connectors.retrieveCredentials
- aiplatform.endpoints.predict
- aiplatform.sessions.create

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Creare un provider di autenticazione con chiave API

Crea un provider di autenticazione per definire la configurazione e le credenziali per le applicazioni di terze parti.

Per creare un provider di autenticazione con chiave API, utilizza la Google Cloud console o Google Cloud CLI.

Console

Nella Google Cloud console, vai alla pagina Registro agenti.
Vai al registro agenti
Fai clic sul nome dell'agente per cui vuoi creare un provider di autenticazione.
Fai clic su Identità.
Nella sezione Provider di autenticazione, fai clic su Aggiungi provider di autenticazione.
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.
Nell'elenco Tipo OAuth, seleziona Chiave API .
Fai clic su Crea e continua.
Per concedere all'identità dell'agente l'autorizzazione a utilizzare il provider di autenticazione, fai clic su Concedi accesso.
In questo modo, il ruolo Utente connettore (roles/iamconnectors.user) viene assegnato automaticamente all'identità dell'agente nella risorsa del provider di autenticazione.
Nella sezione Credenziali del provider di autenticazione, inserisci la chiave API.
Fai clic su Aggiungi configurazione del provider.

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

Google Cloud CLI

Crea il provider di autenticazione:

gcloud alpha agent-identity connectors create AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --api-key="API_KEY"

Per concedere all'identità dell'agente l'autorizzazione a utilizzare i provider di autenticazione, aggiorna il criterio di autorizzazione IAM per il progetto o il provider di autenticazione specifico e assegna il ruolo Utente connettore (roles/iamconnectors.user) all'entità agente.

L'identità dell'agente si basa sul formato ID SPIFFE standard del settore. Nei criteri di autorizzazione IAM, le identità degli agenti vengono indicate utilizzando gli identificatori di entità.
A livello di progetto (gcloud)

La concessione del ruolo a livello di progetto consente all'agente di utilizzare qualsiasi provider di autenticazione nel progetto.
- Per concedere a un singolo agente l'accesso ai provider di autenticazione in un progetto, esegui questo comando:
  gcloud projects add-iam-policy-binding PROJECT_ID \ --role='roles/iamconnectors.user' \ --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"
- Per concedere a tutti gli agenti di un progetto l'accesso ai provider di autenticazione, esegui il seguente comando:
  gcloud projects add-iam-policy-binding PROJECT_ID \ --role='roles/iamconnectors.user' \ --member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER"
A livello di connettore (curl)

Per concedere a un singolo agente l'accesso a un provider di autenticazione specifico, utilizza l' setIamPolicy API. Questo comando sovrascrive qualsiasi criterio di autorizzazione esistente sulla risorsa.
```
curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
  "policy": {
    "bindings": [
      {
        "role": "roles/iamconnectors.user",
        "members": ["principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"]
      }
    ]
  }
}' \
    "https://iamconnectors.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME:setIamPolicy"
```
Sostituisci quanto segue:
- PROJECT_ID: l' Google Cloud ID progetto.
- AUTH_PROVIDER_NAME: il nome del provider di autenticazione.
- ORGANIZATION_ID: l' Google Cloud ID organizzazione.
- PROJECT_NUMBER: il Google Cloud numero del progetto.
- LOCATION: la località dell'agente (ad esempio, us-central1).
- ENGINE_ID: l'ID del motore di ragionamento.

Autenticarsi nel codice dell'agente

Per autenticare l'agente, puoi utilizzare ADK.

ADK

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

from google.adk.agents.llm_agent import LlmAgent
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 the Google Cloud auth provider so the CredentialManager can use it.
CredentialManager.register_auth_provider(GcpAuthProvider())

# Create the Google Cloud auth provider scheme using the auth provider's full resource name.
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/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 = LlmAgent(
    name="YOUR_AGENT_NAME",
    model="gemini-2.0-flash",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[toolset],
)

ADK

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

import httpx
from google.adk.agents.llm_agent import LlmAgent
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 Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# Create Auth Config
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/connectors/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 = LlmAgent(
    name="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

app = App(
    name="YOUR_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 registro agenti in ADK.

from google.adk.agents.llm_agent import LlmAgent
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.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
from google.adk.integrations.agent_registry import AgentRegistry

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

# Create Google Cloud auth provider scheme by providing Auth Provider full resource name
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME"
)

# Set Agent Registry
registry = AgentRegistry(project_id="PROJECT_ID", location="global")

toolset = registry.get_mcp_toolset(mcp_server_name="projects/PROJECT_ID/locations/global/mcpServers/agentregistry-00000000-0000-0000-0000-000000000000", auth_scheme=auth_scheme)

# Example MCP tool
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="MCP_URL"),
    auth_scheme=auth_scheme,
)

agent = LlmAgent(
    name="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[toolset],
)

Eseguire il deployment dell'agente

Quando esegui il deployment dell'agente in Google Cloud, assicurati che l'identità dell'agente sia abilitata.

Se esegui il deployment in Agent Runtime, utilizza il flag identity_type=AGENT_IDENTITY:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

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

# Use the proper wrapper class for your Agent Framework (e.g., AdkApp)
app = AdkApp(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]"],
    },
)