Configurer les fonctionnalités de la plate-forme d'agent pour Cloud Run

Les fonctionnalités de Gemini Enterprise Agent Platform telles qu' Agent Identity et Agent Registry offrent des fonctionnalités intégrées pour créer, déployer et gérer des agents IA, des serveurs MCP (Model Context Protocol) et des outils. En activant ces fonctionnalités pour vos ressources Cloud Run, vous pouvez profiter des identités gérées par le système et de l'enregistrement automatique pour simplifier la découverte et la sécurité de vos charges de travail d'agent.

Ce guide explique comment :

Cloud Run est compatible avec les fonctionnalités suivantes d'Agent Platform :

  • Agent Identity : attribue une identité unique et cryptographiquement vérifiable à votre charge de travail, ce qui permet d'établir des connexions sécurisées à d'autres agents, outils et API Google Cloud.
  • Agent Registry : enregistre automatiquement vos agents et outils pour les rendre détectables par d'autres développeurs et agents de votre organisation.

Avant de commencer

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Installez la Google Cloud CLI.

  4. Configurez la gcloud CLI afin d'utiliser votre identité fédérée.

    Pour en savoir plus, consultez Se connecter à la gcloud CLI avec votre identité fédérée.

  5. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    gcloud init

  6. Activez les API Cloud Run Admin, Identity and Access Management, Agent Registry et App Hub.

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation via le rôle Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

    Activer les API

  7. Assurez-vous d'avoir configuré Agent Registry dans votre projet ou votre organisation.
  8. Installez et initialisez la gcloud CLI.
  9. Mettez à jour les composants : 
    gcloud components update
  10. Consultez la page des tarifs de Cloud Run pour connaître les prix du processeur, de la mémoire et de la sortie réseau. La taille totale du disque provisionné et la durée de vie de l'instance qui l'utilise contribuent à votre coût.

Rôles requis

Pour obtenir les autorisations nécessaires pour configurer les fonctionnalités d'Agent Platform, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

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

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

Cas d'utilisation

Utilisez les fonctionnalités d'Agent Platform avec Cloud Run dans les scénarios suivants :

  • Authentifiez votre agent auprès d'autres agents, outils et Google Cloud API à l'aide d'une identité unique gérée par le système et liée à son cycle de vie.
  • Activez la découverte automatique des agents et des serveurs MCP dans l'Agent Registry de votre organisation.
  • Utilisez Identity-Aware Proxy comme stratégie d'authentification pour sécuriser les serveurs MCP.

Comprendre les types fonctionnels et d'identité

Vous configurez les fonctionnalités d'Agent Platform en définissant des propriétés fonctionnelles et d'identité sur vos ressources Cloud Run.

Ces deux propriétés contrôlent l'enregistrement et l'identification d'une charge de travail :

  • Type fonctionnel : déclare l'objectif principal de la charge de travail. Une fois défini, cette propriété ne peut pas être modifiée ni supprimée. Vous attribuez à votre charge de travail l'un des types fonctionnels suivants :
    • agent : désigne la charge de travail comme un agent IA. Les charges de travail de ce type doivent utiliser le type agent-identity.
    • mcp-server : désigne la charge de travail comme un serveur MCP géré par l'utilisateur. Ce type peut utiliser n'importe quel type d'identité compatible.
  • Type d'identité : spécifie le type d'identité attribué à la charge de travail. Une fois défini, cette propriété ne peut pas être modifiée ni supprimée. Vous attribuez à votre charge de travail l'un des types d'identité suivants :
    • agent-identity: attribue une identité d'agent gérée par le système et conçue pour les agents. Lorsque vous effectuez un déploiement avec agent-identity, Agent Platform active les certificats d'identité par défaut. Pour désactiver cette option, mettez à jour votre service avec l' --no-identity-certificate indicateur ou définissez l' run.googleapis.com/identity-certificate-enabled: "false" annotation. Suivez le guide pour vous authentifier auprès des outils et des ressources pour les agents agissant de leur propre autorité ou au nom des utilisateurs finaux. Pour comprendre les concepts de base et les avantages en termes de sécurité des identités d'agent gérées par le système, découvrez Agent Identity.
    • service-account: utilise un compte de service Google Cloud standard.

Comportement de la configuration

Le comportement des propriétés fonctionnelles et d'identité dépend de la combinaison que vous choisissez :

Type fonctionnel Type d'identité Comportement observé
agent agent-identity La charge de travail est enregistrée en tant qu'agent dans Agent Registry et une identité d'agent gérée par le système lui est attribuée.
agent Autre ou non spécifié Erreur. Les charges de travail avec functional-type=agent doivent utiliser identity-type=agent-identity.
mcp-server agent-identity, service-account ou non spécifié La charge de travail est enregistrée en tant que serveur MCP (/mcpServers) dans Agent Registry. Si elle n'est pas spécifiée, une identité de compte de service est utilisée par défaut.
Non spécifié service-account La charge de travail s'exécute en tant que service ou tâche Cloud Run standard.

