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

Autentica con una clave de API y el administrador de autenticación

Para permitir que tus agentes se autentiquen en herramientas externas, como las APIs de Google Maps o Weather, configura la autenticación de salida con proveedores de autenticación de claves de API en el administrador de autenticación de Agent Identity.

Los proveedores de autenticación de claves de API administran tus claves criptográficas. Esta capacidad elimina la necesidad de codificar claves de forma rígida en el código de tu agente o administrarlas de forma manual.

Flujo de trabajo de claves de API

Los proveedores de autenticación de claves de API usan la identidad del agente y no requieren el consentimiento del usuario. Google toma medidas para proteger la clave de API durante el almacenamiento. Cuando usas el Kit de desarrollo de agentes (ADK), recupera e inserta automáticamente la clave de API en los encabezados de invocación de la herramienta.

Antes de comenzar

Verifica que hayas elegido el método de autenticación correcto.
Habilita la API de Agent Identity Connector.
Roles necesarios para habilitar las APIs
Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.
Habilitar la API
Crea e implementa un agente.
Obtén una clave de API del servicio de terceros al que deseas conectarte.
Verifica que tengas los roles necesarios para completar esta tarea.

Roles obligatorios

Si quieres obtener los permisos que necesitas para crear y usar un proveedor de autenticación de claves de API, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto:

Para crear proveedores de autenticación:
- Administrador de IAM Connector (roles/iamconnectors.admin)
- Editor de IAM Connector (roles/iamconnectors.editor)
Para usar proveedores de autenticación:
- Usuario de IAM Connector (roles/iamconnectors.user)
- Usuario de Vertex AI (roles/aiplatform.user)
- Consumidor de Service Usage (roles/serviceusage.serviceUsageConsumer)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para crear y usar un proveedor de autenticación de claves de API. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para crear y usar un proveedor de autenticación de claves de API:

Para crear proveedores de autenticación: iamconnectors.connectors.create
Para usar proveedores de autenticación:
- iamconnectors.connectors.retrieveCredentials
- aiplatform.endpoints.predict
- aiplatform.sessions.create

También puedes obtener estos permisos con roles personalizados o otros roles predefinidos.

Obtén una clave de API del servicio de terceros

Antes de crear un proveedor de autenticación, obtén una clave de API del servicio de terceros al que deseas que se conecte tu agente.

Si te conectas a un servicio de terceros fuera de Google Cloud, obtén la clave de API del portal para desarrolladores de ese servicio y omite los pasos de esta sección.

Si te conectas a Google Cloud servicios (como Cloud Translation o Google Maps), puedes generar y configurar una clave de API con los siguientes pasos:

En la Google Cloud consola de, habilita los servicios de API necesarios para tu proyecto:
1. En la Google Cloud consola de, ve a la página APIs y servicios >Biblioteca.
  Ir a APIs y servicios >Biblioteca
2. Busca y habilita las APIs que usa tu agente, como la API de Cloud Translation o la API de Weather de Google Maps.
3. Copia la cadena de clave de API generada.
Configura tu clave de API:
1. En la Google Cloud consola de, ve a la página APIs y servicios >Credenciales.
  Ir a APIs y servicios >Credenciales
2. Haz clic en Crear credenciales >Clave de API.
3. En el diálogo Crear clave de API, haz lo siguiente:
  1. Ingresa un nombre único para tu clave de API.
  2. Para restringir la clave a las APIs específicas que habilitaste, selecciona esas APIs de la lista Seleccionar restricciones de API.
  3. Opcional: En la sección Restringe tu clave para reducir los riesgos de seguridad , selecciona un tipo de aplicación para restringir el acceso.
  4. Haz clic en Crear.
Valida tu clave de API enviando una solicitud de prueba al extremo del servicio.
- Para verificar una clave de API de Cloud Translation, ejecuta el siguiente comando:
```
curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-goog-api-key: YOUR_API_KEY" \
  -d '{"q": "Hello world", "target": "es"}' \
  "https://translation.googleapis.com/language/translate/v2"
```
  Reemplaza YOUR_API_KEY por la clave de API que generaste.
- Para verificar una clave de API de Google Maps Weather, ejecuta el siguiente comando:
```
curl -X GET \
  "https://weather.googleapis.com/v1/currentConditions:lookup?key=YOUR_API_KEY&location.latitude=37.4220&location.longitude=-122.0841"
```
  Reemplaza YOUR_API_KEY por la clave de API que generaste.
Si la clave de API es válida y está configurada correctamente, el servicio muestra los datos solicitados.

Crea un proveedor de autenticación de claves de API

Crea un proveedor de autenticación para definir la configuración y las credenciales de las aplicaciones de terceros.

