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

Les fonctionnalités de Gemini Enterprise Agent Platform, comme l'identité de l'agent et Agent Registry, offrent des fonctionnalités intégrées pour créer, déployer et gérer des agents d'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 agentiques.

Ce guide vous explique comment :

Cloud Run est compatible avec les fonctionnalités suivantes de la plate-forme d'agents :

  • Agent Identity : attribue une identité unique et cryptographiquement vérifiable à votre charge de travail, ce qui permet 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. Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

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

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

  4. Installez la Google Cloud CLI.

  5. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

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

    gcloud init

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

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

  9. Installez la Google Cloud CLI.

  10. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

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

    gcloud init

  12. Activez les API Cloud Run Admin, Identity and Access Management, Agent Registry et App Hub, si certaines ne sont pas déjà activées.

    Rôles requis pour activer les API

    Pour activer les API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation grâce au rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation grâce au rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

    Activer les API

  13. Assurez-vous d'avoir configuré l'Agent Registry dans votre projet ou votre organisation.
  14. Installez et initialisez la gcloud CLI.
  15. Mettez à jour les composants : 
    gcloud components update
  16. Consultez la page des tarifs de Cloud Run pour connaître les coûts associés au processeur, à la mémoire et à 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 API  Google Cloud à 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 règle 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 la manière d'enregistrer et d'identifier une charge de travail :

  • Type fonctionnel : déclare l'objectif principal de la charge de travail. Une fois définie, 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 agent d'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éfinie, 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 fonctionnalité, mettez à jour votre service avec le flag --no-identity-certificate ou définissez l'annotation run.googleapis.com/identity-certificate-enabled: "false". Suivez le guide pour vous authentifier auprès des outils et 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, consultez Identité de l'agent.
    • 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 aucune valeur n'est spécifiée, la valeur par défaut est une identité de compte de service.
Non spécifié service-account La charge de travail s'exécute en tant que service ou job Cloud Run standard.

Configurer des fonctionnalités sur les services et les jobs

Vous configurez les fonctionnalités Agent Platform sur vos services et jobs 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 est au format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.

  • Pour mettre à jour un service existant afin qu'il utilise l'identité de l'agent :

    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 : l'ID de votre organisation Google Cloud.
    • PROJECT_NUMBER : numéro de votre projet Google Cloud .
    • 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 est au 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 un job 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 job Cloud Run.
    • IMAGE_URL : référence à l'image de conteneur.

Afficher les identités attribuées

Vous pouvez afficher l'identité de l'agent attribué dans la console Google Cloud ou la gcloud CLI.

Services

Console

  1. Dans la console Google Cloud , 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é de l'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é de l'agent attribué s'affiche dans le résultat.

Jobs

Console

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

    Accédez à Cloud Run

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

  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é de l'agent attribuée.

gcloud

Pour afficher l'identité de l'agent pour une exécution de job, 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 job.

L'identité de l'agent attribué s'affiche dans le résultat.

Afficher un agent ou un serveur 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 des 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, consultez Agent Registry.

Étapes suivantes