Utiliser l'enregistrement automatique

Agent Registry peut enregistrer les agents hébergés sur des environnements d'exécution compatibles Google Cloud sans que vous ayez à appeler manuellement l' API Agent Registry. Selon l'environnement d'exécution, ce processus d'enregistrement est automatique ou nécessite une étape de configuration d'activation lors du déploiement.

Ce document explique comment activer la détection des agents sur les environnements d'exécution compatibles. Si vous hébergez un agent en externe ou sur un environnement d'exécution non compatible, consultez Utiliser l'enregistrement manuel.

Les métadonnées et les fonctionnalités indexées pour un agent lors de l'enregistrement dépendent de l'implémentation ou non du protocole Agent2Agent (A2A) par l'agent. Pour en savoir plus, consultez Enregistrer des agents.

Avant de commencer

Avant d'enregistrer des agents, configurez Agent Registry. Vous avez besoin de l'ID de votre projet pour valider l'enregistrement.

Pour utiliser les commandes Google Cloud CLI de ce document, assurez-vous d'avoir configuré votre environnement gcloud CLI.

Enregistrer des agents à partir d'Agent Runtime

Si vous développez et déployez des agents avec Agent Runtime sur Gemini Enterprise Agent Platform, l'enregistrement dans Agent Registry est automatique.

Le protocole Agent2Agent (A2A) est une norme ouverte qui permet aux agents de déclarer leurs fonctionnalités et leur identité. L'exemple suivant montre comment déployer un agent implémentant le protocole A2A dans Agent Runtime. Pour en savoir plus, consultez Déployer un agent.

# Create and deploy the agent
# This action automatically registers the agent in Agent Registry
remote_agent = client.agent_engines.create(
    agent=my_a2a_agent, # Your defined A2A object
    config={
        "display_name": "my-support-agent",
        "description": "An agent that handles support tickets.",
        "requirements": ["google-cloud-aiplatform[agent_engines,langchain]"],
    },
)

Lorsque vous mettez à jour ou supprimez votre agent dans Agent Runtime, Agent Registry synchronise automatiquement ces modifications.

Enregistrer des agents Google intégrés

Les agents Google intégrés, tels que Google Workspace et Gemini Enterprise agents, sont automatiquement enregistrés dans Agent Registry. Vous n'avez pas besoin d'effectuer d'étape de configuration ni de déploiement. Ces agents sont ingérés et disponibles pour la détection dans votre registre.

Enregistrer des agents à partir de GKE

Vous pouvez enregistrer les agents déployés sur Google Kubernetes Engine (GKE) en ajoutant le libellé registry.gke.io/functional-type: "AGENT" à vos déploiements. Ce libellé identifie le déploiement comme une charge de travail d'agent IA, ce qui indique au contrôleur d'exécution du cluster GKE d'effectuer une analyse d'introspection dans le cluster et d'enregistrer l'agent auprès d'Agent Registry.

Pour activer la détection automatisée des compétences de l'agent, vous devez également fournir l'annotation a2a-protocol.org/agent-card. Le contrôleur d'ingestion GKE utilise cette annotation pour interroger la carte d'agent A2A.

L'exemple suivant montre un fichier manifeste de déploiement d'agent GKE utilisant ces configurations. Pour en savoir plus, consultez Déployer et orchestrer des agents IA.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-agent
  labels:
    # GKE takes this label and registers the agent to Agent Registry
    registry.gke.io/functional-type: "AGENT"
  annotations:
    # A2A protocol metadata annotation for automated Agent Card discovery
    a2a-protocol.org/agent-card: |
      card:
        endpoint: /.well-known/agent-card.json
        protocol: HTTP
        port: 8080
spec:
  selector:
    matchLabels:
      app: my-agent
  template:
    metadata:
      labels:
        app: my-agent
    spec:
      containers:
      - name: server
        image: gcr.io/my-project/my-agent:1.0.0
        ports:
        - containerPort: 8080
        env:
        - name: PORT
          value: "8080"
---
apiVersion: v1
kind: Service
metadata:
  name: my-agent-service
  labels:
    app: my-agent
spec:
  type: ClusterIP
  ports:
  - port: 8080
    targetPort: 8080
    protocol: TCP
    name: http
  selector:
    app: my-agent