Configurer des fonctionnalités sur les services et les tâches

Vous configurez les fonctionnalités d'Agent Platform sur vos services et tâches Cloud Run à l'aide de la Google Cloud CLI.

Services

  • Pour déployer un agent, spécifiez --functional-type=agent et --identity-type=agent-identity :

    gcloud beta run deploy SERVICE_NAME \
    --image=IMAGE_URL \
    --functional-type=agent \
    --identity-type=agent-identity

    Remplacez les éléments suivants :

    • SERVICE_NAME: nom de votre service Cloud Run.
    • IMAGE_URL: référence à l'image de conteneur, par exemple us-docker.pkg.dev/cloudrun/container/hello:latest. Si vous utilisez Artifact Registry, le dépôt REPO_NAME doit déjà être créé. L'URL suit le format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

  • Pour mettre à jour un service existant afin qu'il utilise Agent Identity :

    gcloud beta run services update SERVICE_NAME \
    --functional-type=agent \
    --identity-type=agent-identity \
    --no-traffic

    Remplacez les éléments suivants :

    • SERVICE_NAME: nom de votre service Cloud Run.
    • ORGANIZATION_ID : ID de votre Google Cloud organisation.
    • PROJECT_NUMBER : votre Google Cloud projet numéro.
    • REGION: région dans laquelle votre service est déployé.

  • Pour déployer un serveur MCP géré par l'utilisateur, spécifiez --functional-type=mcp-server. Vous pouvez éventuellement spécifier un type d'identité à l'aide de --identity-type :

    gcloud beta run deploy SERVICE_NAME \
    --image=IMAGE_URL \
    --functional-type=mcp-server \
    --identity-type=IDENTITY_TYPE

    Remplacez les éléments suivants :

    • SERVICE_NAME: nom de votre service Cloud Run.
    • IMAGE_URL: référence à l'image de conteneur, par exemple us-docker.pkg.dev/cloudrun/container/hello:latest. Si vous utilisez Artifact Registry, le dépôt REPO_NAME doit déjà être créé. L'URL suit le format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • IDENTITY_TYPE : facultatif. Type d'identité attribué à la charge de travail. Spécifiez agent-identity ou service-account. La valeur par défaut est service-account.

Jobs

  • Pour créer une tâche d'agent, spécifiez --functional-type=agent et --identity-type=agent-identity :

    gcloud beta run jobs create JOB_NAME \
  --image=IMAGE_URL \
  --functional-type=agent \
  --identity-type=agent-identity

    Remplacez les éléments suivants :

    • JOB_NAME: nom de votre tâche Cloud Run.
    • IMAGE_URL : référence à l'image de conteneur.

Afficher les identités attribuées

Vous pouvez afficher l'identité d'agent attribuée à partir de la Google Cloud console ou gcloud CLI.

Services

Console

  1. Dans la Google Cloud console, accédez à Cloud Run :

    Accédez à Cloud Run

  2. Sélectionnez Services dans le menu de navigation Cloud Run, puis cliquez sur votre service.

  3. Cliquez sur l'onglet Révisions , puis sélectionnez une révision.

  4. Cliquez sur l'onglet Sécurité.

Le champ Identité affiche l'identité d'agent attribuée.

gcloud

Pour afficher l'identité de l'agent, décrivez la révision de votre service :

gcloud beta run revisions describe REVISION_NAME

Remplacez REVISION_NAME par le nom de la révision de votre service.

L'identité d'agent attribuée s'affiche dans le résultat.

Jobs

Console

  1. Dans la Google Cloud console, accédez à Cloud Run :

    Accédez à Cloud Run

  2. Sélectionnez Tâches dans le menu de navigation Cloud Run, puis cliquez sur votre tâche.

  3. Cliquez sur l'onglet Exécutions , puis sélectionnez une exécution.

  4. Affichez les détails de l'exécution.

Le champ Identité affiche l'identité d'agent attribuée.

gcloud

Pour afficher l'identité de l'agent pour une exécution de tâche, décrivez l'exécution :

gcloud beta run jobs executions describe EXECUTION_NAME

Remplacez EXECUTION_NAME par le nom de l'exécution de votre tâche.

L'identité d'agent attribuée s'affiche dans le résultat.

Afficher un agent ou un MCP dans Agent Registry

Lorsque vous déployez une ressource Cloud Run avec --functional-type=agent ou --functional-type=mcp-server, elle est automatiquement enregistrée dans le registre d'agents de votre organisation.

  • Les agents sont enregistrés dans le catalogue d'agents (/agents).
  • Les serveurs MCP sont enregistrés dans le catalogue de serveurs MCP (/mcpServers).

Pour afficher vos agents et outils enregistrés dans le registre, et pour savoir comment les stocker et les découvrir de manière sécurisée, explorez Agent Registry.

Étape suivante