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

S'authentifier à l'aide d'une clé API avec le gestionnaire d'authentification

Pour permettre à vos agents de s'authentifier auprès d'outils externes tels que les API Google Maps ou Weather, configurez l'authentification sortante à l'aide de fournisseurs d'authentification par clé API dans le gestionnaire d'authentification de l'identité de l'agent.

Les fournisseurs d'authentification par clé API gèrent vos clés cryptographiques pour vous. Cette fonctionnalité vous évite de coder en dur les clés dans le code de votre agent ou de les gérer manuellement.

Workflow des clés API

Les fournisseurs d'authentification par clé API utilisent l'identité de l'agent et ne nécessitent pas le consentement de l'utilisateur. Google prend des mesures pour sécuriser la clé API lors du stockage. Lorsque vous utilisez l'Agent Development Kit (ADK), il récupère et injecte automatiquement la clé API dans les en-têtes d'appel d'outil.

Avant de commencer

Vérifiez que vous avez choisi la bonne méthode d'authentification.
Activez l'API Agent Identity.
Rôles requis pour activer les API
Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.
Activer l'API
Créez et déployez un agent.
Obtenez une clé API auprès du service tiers auquel vous souhaitez vous connecter.
Vérifiez que vous disposez des rôles requis pour effectuer cette tâche.

Rôles requis

Pour obtenir les autorisations nécessaires pour créer et utiliser un fournisseur d'authentification par clé API, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le projet :

Pour créer des fournisseurs d'authentification :
- Administrateur de l'identité de l'agent (roles/agentidentity.admin)
- Éditeur d'identité de l'agent (roles/agentidentity.editor)
Pour utiliser les fournisseurs d'authentification :
- Utilisateur de l'identité de l'agent (roles/agentidentity.user)
- Utilisateur Vertex AI (roles/aiplatform.user)
- Consommateur Service Usage (roles/serviceusage.serviceUsageConsumer)

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour créer et utiliser un fournisseur d'authentification par clé API. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Vous devez disposer des autorisations suivantes pour créer et utiliser un fournisseur d'authentification par clé API :

Pour créer des fournisseurs d'authentification : agentidentity.authProviders.create
Pour utiliser les fournisseurs d'authentification :
- agentidentity.authProviders.retrieveCredentials
- aiplatform.endpoints.predict
- aiplatform.sessions.create

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Obtenez une clé API auprès du service tiers.

Avant de créer un fournisseur d'authentification, obtenez une clé API auprès du service tiers auquel vous souhaitez que votre agent se connecte.

Si vous vous connectez à un service tiers en dehors de Google Cloud, obtenez la clé API à partir du portail des développeurs de ce service et ignorez les étapes de cette section.

Si vous vous connectez à des services Google Cloud (tels que Cloud Translation ou Google Maps), vous pouvez générer et configurer une clé API en procédant comme suit :

Dans la console Google Cloud , activez les services d'API requis pour votre projet :
1. Dans la console Google Cloud , accédez à la page API et services >Bibliothèque.
  Accédez à API et services >Bibliothèque
2. Recherchez et activez les API utilisées par votre agent, comme l'API Cloud Translation ou l'API Google Maps Weather.
3. Copiez la chaîne de clé API générée.
Configurez votre clé API :
1. Dans la console Google Cloud , accédez à la page API et services >Identifiants.
  Accéder à API et services > Identifiants
2. Cliquez sur Créer des identifiants> Clé API.
3. Dans la boîte de dialogue Créer une clé API, procédez comme suit :
  1. Saisissez un nom unique pour votre clé API.
  2. Pour limiter la clé aux API spécifiques que vous avez activées, sélectionnez-les dans la liste Sélectionner des restrictions d'API.
  3. Facultatif : Dans la section Restreindre l'utilisation de votre clé pour réduire les risques de sécurité, sélectionnez un type d'application pour restreindre l'accès.
  4. Cliquez sur Créer.
Validez votre clé API en envoyant une requête de test au point de terminaison du service.
- Pour valider une clé API Cloud Translation, exécutez la commande suivante :
```
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"
```
  Remplacez YOUR_API_KEY par la clé API que vous avez générée.
- Pour valider une clé API Google Maps Weather, exécutez la commande suivante :
```
curl -X GET \
  "https://weather.googleapis.com/v1/currentConditions:lookup?key=YOUR_API_KEY&location.latitude=37.4220&location.longitude=-122.0841"
```
  Remplacez YOUR_API_KEY par la clé API que vous avez générée.
Si la clé API est valide et correctement configurée, le service renvoie les données demandées.

Créer un fournisseur d'authentification par clé API

Créez un fournisseur d'authentification pour définir la configuration et les identifiants des applications tierces.

S'authentifier dans le code de votre agent

Pour authentifier votre agent, vous pouvez utiliser l'ADK.

ADK

Faites référence au fournisseur d'authentification dans le code de votre agent à l'aide de l'ensemble d'outils MCP dans l'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 Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# Create Google Cloud 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 = LlmAgent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

Exemple : Se connecter au MCP Google Maps

L'exemple suivant illustre une configuration agent.py qui connecte un agent à un serveur MCP 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 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

Référencez le fournisseur d'authentification dans le code de votre agent à l'aide d'un outil de fonction authentifié dans l'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
# 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 = 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)

Exemple : se connecter à l'API Weather de Google Maps

L'exemple suivant illustre une configuration agent.py qui connecte un agent à l'API Google Maps Weather à l'aide d'un outil de fonction authentifié :

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

Référencez le fournisseur d'authentification dans le code de votre agent à l'aide de l'ensemble d'outils MCP du registre d'agents dans l'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
# 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"
)

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

Déployer l'agent

Lorsque vous déployez votre agent sur Google Cloud, assurez-vous que l'identité de l'agent est activée.

Si vous déployez sur Agent Runtime sur Gemini Enterprise Agent Platform , utilisez l'indicateur 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]"],
    },
)