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 saliente 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 la clave de API del servicio de terceros al que deseas conectarte.
Verifica que tengas los roles necesarios para completar esta tarea.

Roles obligatorios

Para 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)
- Acceso predeterminado del agente (roles/aiplatform.agentDefaultAccess)
- Editor de contexto del agente (roles/aiplatform.agentContextEditor)
- 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.

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 o Google Cloud CLI.

Console

En la Google Cloud consola, ve a la página Agent Registry.
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 Identity.
En la sección Auth Providers, 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 del agente para usar el proveedor de autenticación, haz clic en Otorgar acceso.
Esto asigna automáticamente el rol Usuario de Connector (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 \
    --location="LOCATION" \
    --api-key="API_KEY"

Para otorgar permiso de identidad del agente para usar proveedores de autenticación, actualiza la política de permisos de IAM para el proyecto o el proveedor de autenticación específico y otorga el rol Usuario de Connector (roles/iamconnectors.user) a la entidad del agente.

Agent Identity se basa en el formato de ID SPIFFE estándar de la industria. En las políticas de permisos de IAM, se hace referencia a las identidades de los agentes con identificadores principales.
Nivel de proyecto (gcloud)

Si otorgas el rol a nivel de proyecto, el agente podrá usar cualquier proveedor de autenticación en ese proyecto.
- Para otorgar acceso a un solo agente a los proveedores de autenticación en un proyecto, ejecuta el siguiente 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"
- Para otorgar acceso a todos los agentes de un proyecto a los proveedores de autenticación, ejecuta el siguiente 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"
Nivel de conector (curl)

Para otorgar acceso a un solo agente a un proveedor de autenticación específico, usa la setIamPolicy API. Este comando reemplaza cualquier política de permisos existente en el recurso.
```
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"
```
Reemplaza lo siguiente:
- PROJECT_ID: Es el ID del Google Cloud proyecto.
- AUTH_PROVIDER_NAME: Es el nombre del proveedor de autenticación.
- ORGANIZATION_ID: Es el ID de la organización de Google Cloud .
- PROJECT_NUMBER: Es el número del proyecto de Google Cloud .
- LOCATION: Es la ubicación de tu agente (por ejemplo, us-central1).
- ENGINE_ID: Es el ID de tu motor de razonamiento.

Realiza la autenticación en el código del 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 del 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="YOUR_AGENT_NAME",
    model="gemini-2.0-flash",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[toolset],
)

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="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

Haz referencia al proveedor de autenticación en el código de tu agente con el conjunto de herramientas del 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="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_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 el entorno de ejecución del agente, usa la marca 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]"],
    },
)