Para crear un proveedor de autenticación de claves de API, usa la Google Cloud consola de o Google Cloud CLI.

Console

En la Google Cloud consola, ve a la página Registro de agentes.
Ir al registro de agentes
Haz clic en el nombre del agente para el que deseas crear un proveedor de autenticación.
Haz clic en Identidad.
En la sección Proveedores de autenticación, haz clic en Agregar proveedor de autenticación.
En el panel Agregar proveedor de autenticación, ingresa un nombre y una descripción.

El nombre solo puede contener letras minúsculas, números o guiones, no puede terminar con un guion y debe comenzar con una letra minúscula.
En la lista Tipo de OAuth, selecciona Clave de API .
Haz clic en Crear y continuar.
Para otorgar permiso de identidad de agente para usar el proveedor de autenticación, haz clic en Otorgar acceso.
Esto asigna automáticamente el rol de Usuario de conector (roles/iamconnectors.user) a la identidad del agente en el recurso del proveedor de autenticación.
En la sección Credenciales del proveedor de autenticación, ingresa la clave de API.
Haz clic en Agregar configuración del proveedor.

El proveedor de autenticación recién creado aparecerá en la lista Proveedores de autenticación.

Google Cloud CLI

Crea el proveedor de autenticación:

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

Verifica que tu proveedor de autenticación aparezca en la lista y que su estado sea ENABLED:

gcloud alpha agent-identity connectors list \
   --project="PROJECT_ID" \
   --location="LOCATION"

Otorga permisos de acceso para permitir que tu agente y el entorno de desarrollo local recuperen credenciales del proveedor de autenticación. Para permitir que tu agente implementado y tu cuenta de usuario personal accedan al proveedor de autenticación, otorga el rol de Usuario de conector (roles/iamconnectors.user) en el recurso del proveedor de autenticación:

Otorga acceso al ID de SPIFFE de tu agente implementado (Agent Identity):

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

Otorga acceso a tu cuenta de usuario personal para el desarrollo y las pruebas locales (adk web):

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

Reemplaza lo siguiente:

PROJECT_ID: Es el ID del Google Cloud proyecto de.
LOCATION: Es la ubicación en la que se implementan tu proveedor de autenticación y tu agente (por ejemplo, us-west1).
AUTH_PROVIDER_NAME: Es el nombre de tu proveedor de autenticación (por ejemplo, bigquery-mcp-3lo-authprovider).
AUTHORIZATION_URL: Es la URL del servidor de autorización (por ejemplo, https://accounts.google.com/o/oauth2/v2/auth).
TOKEN_URL: Es la URL del servidor de tokens (por ejemplo, https://oauth2.googleapis.com/token).
CLIENT_ID: Es el ID de cliente de OAuth que generaste desde el servicio de terceros.
CLIENT_SECRET: Es el secreto del cliente de OAuth que generaste desde el servicio de terceros.
ORGANIZATION_ID: Es el ID de tu Google Cloud organización.
PROJECT_NUMBER: Es el número de tu Google Cloud proyecto.
ENGINE_ID: Es el ID de tu agente de motor de razonamiento implementado.
USER_EMAIL: Es la dirección de correo electrónico de tu cuenta de usuario personal.

Realiza la autenticación en el código de tu agente

Para autenticar tu agente, puedes usar el ADK.

ADK

Haz referencia al proveedor de autenticación en el código de tu agente con el conjunto de herramientas MCP en el 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="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

Ejemplo: Conéctate a Google Maps MCP

En el siguiente ejemplo, se muestra una configuración de agent.py que conecta un agente a un servidor MCP de 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"

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

maps_auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/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

Haz referencia al proveedor de autenticación en el código de tu agente con una herramienta de función autenticada en el 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="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)

Ejemplo: Conéctate a la API de Weather de Google Maps

En el siguiente ejemplo, se muestra una configuración de agent.py que conecta un agente a la API de Weather de Google Maps con una herramienta de función autenticada:

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"

# Register GCP 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/connectors/AUTH_PROVIDER_NAME"
    )
)

async def get_weather(credential: AuthCredential, latitude: float, longitude: float) -> str | dict:
    """Gets the current weather conditions for a location using latitude and longitude."""
    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

Haz referencia al proveedor de autenticación en el código de tu agente con el conjunto de herramientas MCP del registro de agentes en el 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="AGENT_NAME",
    model="MODEL_NAME",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

Implementa el agente

Cuando implementes tu agente en Google Cloud, asegúrate de que Agent Identity esté habilitado.

Si realizas la implementación en Agent Runtime en Gemini Enterprise Agent Platform , usa la identity_type=AGENT_IDENTITY marca:

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]"],
    },
)