Lorsque le déploiement est appliqué, le contrôleur d'exécution du cluster GKE effectue automatiquement une introspection du conteneur de charge de travail, interroge le point de terminaison de la carte d'agent déclaré dans l'annotation et synchronise les métadonnées de l'agent et les compétences A2A directement dans le modèle de données Agent Registry.

Enregistrer des agents à partir de Cloud Run

Vous pouvez enregistrer les agents déployés sur Cloud Run en spécifiant les --functional-type=agent et --identity-type=agent-identity options lors du déploiement. L'option --functional-type=agent identifie la charge de travail Cloud Run comme un agent IA plutôt que comme une application conteneurisée standard, ce qui indique à Cloud Run d'enregistrer l'agent auprès d'Agent Registry.

Les charges de travail configurées avec --functional-type=agent doivent spécifier l'option --identity-type=agent-identity. Le déploiement avec tout autre type d'identité entraîne une erreur.

Vous pouvez déployer des agents en tant que services ou tâches Cloud Run. Pour savoir comment déployer un agent en tant que service ou tâche dans Cloud Run, consultez Configurer les fonctionnalités d'Agent Platform pour Cloud Run.

Lors de l'enregistrement, Cloud Run ajoute automatiquement le nom, le point de terminaison URL et le type (AGENT) de l'agent au registre. Pour en savoir plus sur le déploiement d'agents A2A sur Cloud Run, consultez Déployer des agents A2A sur Cloud Run.

L'enregistrement automatique ne détecte que les ressources déployées dans le même Google Cloud projet. Pour enregistrer des agents déployés dans différents projets, consultez Enregistrement manuel.

Valider l'enregistrement

Vous pouvez vérifier qu'Agent Registry a bien enregistré vos agents en les listant :

Console

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

    Accéder à Agent Registry

  2. Dans l'outil de sélection de projets, sélectionnez le Google Cloud projet dans lequel vous avez configuré Agent Registry.

  3. Sélectionnez l'onglet Agents.

    La page affiche la liste de tous les agents enregistrés et leurs détails, tels que le nom, l'identifiant, la description, l'environnement d'exécution et l'emplacement.

  4. Filtrez la liste par emplacement de l'agent ou par ressource d'exécution :

    • Pour filtrer par emplacement, cliquez sur le menu Emplacement, sélectionnez les emplacements que vous souhaitez filtrer, puis cliquez sur Appliquer.
    • Pour filtrer par environnement d'exécution, cliquez sur le menu Environnement d'exécution, sélectionnez les environnements d'exécution que vous souhaitez filtrer, puis cliquez sur Appliquer.

    La page affiche une liste filtrée des agents enregistrés pour les conditions sélectionnées.

gcloud

Vous pouvez filtrer la liste par métadonnées de l'agent. Assurez-vous d'avoir configuré votre environnement Google Cloud CLI pour Agent Registry, puis exécutez la commande suivante :

gcloud agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION \
  --filter="FILTER_EXPRESSION"

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet.
  • REGION : région du registre.
  • FILTER_EXPRESSION: expression de filtre pour les agents que vous souhaitez filtrer. Par exemple, pour filtrer par nom à afficher, vous pouvez utiliser displayName='DISPLAY_NAME'. Pour filtrer par l' identifiant unique global (URN), vous pouvez utiliser agentId='urn:agent:AGENT_URN'.

Les agents Google intégrés utilisent un format URN qui dépend de l'endroit où l'agent est déployé. Par exemple, vous pouvez découvrir les agents Google Workspace intégrés en filtrant votre liste pour l'éditeur googleapis.com à l'aide de --filter="agentId:'urn:agent:googleapis.com:*'".

Terraform

Référencez votre agent enregistré dans d'autres configurations Terraform à l'aide de la source de données google_agent_registry_agent :

data "google_agent_registry_agent" "my_agent" {
  location = "REGION"
  filter = "displayName=\"DISPLAY_NAME\""
}

output "agent_urn" {
  value = data.google_agent_registry_agent.my_agent.urn
}

Remplacez les éléments suivants :

  • REGION : région du registre.
  • DISPLAY_NAME: nom à afficher de l'agent, lisible par l'humain.